icuSources/i18n/unicode/udatpg.h

   1 /*
   2 *******************************************************************************
   3 *
   4 *   Copyright (C) 2007-2015, 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 unusedDtpg     a pointer to UDateTimePatternGenerator.
 269   *    This parameter is no longer used. Callers may pass NULL.
 270   * @param pattern  input pattern, such as "dd/MMM".
 271   * @param length   the length of pattern.
 272   * @param skeleton such as "MMMdd"
 273   * @param capacity the capacity of skeleton.
 274   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 275   *                  failure before the function call.
 276   * @return the length of skeleton.
 277   * @stable ICU 3.8
 278   */
 279 U_STABLE int32_t U_EXPORT2
 280 udatpg_getSkeleton(UDateTimePatternGenerator *unusedDtpg,
 281                    const UChar *pattern, int32_t length,
 282                    UChar *skeleton, int32_t capacity,
 283                    UErrorCode *pErrorCode);
 284
 285 /**
 286  * Get a unique base skeleton from a given pattern. This is the same
 287  * as the skeleton, except that differences in length are minimized so
 288  * as to only preserve the difference between string and numeric form. So
 289  * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
 290  * (notice the single d).
 291  *
 292  * Note that this function uses a non-const UDateTimePatternGenerator:
 293  * It uses a stateful pattern parser which is set up for each generator object,
 294  * rather than creating one for each function call.
 295  * Consecutive calls to this function do not affect each other,
 296  * but this function cannot be used concurrently on a single generator object.
 297  *
 298  * @param unusedDtpg     a pointer to UDateTimePatternGenerator.
 299  *    This parameter is no longer used. Callers may pass NULL.
 300  * @param pattern  input pattern, such as "dd/MMM".
 301  * @param length   the length of pattern.
 302  * @param baseSkeleton such as "Md"
 303  * @param capacity the capacity of base skeleton.
 304  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 305  *                  failure before the function call.
 306  * @return the length of baseSkeleton.
 307  * @stable ICU 3.8
 308  */
 309 U_STABLE int32_t U_EXPORT2
 310 udatpg_getBaseSkeleton(UDateTimePatternGenerator *unusedDtpg,
 311                        const UChar *pattern, int32_t length,
 312                        UChar *baseSkeleton, int32_t capacity,
 313                        UErrorCode *pErrorCode);
 314
 315 /**
 316  * Adds a pattern to the generator. If the pattern has the same skeleton as
 317  * an existing pattern, and the override parameter is set, then the previous
 318  * value is overriden. Otherwise, the previous value is retained. In either
 319  * case, the conflicting status is set and previous vale is stored in
 320  * conflicting pattern.
 321  * <p>
 322  * Note that single-field patterns (like "MMM") are automatically added, and
 323  * don't need to be added explicitly!
 324  *
 325  * @param dtpg     a pointer to UDateTimePatternGenerator.
 326  * @param pattern  input pattern, such as "dd/MMM"
 327  * @param patternLength the length of pattern.
 328  * @param override  When existing values are to be overridden use true,
 329  *                  otherwise use false.
 330  * @param conflictingPattern  Previous pattern with the same skeleton.
 331  * @param capacity the capacity of conflictingPattern.
 332  * @param pLength a pointer to the length of conflictingPattern.
 333  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 334  *                  failure before the function call.
 335  * @return conflicting status. The value could be UDATPG_NO_CONFLICT,
 336  *                  UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
 337  * @stable ICU 3.8
 338  */
 339 U_STABLE UDateTimePatternConflict U_EXPORT2
 340 udatpg_addPattern(UDateTimePatternGenerator *dtpg,
 341                   const UChar *pattern, int32_t patternLength,
 342                   UBool override,
 343                   UChar *conflictingPattern, int32_t capacity, int32_t *pLength,
 344                   UErrorCode *pErrorCode);
 345
 346 /**
 347   * An AppendItem format is a pattern used to append a field if there is no
 348   * good match. For example, suppose that the input skeleton is "GyyyyMMMd",
 349   * and there is no matching pattern internally, but there is a pattern
 350   * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the
 351   * G. The way these two are conjoined is by using the AppendItemFormat for G
 352   * (era). So if that value is, say "{0}, {1}" then the final resulting
 353   * pattern is "d-MM-yyyy, G".
 354   * <p>
 355   * There are actually three available variables: {0} is the pattern so far,
 356   * {1} is the element we are adding, and {2} is the name of the element.
 357   * <p>
 358   * This reflects the way that the CLDR data is organized.
 359   *
 360   * @param dtpg   a pointer to UDateTimePatternGenerator.
 361   * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 362   * @param value  pattern, such as "{0}, {1}"
 363   * @param length the length of value.
 364   * @stable ICU 3.8
 365   */
 366 U_STABLE void U_EXPORT2
 367 udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg,
 368                            UDateTimePatternField field,
 369                            const UChar *value, int32_t length);
 370
 371 /**
 372  * Getter corresponding to setAppendItemFormat. Values below 0 or at or
 373  * above UDATPG_FIELD_COUNT are illegal arguments.
 374  *
 375  * @param dtpg   A pointer to UDateTimePatternGenerator.
 376  * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 377  * @param pLength A pointer that will receive the length of appendItemFormat.
 378  * @return appendItemFormat for field.
 379  * @stable ICU 3.8
 380  */
 381 U_STABLE const UChar * U_EXPORT2
 382 udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg,
 383                            UDateTimePatternField field,
 384                            int32_t *pLength);
 385
 386 /**
 387    * Set the name of field, eg "era" in English for ERA. These are only
 388    * used if the corresponding AppendItemFormat is used, and if it contains a
 389    * {2} variable.
 390    * <p>
 391    * This reflects the way that the CLDR data is organized.
 392    *
 393    * @param dtpg   a pointer to UDateTimePatternGenerator.
 394    * @param field  UDateTimePatternField
 395    * @param value  name for the field.
 396    * @param length the length of value.
 397    * @stable ICU 3.8
 398    */
 399 U_STABLE void U_EXPORT2
 400 udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg,
 401                          UDateTimePatternField field,
 402                          const UChar *value, int32_t length);
 403
 404 /**
 405  * Getter corresponding to setAppendItemNames. Values below 0 or at or above
 406  * UDATPG_FIELD_COUNT are illegal arguments.
 407  *
 408  * @param dtpg   a pointer to UDateTimePatternGenerator.
 409  * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 410  * @param pLength A pointer that will receive the length of the name for field.
 411  * @return name for field
 412  * @stable ICU 3.8
 413  */
 414 U_STABLE const UChar * U_EXPORT2
 415 udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg,
 416                          UDateTimePatternField field,
 417                          int32_t *pLength);
 418
 419 /**
 420  * The DateTimeFormat is a message format pattern used to compose date and
 421  * time patterns. The default pattern in the root locale is "{1} {0}", where
 422  * {1} will be replaced by the date pattern and {0} will be replaced by the
 423  * time pattern; however, other locales may specify patterns such as
 424  * "{1}, {0}" or "{1} 'at' {0}", etc.
 425  * <p>
 426  * This is used when the input skeleton contains both date and time fields,
 427  * but there is not a close match among the added patterns. For example,
 428  * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
 429  * its DateTimeFormat is the default "{1} {0}". Then if the input skeleton
 430  * is "MMMdhmm", there is not an exact match, so the input skeleton is
 431  * broken up into two components "MMMd" and "hmm". There are close matches
 432  * for those two skeletons, so the result is put together with this pattern,
 433  * resulting in "d-MMM h:mm".
 434  *
 435  * @param dtpg a pointer to UDateTimePatternGenerator.
 436  * @param dtFormat
 437  *            message format pattern, here {1} will be replaced by the date
 438  *            pattern and {0} will be replaced by the time pattern.
 439  * @param length the length of dtFormat.
 440  * @stable ICU 3.8
 441  */
 442 U_STABLE void U_EXPORT2
 443 udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg,
 444                          const UChar *dtFormat, int32_t length);
 445
 446 /**
 447  * Getter corresponding to setDateTimeFormat.
 448  * @param dtpg   a pointer to UDateTimePatternGenerator.
 449  * @param pLength A pointer that will receive the length of the format
 450  * @return dateTimeFormat.
 451  * @stable ICU 3.8
 452  */
 453 U_STABLE const UChar * U_EXPORT2
 454 udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg,
 455                          int32_t *pLength);
 456
 457 /**
 458  * The decimal value is used in formatting fractions of seconds. If the
 459  * skeleton contains fractional seconds, then this is used with the
 460  * fractional seconds. For example, suppose that the input pattern is
 461  * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
 462  * the decimal string is ",". Then the resulting pattern is modified to be
 463  * "H:mm:ss,SSSS"
 464  *
 465  * @param dtpg a pointer to UDateTimePatternGenerator.
 466  * @param decimal
 467  * @param length the length of decimal.
 468  * @stable ICU 3.8
 469  */
 470 U_STABLE void U_EXPORT2
 471 udatpg_setDecimal(UDateTimePatternGenerator *dtpg,
 472                   const UChar *decimal, int32_t length);
 473
 474 /**
 475  * Getter corresponding to setDecimal.
 476  *
 477  * @param dtpg a pointer to UDateTimePatternGenerator.
 478  * @param pLength A pointer that will receive the length of the decimal string.
 479  * @return corresponding to the decimal point.
 480  * @stable ICU 3.8
 481  */
 482 U_STABLE const UChar * U_EXPORT2
 483 udatpg_getDecimal(const UDateTimePatternGenerator *dtpg,
 484                   int32_t *pLength);
 485
 486 /**
 487  * Adjusts the field types (width and subtype) of a pattern to match what is
 488  * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
 489  * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
 490  * "dd-MMMM hh:mm". This is used internally to get the best match for the
 491  * input skeleton, but can also be used externally.
 492  *
 493  * Note that this function uses a non-const UDateTimePatternGenerator:
 494  * It uses a stateful pattern parser which is set up for each generator object,
 495  * rather than creating one for each function call.
 496  * Consecutive calls to this function do not affect each other,
 497  * but this function cannot be used concurrently on a single generator object.
 498  *
 499  * @param dtpg a pointer to UDateTimePatternGenerator.
 500  * @param pattern Input pattern
 501  * @param patternLength the length of input pattern.
 502  * @param skeleton
 503  * @param skeletonLength the length of input skeleton.
 504  * @param dest  pattern adjusted to match the skeleton fields widths and subtypes.
 505  * @param destCapacity the capacity of dest.
 506  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 507  *                  failure before the function call.
 508  * @return the length of dest.
 509  * @stable ICU 3.8
 510  */
 511 U_STABLE int32_t U_EXPORT2
 512 udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg,
 513                          const UChar *pattern, int32_t patternLength,
 514                          const UChar *skeleton, int32_t skeletonLength,
 515                          UChar *dest, int32_t destCapacity,
 516                          UErrorCode *pErrorCode);
 517
 518 /**
 519  * Adjusts the field types (width and subtype) of a pattern to match what is
 520  * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
 521  * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
 522  * "dd-MMMM hh:mm". This is used internally to get the best match for the
 523  * input skeleton, but can also be used externally.
 524  *
 525  * Note that this function uses a non-const UDateTimePatternGenerator:
 526  * It uses a stateful pattern parser which is set up for each generator object,
 527  * rather than creating one for each function call.
 528  * Consecutive calls to this function do not affect each other,
 529  * but this function cannot be used concurrently on a single generator object.
 530  *
 531  * @param dtpg a pointer to UDateTimePatternGenerator.
 532  * @param pattern Input pattern
 533  * @param patternLength the length of input pattern.
 534  * @param skeleton
 535  * @param skeletonLength the length of input skeleton.
 536  * @param options
 537  *            Options controlling whether the length of specified fields in the
 538  *            pattern are adjusted to match those in the skeleton (when this
 539  *            would not happen otherwise). For default behavior, use
 540  *            UDATPG_MATCH_NO_OPTIONS.
 541  * @param dest  pattern adjusted to match the skeleton fields widths and subtypes.
 542  * @param destCapacity the capacity of dest.
 543  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 544  *                  failure before the function call.
 545  * @return the length of dest.
 546  * @stable ICU 4.4
 547  */
 548 U_STABLE int32_t U_EXPORT2
 549 udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg,
 550                                     const UChar *pattern, int32_t patternLength,
 551                                     const UChar *skeleton, int32_t skeletonLength,
 552                                     UDateTimePatternMatchOptions options,
 553                                     UChar *dest, int32_t destCapacity,
 554                                     UErrorCode *pErrorCode);
 555
 556 /**
 557  * Return a UEnumeration list of all the skeletons in canonical form.
 558  * Call udatpg_getPatternForSkeleton() to get the corresponding pattern.
 559  *
 560  * @param dtpg a pointer to UDateTimePatternGenerator.
 561  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 562  *                  failure before the function call
 563  * @return a UEnumeration list of all the skeletons
 564  *         The caller must close the object.
 565  * @stable ICU 3.8
 566  */
 567 U_STABLE UEnumeration * U_EXPORT2
 568 udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 569
 570 /**
 571  * Return a UEnumeration list of all the base skeletons in canonical form.
 572  *
 573  * @param dtpg a pointer to UDateTimePatternGenerator.
 574  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 575  *             failure before the function call.
 576  * @return a UEnumeration list of all the base skeletons
 577  *             The caller must close the object.
 578  * @stable ICU 3.8
 579  */
 580 U_STABLE UEnumeration * U_EXPORT2
 581 udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 582
 583 /**
 584  * Get the pattern corresponding to a given skeleton.
 585  *
 586  * @param dtpg a pointer to UDateTimePatternGenerator.
 587  * @param skeleton
 588  * @param skeletonLength pointer to the length of skeleton.
 589  * @param pLength pointer to the length of return pattern.
 590  * @return pattern corresponding to a given skeleton.
 591  * @stable ICU 3.8
 592  */
 593 U_STABLE const UChar * U_EXPORT2
 594 udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg,
 595                              const UChar *skeleton, int32_t skeletonLength,
 596                              int32_t *pLength);
 597
 598 /**
 599  * Remap a pattern per the options (Apple-specific for now).
 600  * Currently this will only remap the time to force an alternate time
 601  * cycle (12-hour instead of 24-hour or vice versa), handling updating
 602  * the pattern characters, insertion/removal of AM/PM marker, etc. in
 603  * a locale-appropriate way. It calls udatpg_getBestPatternWithOptions
 604  * as part of updating the time format.
 605  *
 606  * @param dtpg a pointer to UDateTimePatternGenerator.
 607  * @param pattern
 608  *            The pattern to remap.
 609  * @param patternLength
 610  *            The length of the pattern (may be -1 to indicate that it
 611  *            is zero-terminated).
 612  * @param options
 613  *            Options for forcing the hour cycle and for forcing the
 614  *            length of specified fields in the
 615  *            returned pattern to match those in the skeleton (when this
 616  *            would not happen otherwise). For default behavior, use
 617  *            UDATPG_MATCH_NO_OPTIONS.
 618  * @param newPattern
 619  *            The remapped pattern.
 620  * @param newPatternCapacity
 621  *            The capacity of newPattern.
 622  * @param pErrorCode
 623  *            A pointer to the UErrorCode. If at entry it indicates a
 624  *            failure, the call will return immediately.
 625  * @return
 626  *            The length of newPattern. If this is greater than
 627  *            newPatternCapacity an error will be set and the contents of
 628  *            newPattern are undefined.
 629  * @internal
 630  */
 631 U_INTERNAL int32_t U_EXPORT2
 632 uadatpg_remapPatternWithOptions(UDateTimePatternGenerator *dtpg,
 633                                 const UChar *pattern, int32_t patternLength,
 634                                 UDateTimePatternMatchOptions options,
 635                                 UChar *newPattern, int32_t newPatternCapacity,
 636                                 UErrorCode *pErrorCode);
 637
 638 #endif