icuSources/i18n/unicode/udatpg.h

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