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/udat.h" 24 #include "unicode/uenum.h" 25 26 #if U_SHOW_CPLUSPLUS_API 27 #include "unicode/localpointer.h" 28 #endif // U_SHOW_CPLUSPLUS_API 29 30 /** 31 * \file 32 * \brief C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h). 33 * 34 * UDateTimePatternGenerator provides flexible generation of date format patterns, 35 * like "yy-MM-dd". The user can build up the generator by adding successive 36 * patterns. Once that is done, a query can be made using a "skeleton", which is 37 * a pattern which just includes the desired fields and lengths. The generator 38 * will return the "best fit" pattern corresponding to that skeleton. 39 * <p>The main method people will use is udatpg_getBestPattern, since normally 40 * UDateTimePatternGenerator is pre-built with data from a particular locale. 41 * However, generators can be built directly from other data as well. 42 * <p><i>Issue: may be useful to also have a function that returns the list of 43 * fields in a pattern, in order, since we have that internally. 44 * That would be useful for getting the UI order of field elements.</i> 45 */ 46 47 /** 48 * Opaque type for a date/time pattern generator object. 49 * @stable ICU 3.8 50 */ 51 typedef void *UDateTimePatternGenerator; 52 53 /** 54 * Field number constants for udatpg_getAppendItemFormats() and similar functions. 55 * These constants are separate from UDateFormatField despite semantic overlap 56 * because some fields are merged for the date/time pattern generator. 57 * @stable ICU 3.8 58 */ 59 typedef enum UDateTimePatternField { 60 /** @stable ICU 3.8 */ 61 UDATPG_ERA_FIELD, 62 /** @stable ICU 3.8 */ 63 UDATPG_YEAR_FIELD, 64 /** @stable ICU 3.8 */ 65 UDATPG_QUARTER_FIELD, 66 /** @stable ICU 3.8 */ 67 UDATPG_MONTH_FIELD, 68 /** @stable ICU 3.8 */ 69 UDATPG_WEEK_OF_YEAR_FIELD, 70 /** @stable ICU 3.8 */ 71 UDATPG_WEEK_OF_MONTH_FIELD, 72 /** @stable ICU 3.8 */ 73 UDATPG_WEEKDAY_FIELD, 74 /** @stable ICU 3.8 */ 75 UDATPG_DAY_OF_YEAR_FIELD, 76 /** @stable ICU 3.8 */ 77 UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD, 78 /** @stable ICU 3.8 */ 79 UDATPG_DAY_FIELD, 80 /** @stable ICU 3.8 */ 81 UDATPG_DAYPERIOD_FIELD, 82 /** @stable ICU 3.8 */ 83 UDATPG_HOUR_FIELD, 84 /** @stable ICU 3.8 */ 85 UDATPG_MINUTE_FIELD, 86 /** @stable ICU 3.8 */ 87 UDATPG_SECOND_FIELD, 88 /** @stable ICU 3.8 */ 89 UDATPG_FRACTIONAL_SECOND_FIELD, 90 /** @stable ICU 3.8 */ 91 UDATPG_ZONE_FIELD, 92 93 /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, 94 * it is needed for layout of DateTimePatternGenerator object. */ 95 #ifndef U_FORCE_HIDE_DEPRECATED_API 96 /** 97 * One more than the highest normal UDateTimePatternField value. 98 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 99 */ 100 UDATPG_FIELD_COUNT 101 #endif // U_FORCE_HIDE_DEPRECATED_API 102 } UDateTimePatternField; 103 104 /** 105 * Field display name width constants for udatpg_getFieldDisplayName(). 106 * @stable ICU 61 107 */ 108 typedef enum UDateTimePGDisplayWidth { 109 /** @stable ICU 61 */ 110 UDATPG_WIDE, 111 /** @stable ICU 61 */ 112 UDATPG_ABBREVIATED, 113 /** @stable ICU 61 */ 114 UDATPG_NARROW 115 } UDateTimePGDisplayWidth; 116 117 /** 118 * Masks to control forcing the length of specified fields in the returned 119 * pattern to match those in the skeleton (when this would not happen 120 * otherwise). These may be combined to force the length of multiple fields. 121 * Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions. 122 * @stable ICU 4.4 123 */ 124 typedef enum UDateTimePatternMatchOptions { 125 /** @stable ICU 4.4 */ 126 UDATPG_MATCH_NO_OPTIONS = 0, 127 /** @stable ICU 4.4 */ 128 UDATPG_MATCH_HOUR_FIELD_LENGTH = 1 << UDATPG_HOUR_FIELD, 129 #ifndef U_HIDE_INTERNAL_API 130 /** @internal ICU 4.4 */ 131 UDATPG_MATCH_MINUTE_FIELD_LENGTH = 1 << UDATPG_MINUTE_FIELD, 132 /** @internal ICU 4.4 */ 133 UDATPG_MATCH_SECOND_FIELD_LENGTH = 1 << UDATPG_SECOND_FIELD, 134 #endif /* U_HIDE_INTERNAL_API */ 135 /** @stable ICU 4.4 */ 136 UDATPG_MATCH_ALL_FIELDS_LENGTH = (1 << UDATPG_FIELD_COUNT) - 1 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_CAPI 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_CAPI 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_CAPI 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 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI const UChar * U_EXPORT2 654 udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg, 655 const UChar *skeleton, int32_t skeletonLength, 656 int32_t *pLength); 657 658 #if !UCONFIG_NO_FORMATTING 659 660 #ifndef U_HIDE_DRAFT_API 661 /** 662 * Return the default hour cycle for a locale. Uses the locale that the 663 * UDateTimePatternGenerator was initially created with. 664 * 665 * Cannot be used on an empty UDateTimePatternGenerator instance. 666 * 667 * @param dtpg a pointer to UDateTimePatternGenerator. 668 * @param pErrorCode a pointer to the UErrorCode which must not indicate a 669 * failure before the function call. Set to U_UNSUPPORTED_ERROR 670 * if used on an empty instance. 671 * @return the default hour cycle. 672 * @draft ICU 67 673 */ 674 U_CAPI UDateFormatHourCycle U_EXPORT2 675 udatpg_getDefaultHourCycle(const UDateTimePatternGenerator *dtpg, UErrorCode* pErrorCode); 676 #endif /* U_HIDE_DRAFT_API */ 677 678 #endif /* #if !UCONFIG_NO_FORMATTING */ 679 680 #endif 681