icuSources/i18n/unicode/udatpg.h

   1 /*
   2 *******************************************************************************
   3 *
   4 *   Copyright (C) 2007-2008, 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
  23 /**
  24  * \file
  25  * \brief C API: Wrapper for DateTimePatternGenerator (unicode/dtptngen.h).
  26  *
  27  * UDateTimePatternGenerator provides flexible generation of date format patterns,
  28  * like "yy-MM-dd". The user can build up the generator by adding successive
  29  * patterns. Once that is done, a query can be made using a "skeleton", which is
  30  * a pattern which just includes the desired fields and lengths. The generator
  31  * will return the "best fit" pattern corresponding to that skeleton.
  32  * <p>The main method people will use is udatpg_getBestPattern, since normally
  33  * UDateTimePatternGenerator is pre-built with data from a particular locale.
  34  * However, generators can be built directly from other data as well.
  35  * <p><i>Issue: may be useful to also have a function that returns the list of
  36  * fields in a pattern, in order, since we have that internally.
  37  * That would be useful for getting the UI order of field elements.</i>
  38  */
  39
  40 /**
  41  * Opaque type for a date/time pattern generator object.
  42  * @stable ICU 4.0
  43  */
  44 typedef void *UDateTimePatternGenerator;
  45
  46 /**
  47  * Field number constants for udatpg_getAppendItemFormats() and similar functions.
  48  * These constants are separate from UDateFormatField despite semantic overlap
  49  * because some fields are merged for the date/time pattern generator.
  50  * @stable ICU 4.0
  51  */
  52 typedef enum UDateTimePatternField {
  53     /** @stable ICU 4.0 */
  54     UDATPG_ERA_FIELD,
  55     /** @stable ICU 4.0 */
  56     UDATPG_YEAR_FIELD,
  57     /** @stable ICU 4.0 */
  58     UDATPG_QUARTER_FIELD,
  59     /** @stable ICU 4.0 */
  60     UDATPG_MONTH_FIELD,
  61     /** @stable ICU 4.0 */
  62     UDATPG_WEEK_OF_YEAR_FIELD,
  63     /** @stable ICU 4.0 */
  64     UDATPG_WEEK_OF_MONTH_FIELD,
  65     /** @stable ICU 4.0 */
  66     UDATPG_WEEKDAY_FIELD,
  67     /** @stable ICU 4.0 */
  68     UDATPG_DAY_OF_YEAR_FIELD,
  69     /** @stable ICU 4.0 */
  70     UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD,
  71     /** @stable ICU 4.0 */
  72     UDATPG_DAY_FIELD,
  73     /** @stable ICU 4.0 */
  74     UDATPG_DAYPERIOD_FIELD,
  75     /** @stable ICU 4.0 */
  76     UDATPG_HOUR_FIELD,
  77     /** @stable ICU 4.0 */
  78     UDATPG_MINUTE_FIELD,
  79     /** @stable ICU 4.0 */
  80     UDATPG_SECOND_FIELD,
  81     /** @stable ICU 4.0 */
  82     UDATPG_FRACTIONAL_SECOND_FIELD,
  83     /** @stable ICU 4.0 */
  84     UDATPG_ZONE_FIELD,
  85     /** @stable ICU 4.0 */
  86     UDATPG_FIELD_COUNT
  87 } UDateTimePatternField;
  88
  89 /**
  90  * Status return values from udatpg_addPattern().
  91  * @stable ICU 4.0
  92  */
  93 typedef enum UDateTimePatternConflict {
  94     /** @stable ICU 4.0 */
  95     UDATPG_NO_CONFLICT,
  96     /** @stable ICU 4.0 */
  97     UDATPG_BASE_CONFLICT,
  98     /** @stable ICU 4.0 */
  99     UDATPG_CONFLICT,
 100     /** @stable ICU 4.0 */
 101     UDATPG_CONFLICT_COUNT
 102 } UDateTimePatternConflict;
 103
 104 /**
 105   * Open a generator according to a given locale.
 106   * @param locale
 107   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 108   *                   failure before the function call.
 109   * @return a pointer to UDateTimePatternGenerator.
 110   * @stable ICU 4.0
 111   */
 112 U_DRAFT UDateTimePatternGenerator * U_EXPORT2
 113 udatpg_open(const char *locale, UErrorCode *pErrorCode);
 114
 115 /**
 116   * Open an empty generator, to be constructed with udatpg_addPattern(...) etc.
 117   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 118   *                   failure before the function call.
 119   * @return a pointer to UDateTimePatternGenerator.
 120   * @stable ICU 4.0
 121   */
 122 U_DRAFT UDateTimePatternGenerator * U_EXPORT2
 123 udatpg_openEmpty(UErrorCode *pErrorCode);
 124
 125 /**
 126   * Close a generator.
 127   * @param dtpg a pointer to UDateTimePatternGenerator.
 128   * @stable ICU 4.0
 129   */
 130 U_DRAFT void U_EXPORT2
 131 udatpg_close(UDateTimePatternGenerator *dtpg);
 132
 133 /**
 134   * Create a copy pf a generator.
 135   * @param dtpg a pointer to UDateTimePatternGenerator to be copied.
 136   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 137   *                   failure before the function call.
 138   * @return a pointer to a new UDateTimePatternGenerator.
 139   * @stable ICU 4.0
 140  */
 141 U_DRAFT UDateTimePatternGenerator * U_EXPORT2
 142 udatpg_clone(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 143
 144 /**
 145  * Get the best pattern matching the input skeleton. It is guaranteed to
 146  * have all of the fields in the skeleton.
 147  *
 148  * Note that this function uses a non-const UDateTimePatternGenerator:
 149  * It uses a stateful pattern parser which is set up for each generator object,
 150  * rather than creating one for each function call.
 151  * Consecutive calls to this function do not affect each other,
 152  * but this function cannot be used concurrently on a single generator object.
 153  *
 154  * @param dtpg a pointer to UDateTimePatternGenerator.
 155  * @param skeleton
 156  *            The skeleton is a pattern containing only the variable fields.
 157  *            For example, "MMMdd" and "mmhh" are skeletons.
 158  * @param length the length of skeleton
 159  * @param bestPattern
 160  *            The best pattern found from the given skeleton.
 161  * @param capacity the capacity of bestPattern.
 162  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 163  *                   failure before the function call.
 164  * @return the length of bestPattern.
 165  * @stable ICU 4.0
 166  */
 167 U_DRAFT int32_t U_EXPORT2
 168 udatpg_getBestPattern(UDateTimePatternGenerator *dtpg,
 169                       const UChar *skeleton, int32_t length,
 170                       UChar *bestPattern, int32_t capacity,
 171                       UErrorCode *pErrorCode);
 172
 173 /**
 174   * Get a unique skeleton from a given pattern. For example,
 175   * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
 176   *
 177   * Note that this function uses a non-const UDateTimePatternGenerator:
 178   * It uses a stateful pattern parser which is set up for each generator object,
 179   * rather than creating one for each function call.
 180   * Consecutive calls to this function do not affect each other,
 181   * but this function cannot be used concurrently on a single generator object.
 182   *
 183   * @param dtpg     a pointer to UDateTimePatternGenerator.
 184   * @param pattern  input pattern, such as "dd/MMM".
 185   * @param length   the length of pattern.
 186   * @param skeleton such as "MMMdd"
 187   * @param capacity the capacity of skeleton.
 188   * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 189   *                  failure before the function call.
 190   * @return the length of skeleton.
 191   * @stable ICU 4.0
 192   */
 193 U_DRAFT int32_t U_EXPORT2
 194 udatpg_getSkeleton(UDateTimePatternGenerator *dtpg,
 195                    const UChar *pattern, int32_t length,
 196                    UChar *skeleton, int32_t capacity,
 197                    UErrorCode *pErrorCode);
 198
 199 /**
 200  * Get a unique base skeleton from a given pattern. This is the same
 201  * as the skeleton, except that differences in length are minimized so
 202  * as to only preserve the difference between string and numeric form. So
 203  * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
 204  * (notice the single d).
 205  *
 206  * Note that this function uses a non-const UDateTimePatternGenerator:
 207  * It uses a stateful pattern parser which is set up for each generator object,
 208  * rather than creating one for each function call.
 209  * Consecutive calls to this function do not affect each other,
 210  * but this function cannot be used concurrently on a single generator object.
 211  *
 212  * @param dtpg     a pointer to UDateTimePatternGenerator.
 213  * @param pattern  input pattern, such as "dd/MMM".
 214  * @param length   the length of pattern.
 215  * @param baseSkeleton such as "Md"
 216  * @param capacity the capacity of base skeleton.
 217  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 218  *                  failure before the function call.
 219  * @return the length of baseSkeleton.
 220  * @stable ICU 4.0
 221  */
 222 U_DRAFT int32_t U_EXPORT2
 223 udatpg_getBaseSkeleton(UDateTimePatternGenerator *dtpg,
 224                        const UChar *pattern, int32_t length,
 225                        UChar *baseSkeleton, int32_t capacity,
 226                        UErrorCode *pErrorCode);
 227
 228 /**
 229  * Adds a pattern to the generator. If the pattern has the same skeleton as
 230  * an existing pattern, and the override parameter is set, then the previous
 231  * value is overriden. Otherwise, the previous value is retained. In either
 232  * case, the conflicting status is set and previous vale is stored in
 233  * conflicting pattern.
 234  * <p>
 235  * Note that single-field patterns (like "MMM") are automatically added, and
 236  * don't need to be added explicitly!
 237  *
 238  * @param dtpg     a pointer to UDateTimePatternGenerator.
 239  * @param pattern  input pattern, such as "dd/MMM"
 240  * @param patternLength the length of pattern.
 241  * @param override  When existing values are to be overridden use true,
 242  *                  otherwise use false.
 243  * @param conflictingPattern  Previous pattern with the same skeleton.
 244  * @param capacity the capacity of conflictingPattern.
 245  * @param pLength a pointer to the length of conflictingPattern.
 246  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 247  *                  failure before the function call.
 248  * @return conflicting status. The value could be UDATPG_NO_CONFLICT,
 249  *                  UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
 250  * @stable ICU 4.0
 251  */
 252 U_DRAFT UDateTimePatternConflict U_EXPORT2
 253 udatpg_addPattern(UDateTimePatternGenerator *dtpg,
 254                   const UChar *pattern, int32_t patternLength,
 255                   UBool override,
 256                   UChar *conflictingPattern, int32_t capacity, int32_t *pLength,
 257                   UErrorCode *pErrorCode);
 258
 259 /**
 260   * An AppendItem format is a pattern used to append a field if there is no
 261   * good match. For example, suppose that the input skeleton is "GyyyyMMMd",
 262   * and there is no matching pattern internally, but there is a pattern
 263   * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the
 264   * G. The way these two are conjoined is by using the AppendItemFormat for G
 265   * (era). So if that value is, say "{0}, {1}" then the final resulting
 266   * pattern is "d-MM-yyyy, G".
 267   * <p>
 268   * There are actually three available variables: {0} is the pattern so far,
 269   * {1} is the element we are adding, and {2} is the name of the element.
 270   * <p>
 271   * This reflects the way that the CLDR data is organized.
 272   *
 273   * @param dtpg   a pointer to UDateTimePatternGenerator.
 274   * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 275   * @param value  pattern, such as "{0}, {1}"
 276   * @param length the length of value.
 277   * @stable ICU 4.0
 278   */
 279 U_DRAFT void U_EXPORT2
 280 udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg,
 281                            UDateTimePatternField field,
 282                            const UChar *value, int32_t length);
 283
 284 /**
 285  * Getter corresponding to setAppendItemFormat. Values below 0 or at or
 286  * above UDATPG_FIELD_COUNT are illegal arguments.
 287  *
 288  * @param dtpg   A pointer to UDateTimePatternGenerator.
 289  * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 290  * @param pLength A pointer that will receive the length of appendItemFormat.
 291  * @return appendItemFormat for field.
 292  * @stable ICU 4.0
 293  */
 294 U_DRAFT const UChar * U_EXPORT2
 295 udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg,
 296                            UDateTimePatternField field,
 297                            int32_t *pLength);
 298
 299 /**
 300    * Set the name of field, eg "era" in English for ERA. These are only
 301    * used if the corresponding AppendItemFormat is used, and if it contains a
 302    * {2} variable.
 303    * <p>
 304    * This reflects the way that the CLDR data is organized.
 305    *
 306    * @param dtpg   a pointer to UDateTimePatternGenerator.
 307    * @param field  UDateTimePatternField
 308    * @param value  name for the field.
 309    * @param length the length of value.
 310    * @stable ICU 4.0
 311    */
 312 U_DRAFT void U_EXPORT2
 313 udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg,
 314                          UDateTimePatternField field,
 315                          const UChar *value, int32_t length);
 316
 317 /**
 318  * Getter corresponding to setAppendItemNames. Values below 0 or at or above
 319  * UDATPG_FIELD_COUNT are illegal arguments.
 320  *
 321  * @param dtpg   a pointer to UDateTimePatternGenerator.
 322  * @param field  UDateTimePatternField, such as UDATPG_ERA_FIELD
 323  * @param pLength A pointer that will receive the length of the name for field.
 324  * @return name for field
 325  * @stable ICU 4.0
 326  */
 327 U_DRAFT const UChar * U_EXPORT2
 328 udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg,
 329                          UDateTimePatternField field,
 330                          int32_t *pLength);
 331
 332 /**
 333  * The date time format is a message format pattern used to compose date and
 334  * time patterns. The default value is "{0} {1}", where {0} will be replaced
 335  * by the date pattern and {1} will be replaced by the time pattern.
 336  * <p>
 337  * This is used when the input skeleton contains both date and time fields,
 338  * but there is not a close match among the added patterns. For example,
 339  * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
 340  * its datetimeFormat is the default "{0} {1}". Then if the input skeleton
 341  * is "MMMdhmm", there is not an exact match, so the input skeleton is
 342  * broken up into two components "MMMd" and "hmm". There are close matches
 343  * for those two skeletons, so the result is put together with this pattern,
 344  * resulting in "d-MMM h:mm".
 345  *
 346  * @param dtpg a pointer to UDateTimePatternGenerator.
 347  * @param dtFormat
 348  *            message format pattern, here {0} will be replaced by the date
 349  *            pattern and {1} will be replaced by the time pattern.
 350  * @param length the length of dtFormat.
 351  * @stable ICU 4.0
 352  */
 353 U_DRAFT void U_EXPORT2
 354 udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg,
 355                          const UChar *dtFormat, int32_t length);
 356
 357 /**
 358  * Getter corresponding to setDateTimeFormat.
 359  * @param dtpg   a pointer to UDateTimePatternGenerator.
 360  * @param pLength A pointer that will receive the length of the format
 361  * @return dateTimeFormat.
 362  * @stable ICU 4.0
 363  */
 364 U_DRAFT const UChar * U_EXPORT2
 365 udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg,
 366                          int32_t *pLength);
 367
 368 /**
 369  * The decimal value is used in formatting fractions of seconds. If the
 370  * skeleton contains fractional seconds, then this is used with the
 371  * fractional seconds. For example, suppose that the input pattern is
 372  * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
 373  * the decimal string is ",". Then the resulting pattern is modified to be
 374  * "H:mm:ss,SSSS"
 375  *
 376  * @param dtpg a pointer to UDateTimePatternGenerator.
 377  * @param decimal
 378  * @param length the length of decimal.
 379  * @stable ICU 4.0
 380  */
 381 U_DRAFT void U_EXPORT2
 382 udatpg_setDecimal(UDateTimePatternGenerator *dtpg,
 383                   const UChar *decimal, int32_t length);
 384
 385 /**
 386  * Getter corresponding to setDecimal.
 387  *
 388  * @param dtpg a pointer to UDateTimePatternGenerator.
 389  * @param pLength A pointer that will receive the length of the decimal string.
 390  * @return corresponding to the decimal point.
 391  * @stable ICU 4.0
 392  */
 393 U_DRAFT const UChar * U_EXPORT2
 394 udatpg_getDecimal(const UDateTimePatternGenerator *dtpg,
 395                   int32_t *pLength);
 396
 397 /**
 398  * Adjusts the field types (width and subtype) of a pattern to match what is
 399  * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
 400  * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
 401  * "dd-MMMM hh:mm". This is used internally to get the best match for the
 402  * input skeleton, but can also be used externally.
 403  *
 404  * Note that this function uses a non-const UDateTimePatternGenerator:
 405  * It uses a stateful pattern parser which is set up for each generator object,
 406  * rather than creating one for each function call.
 407  * Consecutive calls to this function do not affect each other,
 408  * but this function cannot be used concurrently on a single generator object.
 409  *
 410  * @param dtpg a pointer to UDateTimePatternGenerator.
 411  * @param pattern Input pattern
 412  * @param patternLength the length of input pattern.
 413  * @param skeleton
 414  * @param skeletonLength the length of input skeleton.
 415  * @param dest  pattern adjusted to match the skeleton fields widths and subtypes.
 416  * @param destCapacity the capacity of dest.
 417  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 418  *                  failure before the function call.
 419  * @return the length of dest.
 420  * @stable ICU 4.0
 421  */
 422 U_DRAFT int32_t U_EXPORT2
 423 udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg,
 424                          const UChar *pattern, int32_t patternLength,
 425                          const UChar *skeleton, int32_t skeletonLength,
 426                          UChar *dest, int32_t destCapacity,
 427                          UErrorCode *pErrorCode);
 428
 429 /**
 430  * Return a UEnumeration list of all the skeletons in canonical form.
 431  * Call udatpg_getPatternForSkeleton() to get the corresponding pattern.
 432  *
 433  * @param dtpg a pointer to UDateTimePatternGenerator.
 434  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 435  *                  failure before the function call
 436  * @return a UEnumeration list of all the skeletons
 437  *         The caller must close the object.
 438  * @stable ICU 4.0
 439  */
 440 U_DRAFT UEnumeration * U_EXPORT2
 441 udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 442
 443 /**
 444  * Return a UEnumeration list of all the base skeletons in canonical form.
 445  *
 446  * @param dtpg a pointer to UDateTimePatternGenerator.
 447  * @param pErrorCode a pointer to the UErrorCode which must not indicate a
 448  *             failure before the function call.
 449  * @return a UEnumeration list of all the base skeletons
 450  *             The caller must close the object.
 451  * @stable ICU 4.0
 452  */
 453 U_DRAFT UEnumeration * U_EXPORT2
 454 udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
 455
 456 /**
 457  * Get the pattern corresponding to a given skeleton.
 458  *
 459  * @param dtpg a pointer to UDateTimePatternGenerator.
 460  * @param skeleton
 461  * @param skeletonLength pointer to the length of skeleton.
 462  * @param pLength pointer to the length of return pattern.
 463  * @return pattern corresponding to a given skeleton.
 464  * @stable ICU 4.0
 465  */
 466 U_DRAFT const UChar * U_EXPORT2
 467 udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg,
 468                              const UChar *skeleton, int32_t skeletonLength,
 469                              int32_t *pLength);
 470
 471 #endif