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