udatpg.h (30851B)
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 overridden. 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 * There are four DateTimeFormats in a UDateTimePatternGenerator object, 496 * corresponding to date styles UDAT_FULL..UDAT_SHORT. This method sets 497 * all of them to the specified pattern. To set them individually, see 498 * udatpg_setDateTimeFormatForStyle. 499 * 500 * @param dtpg a pointer to UDateTimePatternGenerator. 501 * @param dtFormat 502 * message format pattern, here {1} will be replaced by the date 503 * pattern and {0} will be replaced by the time pattern. 504 * @param length the length of dtFormat. 505 * @stable ICU 3.8 506 */ 507 U_CAPI void U_EXPORT2 508 udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg, 509 const UChar *dtFormat, int32_t length); 510 511 /** 512 * Getter corresponding to setDateTimeFormat. 513 * 514 * There are four DateTimeFormats in a UDateTimePatternGenerator object, 515 * corresponding to date styles UDAT_FULL..UDAT_SHORT. This method gets 516 * the style for UDAT_MEDIUM (the default). To get them individually, see 517 * udatpg_getDateTimeFormatForStyle. 518 * 519 * @param dtpg a pointer to UDateTimePatternGenerator. 520 * @param pLength A pointer that will receive the length of the format 521 * @return dateTimeFormat. 522 * @stable ICU 3.8 523 */ 524 U_CAPI const UChar * U_EXPORT2 525 udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg, 526 int32_t *pLength); 527 528 #if !UCONFIG_NO_FORMATTING 529 /** 530 * dateTimeFormats are message patterns used to compose combinations of date 531 * and time patterns. There are four length styles, corresponding to the 532 * inferred style of the date pattern; these are UDateFormatStyle values: 533 * - UDAT_FULL (for date pattern with weekday and long month), else 534 * - UDAT_LONG (for a date pattern with long month), else 535 * - UDAT_MEDIUM (for a date pattern with abbreviated month), else 536 * - UDAT_SHORT (for any other date pattern). 537 * For details on dateTimeFormats, see 538 * https://www.unicode.org/reports/tr35/tr35-dates.html#dateTimeFormats. 539 * The default pattern in the root locale for all styles is "{1} {0}". 540 * 541 * @param udtpg 542 * a pointer to the UDateTimePatternGenerator 543 * @param style 544 * one of UDAT_FULL..UDAT_SHORT. Error if out of range. 545 * @param dateTimeFormat 546 * the new dateTimeFormat to set for the specified style 547 * @param length 548 * the length of dateTimeFormat, or -1 if unknown and pattern 549 * is null-terminated 550 * @param pErrorCode 551 * a pointer to the UErrorCode (in/out parameter); if no failure 552 * status is already set, it will be set according to result of the 553 * function (e.g. U_ILLEGAL_ARGUMENT_ERROR for style out of range). 554 * @stable ICU 71 555 */ 556 U_CAPI void U_EXPORT2 557 udatpg_setDateTimeFormatForStyle(UDateTimePatternGenerator *udtpg, 558 UDateFormatStyle style, 559 const UChar *dateTimeFormat, int32_t length, 560 UErrorCode *pErrorCode); 561 562 /** 563 * Getter corresponding to udatpg_setDateTimeFormatForStyle. 564 * 565 * @param udtpg 566 * a pointer to the UDateTimePatternGenerator 567 * @param style 568 * one of UDAT_FULL..UDAT_SHORT. Error if out of range. 569 * @param pLength 570 * a pointer that will receive the length of the format. May be NULL 571 * if length is not desired. 572 * @param pErrorCode 573 * a pointer to the UErrorCode (in/out parameter); if no failure 574 * status is already set, it will be set according to result of the 575 * function (e.g. U_ILLEGAL_ARGUMENT_ERROR for style out of range). 576 * @return 577 * pointer to the current dateTimeFormat (0 terminated) for the specified 578 * style, or empty string in case of error. The pointer and its contents 579 * may no longer be valid if udatpg_setDateTimeFormat is called, or 580 * udatpg_setDateTimeFormatForStyle for the same style is called, or the 581 * UDateTimePatternGenerator object is closed. 582 * @stable ICU 71 583 */ 584 U_CAPI const UChar* U_EXPORT2 585 udatpg_getDateTimeFormatForStyle(const UDateTimePatternGenerator *udtpg, 586 UDateFormatStyle style, int32_t *pLength, 587 UErrorCode *pErrorCode); 588 #endif /* #if !UCONFIG_NO_FORMATTING */ 589 590 /** 591 * The decimal value is used in formatting fractions of seconds. If the 592 * skeleton contains fractional seconds, then this is used with the 593 * fractional seconds. For example, suppose that the input pattern is 594 * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and 595 * the decimal string is ",". Then the resulting pattern is modified to be 596 * "H:mm:ss,SSSS" 597 * 598 * @param dtpg a pointer to UDateTimePatternGenerator. 599 * @param decimal 600 * @param length the length of decimal. 601 * @stable ICU 3.8 602 */ 603 U_CAPI void U_EXPORT2 604 udatpg_setDecimal(UDateTimePatternGenerator *dtpg, 605 const UChar *decimal, int32_t length); 606 607 /** 608 * Getter corresponding to setDecimal. 609 * 610 * @param dtpg a pointer to UDateTimePatternGenerator. 611 * @param pLength A pointer that will receive the length of the decimal string. 612 * @return corresponding to the decimal point. 613 * @stable ICU 3.8 614 */ 615 U_CAPI const UChar * U_EXPORT2 616 udatpg_getDecimal(const UDateTimePatternGenerator *dtpg, 617 int32_t *pLength); 618 619 /** 620 * Adjusts the field types (width and subtype) of a pattern to match what is 621 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a 622 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be 623 * "dd-MMMM hh:mm". This is used internally to get the best match for the 624 * input skeleton, but can also be used externally. 625 * 626 * Note that this function uses a non-const UDateTimePatternGenerator: 627 * It uses a stateful pattern parser which is set up for each generator object, 628 * rather than creating one for each function call. 629 * Consecutive calls to this function do not affect each other, 630 * but this function cannot be used concurrently on a single generator object. 631 * 632 * @param dtpg a pointer to UDateTimePatternGenerator. 633 * @param pattern Input pattern 634 * @param patternLength the length of input pattern. 635 * @param skeleton 636 * @param skeletonLength the length of input skeleton. 637 * @param dest pattern adjusted to match the skeleton fields widths and subtypes. 638 * @param destCapacity the capacity of dest. 639 * @param pErrorCode a pointer to the UErrorCode which must not indicate a 640 * failure before the function call. 641 * @return the length of dest. 642 * @stable ICU 3.8 643 */ 644 U_CAPI int32_t U_EXPORT2 645 udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg, 646 const UChar *pattern, int32_t patternLength, 647 const UChar *skeleton, int32_t skeletonLength, 648 UChar *dest, int32_t destCapacity, 649 UErrorCode *pErrorCode); 650 651 /** 652 * Adjusts the field types (width and subtype) of a pattern to match what is 653 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a 654 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be 655 * "dd-MMMM hh:mm". This is used internally to get the best match for the 656 * input skeleton, but can also be used externally. 657 * 658 * Note that this function uses a non-const UDateTimePatternGenerator: 659 * It uses a stateful pattern parser which is set up for each generator object, 660 * rather than creating one for each function call. 661 * Consecutive calls to this function do not affect each other, 662 * but this function cannot be used concurrently on a single generator object. 663 * 664 * @param dtpg a pointer to UDateTimePatternGenerator. 665 * @param pattern Input pattern 666 * @param patternLength the length of input pattern. 667 * @param skeleton 668 * @param skeletonLength the length of input skeleton. 669 * @param options 670 * Options controlling whether the length of specified fields in the 671 * pattern are adjusted to match those in the skeleton (when this 672 * would not happen otherwise). For default behavior, use 673 * UDATPG_MATCH_NO_OPTIONS. 674 * @param dest pattern adjusted to match the skeleton fields widths and subtypes. 675 * @param destCapacity the capacity of dest. 676 * @param pErrorCode a pointer to the UErrorCode which must not indicate a 677 * failure before the function call. 678 * @return the length of dest. 679 * @stable ICU 4.4 680 */ 681 U_CAPI int32_t U_EXPORT2 682 udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg, 683 const UChar *pattern, int32_t patternLength, 684 const UChar *skeleton, int32_t skeletonLength, 685 UDateTimePatternMatchOptions options, 686 UChar *dest, int32_t destCapacity, 687 UErrorCode *pErrorCode); 688 689 /** 690 * Return a UEnumeration list of all the skeletons in canonical form. 691 * Call udatpg_getPatternForSkeleton() to get the corresponding pattern. 692 * 693 * @param dtpg a pointer to UDateTimePatternGenerator. 694 * @param pErrorCode a pointer to the UErrorCode which must not indicate a 695 * failure before the function call 696 * @return a UEnumeration list of all the skeletons 697 * The caller must close the object. 698 * @stable ICU 3.8 699 */ 700 U_CAPI UEnumeration * U_EXPORT2 701 udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); 702 703 /** 704 * Return a UEnumeration list of all the base skeletons in canonical form. 705 * 706 * @param dtpg a pointer to UDateTimePatternGenerator. 707 * @param pErrorCode a pointer to the UErrorCode which must not indicate a 708 * failure before the function call. 709 * @return a UEnumeration list of all the base skeletons 710 * The caller must close the object. 711 * @stable ICU 3.8 712 */ 713 U_CAPI UEnumeration * U_EXPORT2 714 udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); 715 716 /** 717 * Get the pattern corresponding to a given skeleton. 718 * 719 * @param dtpg a pointer to UDateTimePatternGenerator. 720 * @param skeleton 721 * @param skeletonLength pointer to the length of skeleton. 722 * @param pLength pointer to the length of return pattern. 723 * @return pattern corresponding to a given skeleton. 724 * @stable ICU 3.8 725 */ 726 U_CAPI const UChar * U_EXPORT2 727 udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg, 728 const UChar *skeleton, int32_t skeletonLength, 729 int32_t *pLength); 730 731 #if !UCONFIG_NO_FORMATTING 732 733 /** 734 * Return the default hour cycle for a locale. Uses the locale that the 735 * UDateTimePatternGenerator was initially created with. 736 * 737 * Cannot be used on an empty UDateTimePatternGenerator instance. 738 * 739 * @param dtpg a pointer to UDateTimePatternGenerator. 740 * @param pErrorCode a pointer to the UErrorCode which must not indicate a 741 * failure before the function call. Set to U_UNSUPPORTED_ERROR 742 * if used on an empty instance. 743 * @return the default hour cycle. 744 * @stable ICU 67 745 */ 746 U_CAPI UDateFormatHourCycle U_EXPORT2 747 udatpg_getDefaultHourCycle(const UDateTimePatternGenerator *dtpg, UErrorCode* pErrorCode); 748 749 #endif /* #if !UCONFIG_NO_FORMATTING */ 750 751 #endif