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