icuSources/i18n/unicode/udatpg.h

   1 /*
   2 *******************************************************************************
   3 *
   4 *   Copyright (C) 2007-2012,2014 International Business Machines
   5 *   Corporation and others.  All Rights Reserved.
   6 *
   7 *******************************************************************************
   8 *   file name:  udatpg.h
   9 *   encoding:   US-ASCII
  10 *   tab size:   8 (not used)
  11 *   indentation:4
  12 *
  13 *   created on: 2007jul30
  14 *   created by: Markus W. Scherer
  15 */
  16
  17 #ifndef __UDATPG_H__
  18 #define __UDATPG_H__
  19
  20 #include "unicode/utypes.h"
  21 #include "unicode/uenum.h"
  22 #include "unicode/localpointer.h"
  23
  24 /**
  25  * \file
  26  * \brief C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h).
  27  *
  28  * UDateTimePatternGenerator provides flexible generation of date format patterns,
  29  * like "yy-MM-dd". The user can build up the generator by adding successive
  30  * patterns. Once that is done, a query can be made using a "skeleton", which is
  31  * a pattern which just includes the desired fields and lengths. The generator
  32  * will return the "best fit" pattern corresponding to that skeleton.
  33  * <p>The main method people will use is udatpg_getBestPattern, since normally
  34  * UDateTimePatternGenerator is pre-built with data from a particular locale.
  35  * However, generators can be built directly from other data as well.
  36  * <p><i>Issue: may be useful to also have a function that returns the list of
  37  * fields in a pattern, in order, since we have that internally.
  38  * That would be useful for getting the UI order of field elements.</i>
  39  */
  40
  41 /**
  42  * Opaque type for a date/time pattern generator object.
  43  * @stable ICU 3.8
  44  */
  45 typedef void *UDateTimePatternGenerator;
  46
  47 /**
  48  * Field number constants for udatpg_getAppendItemFormats() and similar functions.
  49  * These constants are separate from UDateFormatField despite semantic overlap
  50  * because some fields are merged for the date/time pattern generator.
  51  * @stable ICU 3.8
  52  */
  53 typedef enum UDateTimePatternField {
  54     /** @stable ICU 3.8 */
  55     UDATPG_ERA_FIELD,
  56     /** @stable ICU 3.8 */
  57     UDATPG_YEAR_FIELD,
  58     /** @stable ICU 3.8 */
  59     UDATPG_QUARTER_FIELD,
  60     /** @stable ICU 3.8 */
  61     UDATPG_MONTH_FIELD,
  62     /** @stable ICU 3.8 */
  63     UDATPG_WEEK_OF_YEAR_FIELD,
  64     /** @stable ICU 3.8 */
  65     UDATPG_WEEK_OF_MONTH_FIELD,
  66     /** @stable ICU 3.8 */
  67     UDATPG_WEEKDAY_FIELD,
  68     /** @stable ICU 3.8 */
  69     UDATPG_DAY_OF_YEAR_FIELD,
  70     /** @stable ICU 3.8 */
  71     UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD,
  72     /** @stable ICU 3.8 */
  73     UDATPG_DAY_FIELD,
  74     /** @stable ICU 3.8 */
  75     UDATPG_DAYPERIOD_FIELD,
  76     /** @stable ICU 3.8 */
  77     UDATPG_HOUR_FIELD,
  78     /** @stable ICU 3.8 */
  79     UDATPG_MINUTE_FIELD,
  80     /** @stable ICU 3.8 */
  81     UDATPG_SECOND_FIELD,
  82     /** @stable ICU 3.8 */
  83     UDATPG_FRACTIONAL_SECOND_FIELD,
  84     /** @stable ICU 3.8 */
  85     UDATPG_ZONE_FIELD,
  86     /** @stable ICU 3.8 */
  87     UDATPG_FIELD_COUNT
  88 } UDateTimePatternField;
  89
  90 /**
  91  * Masks to control forcing the length of specified fields in the returned
  92  * pattern to match those in the skeleton (when this would not happen
  93  * otherwise). These may be combined to force the length of multiple fields.
  94  * Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions.
  95  * @stable ICU 4.4
  96  */
  97 typedef enum UDateTimePatternMatchOptions {
  98     /** @stable ICU 4.4 */
  99     UDATPG_MATCH_NO_OPTIONS = 0,
 100     /** @stable ICU 4.4 */
 101     UDATPG_MATCH_HOUR_FIELD_LENGTH = 1 << UDATPG_HOUR_FIELD,
 102 #ifndef U_HIDE_INTERNAL_API
 103     /** @internal ICU 4.4 */
 104     UDATPG_MATCH_MINUTE_FIELD_LENGTH = 1 << UDATPG_MINUTE_FIELD,
 105     /** @internal ICU 4.4 */
 106     UDATPG_MATCH_SECOND_FIELD_LENGTH = 1 << UDATPG_SECOND_FIELD,
 107 #endif  /* U_HIDE_INTERNAL_API */
 108     /** @stable ICU 4.4 */
 109     UDATPG_MATCH_ALL_FIELDS_LENGTH = (1 << UDATPG_FIELD_COUNT) - 1,
 110     /** @internal, Apple-specific for now */
 111     UADATPG_FORCE_12_HOUR_CYCLE = 1 << 29,
 112     /** @internal, Apple-specific for now */
 113     UADATPG_FORCE_24_HOUR_CYCLE = 1 << 30,
 114     /** @internal, Apple-specific for now */
 115     UADATPG_FORCE_HOUR_CYCLE_MASK = 3 << 29,
 116 } UDateTimePatternMatchOptions;
 117
 118 /**
 119  * Status return values from udatpg_addPattern().
 120  * @stable ICU 3.8
 121  */
 122 typedef enum UDateTimePatternConflict {
 123     /** @stable ICU 3.8 */
 124     UDATPG_NO_CONFLICT,
 125     /** @stable ICU 3.8 */
 126     UDATPG_BASE_CONFLICT,
 127     /** @stable ICU 3.8 */
 128     UDATPG_CONFLICT,
 129     /** @stable ICU 3.8 */
 130     UDATPG_CONFLICT_COUNT
 131 } UDateTimePatternConflict;
 132
 133 /**
 134   * Open a generator according to a given locale.
 135   * @param locale
 136   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 137   *                   failure before the function call.
 138   * @return a pointer to UDateTimePatternGenerator.
 139   * @stable ICU 3.8
 140   */
 141 U_STABLE UDateTimePatternGenerator * U_EXPORT2
 142 udatpg_open(const char *locale, UErrorCode *pErrorCode);
 143
 144 /**
 145   * Open an empty generator, to be constructed with udatpg_addPattern(...) etc.
 146   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 147   *                   failure before the function call.
 148   * @return a pointer to UDateTimePatternGenerator.
 149   * @stable ICU 3.8
 150   */
 151 U_STABLE UDateTimePatternGenerator * U_EXPORT2
 152 udatpg_openEmpty(UErrorCode *pErrorCode);
 153
 154 /**
 155   * Close a generator.
 156   * @param dtpg a pointer to UDateTimePatternGenerator.
 157   * @stable ICU 3.8
 158   */
 159 U_STABLE void U_EXPORT2
 160 udatpg_close(UDateTimePatternGenerator *dtpg);
 161
 162 #if U_SHOW_CPLUSPLUS_API
 163
 164 U_NAMESPACE_BEGIN
 165
 166 /**
 167  * \class LocalUDateTimePatternGeneratorPointer
 168  * "Smart pointer" class, closes a UDateTimePatternGenerator via udatpg_close().
 169  * For most methods see the LocalPointerBase base class.
 170  *
 171  * @see LocalPointerBase
 172  * @see LocalPointer
 173  * @stable ICU 4.4
 174  */
 175 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateTimePatternGeneratorPointer, UDateTimePatternGenerator, udatpg_close);
 176
 177 U_NAMESPACE_END
 178
 179 #endif
 180
 181 /**
 182   * Create a copy pf a generator.
 183   * @param dtpg a pointer to UDateTimePatternGenerator to be copied.
 184   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 185   *                   failure before the function call.
 186   * @return a pointer to a new UDateTimePatternGenerator.
 187   * @stable ICU 3.8
 188  */
 189 U_STABLE UDateTimePatternGenerator * U_EXPORT2
 190 udatpg_clone(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 191
 192 /**
 193  * Get the best pattern matching the input skeleton. It is guaranteed to
 194  * have all of the fields in the skeleton.
 195  *
 196  * Note that this function uses a non-const UDateTimePatternGenerator:
 197  * It uses a stateful pattern parser which is set up for each generator object,
 198  * rather than creating one for each function call.
 199  * Consecutive calls to this function do not affect each other,
 200  * but this function cannot be used concurrently on a single generator object.
 201  *
 202  * @param dtpg a pointer to UDateTimePatternGenerator.
 203  * @param skeleton
 204  *            The skeleton is a pattern containing only the variable fields.
 205  *            For example, "MMMdd" and "mmhh" are skeletons.
 206  * @param length the length of skeleton
 207  * @param bestPattern
 208  *            The best pattern found from the given skeleton.
 209  * @param capacity the capacity of bestPattern.
 210  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 211  *                   failure before the function call.
 212  * @return the length of bestPattern.
 213  * @stable ICU 3.8
 214  */
 215 U_STABLE int32_t U_EXPORT2
 216 udatpg_getBestPattern(UDateTimePatternGenerator *dtpg,
 217                       const UChar *skeleton, int32_t length,
 218                       UChar *bestPattern, int32_t capacity,
 219                       UErrorCode *pErrorCode);
 220
 221 /**
 222  * Get the best pattern matching the input skeleton. It is guaranteed to
 223  * have all of the fields in the skeleton.
 224  *
 225  * Note that this function uses a non-const UDateTimePatternGenerator:
 226  * It uses a stateful pattern parser which is set up for each generator object,
 227  * rather than creating one for each function call.
 228  * Consecutive calls to this function do not affect each other,
 229  * but this function cannot be used concurrently on a single generator object.
 230  *
 231  * @param dtpg a pointer to UDateTimePatternGenerator.
 232  * @param skeleton
 233  *            The skeleton is a pattern containing only the variable fields.
 234  *            For example, "MMMdd" and "mmhh" are skeletons.
 235  * @param length the length of skeleton
 236  * @param options
 237  *            Options for forcing the length of specified fields in the
 238  *            returned pattern to match those in the skeleton (when this
 239  *            would not happen otherwise). For default behavior, use
 240  *            UDATPG_MATCH_NO_OPTIONS.
 241  * @param bestPattern
 242  *            The best pattern found from the given skeleton.
 243  * @param capacity
 244  *            the capacity of bestPattern.
 245  * @param pErrorCode
 246  *            a pointer to the UErrorCode which must not indicate a
 247  *            failure before the function call.
 248  * @return the length of bestPattern.
 249  * @stable ICU 4.4
 250  */
 251 U_STABLE int32_t U_EXPORT2
 252 udatpg_getBestPatternWithOptions(UDateTimePatternGenerator *dtpg,
 253                                  const UChar *skeleton, int32_t length,
 254                                  UDateTimePatternMatchOptions options,
 255                                  UChar *bestPattern, int32_t capacity,
 256                                  UErrorCode *pErrorCode);
 257
 258 /**
 259   * Get a unique skeleton from a given pattern. For example,
 260   * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
 261   *
 262   * Note that this function uses a non-const UDateTimePatternGenerator:
 263   * It uses a stateful pattern parser which is set up for each generator object,
 264   * rather than creating one for each function call.
 265   * Consecutive calls to this function do not affect each other,
 266   * but this function cannot be used concurrently on a single generator object.
 267   *
 268   * @param dtpg     a pointer to UDateTimePatternGenerator.
 269   * @param pattern  input pattern, such as "dd/MMM".
 270   * @param length   the length of pattern.
 271   * @param skeleton such as "MMMdd"
 272   * @param capacity the capacity of skeleton.
 273   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 274   *                  failure before the function call.
 275   * @return the length of skeleton.
 276   * @stable ICU 3.8
 277   */
 278 U_STABLE int32_t U_EXPORT2
 279 udatpg_getSkeleton(UDateTimePatternGenerator *dtpg,
 280                    const UChar *pattern, int32_t length,
 281                    UChar *skeleton, int32_t capacity,
 282                    UErrorCode *pErrorCode);
 283
 284 /**
 285  * Get a unique base skeleton from a given pattern. This is the same
 286  * as the skeleton, except that differences in length are minimized so
 287  * as to only preserve the difference between string and numeric form. So
 288  * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
 289  * (notice the single d).
 290  *
 291  * Note that this function uses a non-const UDateTimePatternGenerator:
 292  * It uses a stateful pattern parser which is set up for each generator object,
 293  * rather than creating one for each function call.
 294  * Consecutive calls to this function do not affect each other,
 295  * but this function cannot be used concurrently on a single generator object.
 296  *
 297  * @param dtpg     a pointer to UDateTimePatternGenerator.
 298  * @param pattern  input pattern, such as "dd/MMM".
 299  * @param length   the length of pattern.
 300  * @param baseSkeleton such as "Md"
 301  * @param capacity the capacity of base skeleton.
 302  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 303  *                  failure before the function call.
 304  * @return the length of baseSkeleton.
 305  * @stable ICU 3.8
 306  */
 307 U_STABLE int32_t U_EXPORT2
 308 udatpg_getBaseSkeleton(UDateTimePatternGenerator *dtpg,
 309                        const UChar *pattern, int32_t length,
 310                        UChar *baseSkeleton, int32_t capacity,
 311                        UErrorCode *pErrorCode);
 312
 313 /**
 314  * Adds a pattern to the generator. If the pattern has the same skeleton as
 315  * an existing pattern, and the override parameter is set, then the previous
 316  * value is overriden. Otherwise, the previous value is retained. In either
 317  * case, the conflicting status is set and previous vale is stored in
 318  * conflicting pattern.
 319  * <p>
 320  * Note that single-field patterns (like "MMM") are automatically added, and
 321  * don't need to be added explicitly!
 322  *
 323  * @param dtpg     a pointer to UDateTimePatternGenerator.
 324  * @param pattern  input pattern, such as "dd/MMM"
 325  * @param patternLength the length of pattern.
 326  * @param override  When existing values are to be overridden use true,
 327  *                  otherwise use false.
 328  * @param conflictingPattern  Previous pattern with the same skeleton.
 329  * @param capacity the capacity of conflictingPattern.
 330  * @param pLength a pointer to the length of conflictingPattern.
 331  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 332  *                  failure before the function call.
 333  * @return conflicting status. The value could be UDATPG_NO_CONFLICT,
 334  *                  UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
 335  * @stable ICU 3.8
 336  */
 337 U_STABLE UDateTimePatternConflict U_EXPORT2
 338 udatpg_addPattern(UDateTimePatternGenerator *dtpg,
 339                   const UChar *pattern, int32_t patternLength,
 340                   UBool override,
 341                   UChar *conflictingPattern, int32_t capacity, int32_t *pLength,
 342                   UErrorCode *pErrorCode);
 343
 344 /**
 345   * An AppendItem format is a pattern used to append a field if there is no
 346   * good match. For example, suppose that the input skeleton is "GyyyyMMMd",
 347   * and there is no matching pattern internally, but there is a pattern
 348   * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the
 349   * G. The way these two are conjoined is by using the AppendItemFormat for G
 350   * (era). So if that value is, say "{0}, {1}" then the final resulting
 351   * pattern is "d-MM-yyyy, G".
 352   * <p>
 353   * There are actually three available variables: {0} is the pattern so far,
 354   * {1} is the element we are adding, and {2} is the name of the element.
 355   * <p>
 356   * This reflects the way that the CLDR data is organized.
 357   *
 358   * @param dtpg   a pointer to UDateTimePatternGenerator.
 359   * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 360   * @param value  pattern, such as "{0}, {1}"
 361   * @param length the length of value.
 362   * @stable ICU 3.8
 363   */
 364 U_STABLE void U_EXPORT2
 365 udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg,
 366                            UDateTimePatternField field,
 367                            const UChar *value, int32_t length);
 368
 369 /**
 370  * Getter corresponding to setAppendItemFormat. Values below 0 or at or
 371  * above UDATPG_FIELD_COUNT are illegal arguments.
 372  *
 373  * @param dtpg   A pointer to UDateTimePatternGenerator.
 374  * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 375  * @param pLength A pointer that will receive the length of appendItemFormat.
 376  * @return appendItemFormat for field.
 377  * @stable ICU 3.8
 378  */
 379 U_STABLE const UChar * U_EXPORT2
 380 udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg,
 381                            UDateTimePatternField field,
 382                            int32_t *pLength);
 383
 384 /**
 385    * Set the name of field, eg "era" in English for ERA. These are only
 386    * used if the corresponding AppendItemFormat is used, and if it contains a
 387    * {2} variable.
 388    * <p>
 389    * This reflects the way that the CLDR data is organized.
 390    *
 391    * @param dtpg   a pointer to UDateTimePatternGenerator.
 392    * @param field  UDateTimePatternField
 393    * @param value  name for the field.
 394    * @param length the length of value.
 395    * @stable ICU 3.8
 396    */
 397 U_STABLE void U_EXPORT2
 398 udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg,
 399                          UDateTimePatternField field,
 400                          const UChar *value, int32_t length);
 401
 402 /**
 403  * Getter corresponding to setAppendItemNames. Values below 0 or at or above
 404  * UDATPG_FIELD_COUNT are illegal arguments.
 405  *
 406  * @param dtpg   a pointer to UDateTimePatternGenerator.
 407  * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 408  * @param pLength A pointer that will receive the length of the name for field.
 409  * @return name for field
 410  * @stable ICU 3.8
 411  */
 412 U_STABLE const UChar * U_EXPORT2
 413 udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg,
 414                          UDateTimePatternField field,
 415                          int32_t *pLength);
 416
 417 /**
 418  * The date time format is a message format pattern used to compose date and
 419  * time patterns. The default value is "{0} {1}", where {0} will be replaced
 420  * by the date pattern and {1} will be replaced by the time pattern.
 421  * <p>
 422  * This is used when the input skeleton contains both date and time fields,
 423  * but there is not a close match among the added patterns. For example,
 424  * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
 425  * its datetimeFormat is the default "{0} {1}". Then if the input skeleton
 426  * is "MMMdhmm", there is not an exact match, so the input skeleton is
 427  * broken up into two components "MMMd" and "hmm". There are close matches
 428  * for those two skeletons, so the result is put together with this pattern,
 429  * resulting in "d-MMM h:mm".
 430  *
 431  * @param dtpg a pointer to UDateTimePatternGenerator.
 432  * @param dtFormat
 433  *            message format pattern, here {0} will be replaced by the date
 434  *            pattern and {1} will be replaced by the time pattern.
 435  * @param length the length of dtFormat.
 436  * @stable ICU 3.8
 437  */
 438 U_STABLE void U_EXPORT2
 439 udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg,
 440                          const UChar *dtFormat, int32_t length);
 441
 442 /**
 443  * Getter corresponding to setDateTimeFormat.
 444  * @param dtpg   a pointer to UDateTimePatternGenerator.
 445  * @param pLength A pointer that will receive the length of the format
 446  * @return dateTimeFormat.
 447  * @stable ICU 3.8
 448  */
 449 U_STABLE const UChar * U_EXPORT2
 450 udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg,
 451                          int32_t *pLength);
 452
 453 /**
 454  * The decimal value is used in formatting fractions of seconds. If the
 455  * skeleton contains fractional seconds, then this is used with the
 456  * fractional seconds. For example, suppose that the input pattern is
 457  * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
 458  * the decimal string is ",". Then the resulting pattern is modified to be
 459  * "H:mm:ss,SSSS"
 460  *
 461  * @param dtpg a pointer to UDateTimePatternGenerator.
 462  * @param decimal
 463  * @param length the length of decimal.
 464  * @stable ICU 3.8
 465  */
 466 U_STABLE void U_EXPORT2
 467 udatpg_setDecimal(UDateTimePatternGenerator *dtpg,
 468                   const UChar *decimal, int32_t length);
 469
 470 /**
 471  * Getter corresponding to setDecimal.
 472  *
 473  * @param dtpg a pointer to UDateTimePatternGenerator.
 474  * @param pLength A pointer that will receive the length of the decimal string.
 475  * @return corresponding to the decimal point.
 476  * @stable ICU 3.8
 477  */
 478 U_STABLE const UChar * U_EXPORT2
 479 udatpg_getDecimal(const UDateTimePatternGenerator *dtpg,
 480                   int32_t *pLength);
 481
 482 /**
 483  * Adjusts the field types (width and subtype) of a pattern to match what is
 484  * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
 485  * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
 486  * "dd-MMMM hh:mm". This is used internally to get the best match for the
 487  * input skeleton, but can also be used externally.
 488  *
 489  * Note that this function uses a non-const UDateTimePatternGenerator:
 490  * It uses a stateful pattern parser which is set up for each generator object,
 491  * rather than creating one for each function call.
 492  * Consecutive calls to this function do not affect each other,
 493  * but this function cannot be used concurrently on a single generator object.
 494  *
 495  * @param dtpg a pointer to UDateTimePatternGenerator.
 496  * @param pattern Input pattern
 497  * @param patternLength the length of input pattern.
 498  * @param skeleton
 499  * @param skeletonLength the length of input skeleton.
 500  * @param dest  pattern adjusted to match the skeleton fields widths and subtypes.
 501  * @param destCapacity the capacity of dest.
 502  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 503  *                  failure before the function call.
 504  * @return the length of dest.
 505  * @stable ICU 3.8
 506  */
 507 U_STABLE int32_t U_EXPORT2
 508 udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg,
 509                          const UChar *pattern, int32_t patternLength,
 510                          const UChar *skeleton, int32_t skeletonLength,
 511                          UChar *dest, int32_t destCapacity,
 512                          UErrorCode *pErrorCode);
 513
 514 /**
 515  * Adjusts the field types (width and subtype) of a pattern to match what is
 516  * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
 517  * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
 518  * "dd-MMMM hh:mm". This is used internally to get the best match for the
 519  * input skeleton, but can also be used externally.
 520  *
 521  * Note that this function uses a non-const UDateTimePatternGenerator:
 522  * It uses a stateful pattern parser which is set up for each generator object,
 523  * rather than creating one for each function call.
 524  * Consecutive calls to this function do not affect each other,
 525  * but this function cannot be used concurrently on a single generator object.
 526  *
 527  * @param dtpg a pointer to UDateTimePatternGenerator.
 528  * @param pattern Input pattern
 529  * @param patternLength the length of input pattern.
 530  * @param skeleton
 531  * @param skeletonLength the length of input skeleton.
 532  * @param options
 533  *            Options controlling whether the length of specified fields in the
 534  *            pattern are adjusted to match those in the skeleton (when this
 535  *            would not happen otherwise). For default behavior, use
 536  *            UDATPG_MATCH_NO_OPTIONS.
 537  * @param dest  pattern adjusted to match the skeleton fields widths and subtypes.
 538  * @param destCapacity the capacity of dest.
 539  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 540  *                  failure before the function call.
 541  * @return the length of dest.
 542  * @stable ICU 4.4
 543  */
 544 U_STABLE int32_t U_EXPORT2
 545 udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg,
 546                                     const UChar *pattern, int32_t patternLength,
 547                                     const UChar *skeleton, int32_t skeletonLength,
 548                                     UDateTimePatternMatchOptions options,
 549                                     UChar *dest, int32_t destCapacity,
 550                                     UErrorCode *pErrorCode);
 551
 552 /**
 553  * Return a UEnumeration list of all the skeletons in canonical form.
 554  * Call udatpg_getPatternForSkeleton() to get the corresponding pattern.
 555  *
 556  * @param dtpg a pointer to UDateTimePatternGenerator.
 557  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 558  *                  failure before the function call
 559  * @return a UEnumeration list of all the skeletons
 560  *         The caller must close the object.
 561  * @stable ICU 3.8
 562  */
 563 U_STABLE UEnumeration * U_EXPORT2
 564 udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 565
 566 /**
 567  * Return a UEnumeration list of all the base skeletons in canonical form.
 568  *
 569  * @param dtpg a pointer to UDateTimePatternGenerator.
 570  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 571  *             failure before the function call.
 572  * @return a UEnumeration list of all the base skeletons
 573  *             The caller must close the object.
 574  * @stable ICU 3.8
 575  */
 576 U_STABLE UEnumeration * U_EXPORT2
 577 udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 578
 579 /**
 580  * Get the pattern corresponding to a given skeleton.
 581  *
 582  * @param dtpg a pointer to UDateTimePatternGenerator.
 583  * @param skeleton
 584  * @param skeletonLength pointer to the length of skeleton.
 585  * @param pLength pointer to the length of return pattern.
 586  * @return pattern corresponding to a given skeleton.
 587  * @stable ICU 3.8
 588  */
 589 U_STABLE const UChar * U_EXPORT2
 590 udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg,
 591                              const UChar *skeleton, int32_t skeletonLength,
 592                              int32_t *pLength);
 593
 594 /**
 595  * Remap a pattern per the options (Apple-specific for now).
 596  * Currently this will only remap the time to force an alternate time
 597  * cycle (12-hour instead of 24-hour or vice versa), handling updating
 598  * the pattern characters, insertion/removal of AM/PM marker, etc. in
 599  * a locale-appropriate way. It calls udatpg_getBestPatternWithOptions
 600  * as part of updating the time format.
 601  *
 602  * @param dtpg a pointer to UDateTimePatternGenerator.
 603  * @param pattern
 604  *            The pattern to remap.
 605  * @param patternLength
 606  *            The length of the pattern (may be -1 to indicate that it
 607  *            is zero-terminated).
 608  * @param options
 609  *            Options for forcing the hour cycle and for forcing the
 610  *            length of specified fields in the
 611  *            returned pattern to match those in the skeleton (when this
 612  *            would not happen otherwise). For default behavior, use
 613  *            UDATPG_MATCH_NO_OPTIONS.
 614  * @param newPattern
 615  *            The remapped pattern.
 616  * @param newPatternCapacity
 617  *            The capacity of newPattern.
 618  * @param pErrorCode
 619  *            A pointer to the UErrorCode. If at entry it indicates a
 620  *            failure, the call will return immediately.
 621  * @return
 622  *            The length of newPattern. If this is greater than
 623  *            newPatternCapacity an error will be set and the contents of
 624  *            newPattern are undefined.
 625  * @internal
 626  */
 627 U_INTERNAL int32_t U_EXPORT2
 628 uadatpg_remapPatternWithOptions(UDateTimePatternGenerator *dtpg,
 629                                 const UChar *pattern, int32_t patternLength,
 630                                 UDateTimePatternMatchOptions options,
 631                                 UChar *newPattern, int32_t newPatternCapacity,
 632                                 UErrorCode *pErrorCode);
 633
 634 #endif