dtfmtsym.h (42021B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ******************************************************************************** 5 * Copyright (C) 1997-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ******************************************************************************** 8 * 9 * File DTFMTSYM.H 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 02/19/97 aliu Converted from java. 15 * 07/21/98 stephen Added getZoneIndex() 16 * Changed to match C++ conventions 17 ******************************************************************************** 18 */ 19 20 #ifndef DTFMTSYM_H 21 #define DTFMTSYM_H 22 23 #include "unicode/utypes.h" 24 25 #if U_SHOW_CPLUSPLUS_API 26 27 #if !UCONFIG_NO_FORMATTING 28 29 #include "unicode/calendar.h" 30 #include "unicode/strenum.h" 31 #include "unicode/uobject.h" 32 #include "unicode/locid.h" 33 #include "unicode/udat.h" 34 #include "unicode/ures.h" 35 36 /** 37 * \file 38 * \brief C++ API: Symbols for formatting dates. 39 */ 40 41 U_NAMESPACE_BEGIN 42 43 /* forward declaration */ 44 class SimpleDateFormat; 45 class Hashtable; 46 47 /** 48 * DateFormatSymbols is a public class for encapsulating localizable date-time 49 * formatting data -- including timezone data. DateFormatSymbols is used by 50 * DateFormat and SimpleDateFormat. 51 * <P> 52 * Rather than first creating a DateFormatSymbols to get a date-time formatter 53 * by using a SimpleDateFormat constructor, clients are encouraged to create a 54 * date-time formatter using the getTimeInstance(), getDateInstance(), or 55 * getDateTimeInstance() method in DateFormat. Each of these methods can return a 56 * date/time formatter initialized with a default format pattern along with the 57 * date-time formatting data for a given or default locale. After a formatter is 58 * created, clients may modify the format pattern using the setPattern function 59 * as so desired. For more information on using these formatter factory 60 * functions, see DateFormat. 61 * <P> 62 * If clients decide to create a date-time formatter with a particular format 63 * pattern and locale, they can do so with new SimpleDateFormat(aPattern, 64 * new DateFormatSymbols(aLocale)). This will load the appropriate date-time 65 * formatting data from the locale. 66 * <P> 67 * DateFormatSymbols objects are clonable. When clients obtain a 68 * DateFormatSymbols object, they can feel free to modify the date-time 69 * formatting data as necessary. For instance, clients can 70 * replace the localized date-time format pattern characters with the ones that 71 * they feel easy to remember. Or they can change the representative cities 72 * originally picked by default to using their favorite ones. 73 * <P> 74 * DateFormatSymbols are not expected to be subclassed. Data for a calendar is 75 * loaded out of resource bundles. The 'type' parameter indicates the type of 76 * calendar, for example, "gregorian" or "japanese". If the type is not gregorian 77 * (or nullptr, or an empty string) then the type is appended to the resource name, 78 * for example, 'Eras_japanese' instead of 'Eras'. If the resource 'Eras_japanese' did 79 * not exist (even in root), then this class will fall back to just 'Eras', that is, 80 * Gregorian data. Therefore, the calendar implementor MUST ensure that the root 81 * locale at least contains any resources that are to be particularized for the 82 * calendar type. 83 */ 84 class U_I18N_API_CLASS DateFormatSymbols final : public UObject { 85 public: 86 /** 87 * Construct a DateFormatSymbols object by loading format data from 88 * resources for the default locale, in the default calendar (Gregorian). 89 * <P> 90 * NOTE: This constructor will never fail; if it cannot get resource 91 * data for the default locale, it will return a last-resort object 92 * based on hard-coded strings. 93 * 94 * @param status Status code. Failure 95 * results if the resources for the default cannot be 96 * found or cannot be loaded 97 * @stable ICU 2.0 98 */ 99 U_I18N_API DateFormatSymbols(UErrorCode& status); 100 101 /** 102 * Construct a DateFormatSymbols object by loading format data from 103 * resources for the given locale, in the default calendar (Gregorian). 104 * 105 * @param locale Locale to load format data from. 106 * @param status Status code. Failure 107 * results if the resources for the locale cannot be 108 * found or cannot be loaded 109 * @stable ICU 2.0 110 */ 111 U_I18N_API DateFormatSymbols(const Locale& locale, UErrorCode& status); 112 113 #ifndef U_HIDE_INTERNAL_API 114 /** 115 * Construct a DateFormatSymbols object by loading format data from 116 * resources for the default locale, in the default calendar (Gregorian). 117 * <P> 118 * NOTE: This constructor will never fail; if it cannot get resource 119 * data for the default locale, it will return a last-resort object 120 * based on hard-coded strings. 121 * 122 * @param type Type of calendar (as returned by Calendar::getType). 123 * Will be used to access the correct set of strings. 124 * (nullptr or empty string defaults to "gregorian".) 125 * @param status Status code. Failure 126 * results if the resources for the default cannot be 127 * found or cannot be loaded 128 * @internal 129 */ 130 U_I18N_API DateFormatSymbols(const char* type, UErrorCode& status); 131 132 /** 133 * Construct a DateFormatSymbols object by loading format data from 134 * resources for the given locale, in the default calendar (Gregorian). 135 * 136 * @param locale Locale to load format data from. 137 * @param type Type of calendar (as returned by Calendar::getType). 138 * Will be used to access the correct set of strings. 139 * (nullptr or empty string defaults to "gregorian".) 140 * @param status Status code. Failure 141 * results if the resources for the locale cannot be 142 * found or cannot be loaded 143 * @internal 144 */ 145 U_I18N_API DateFormatSymbols(const Locale& locale, const char* type, UErrorCode& status); 146 #endif /* U_HIDE_INTERNAL_API */ 147 148 /** 149 * Copy constructor. 150 * @stable ICU 2.0 151 */ 152 U_I18N_API DateFormatSymbols(const DateFormatSymbols&); 153 154 /** 155 * Assignment operator. 156 * @stable ICU 2.0 157 */ 158 U_I18N_API DateFormatSymbols& operator=(const DateFormatSymbols&); 159 160 /** 161 * Destructor. This is nonvirtual because this class is not designed to be 162 * subclassed. 163 * @stable ICU 2.0 164 */ 165 U_I18N_API virtual ~DateFormatSymbols(); 166 167 /** 168 * Return true if another object is semantically equal to this one. 169 * 170 * @param other the DateFormatSymbols object to be compared with. 171 * @return true if other is semantically equal to this. 172 * @stable ICU 2.0 173 */ 174 U_I18N_API bool operator==(const DateFormatSymbols& other) const; 175 176 /** 177 * Return true if another object is semantically unequal to this one. 178 * 179 * @param other the DateFormatSymbols object to be compared with. 180 * @return true if other is semantically unequal to this. 181 * @stable ICU 2.0 182 */ 183 U_I18N_API bool operator!=(const DateFormatSymbols& other) const { return !operator==(other); } 184 185 /** 186 * Gets abbreviated era strings. For example: "AD" and "BC". 187 * 188 * @param count Filled in with length of the array. 189 * @return the era strings. 190 * @stable ICU 2.0 191 */ 192 U_I18N_API const UnicodeString* getEras(int32_t& count) const; 193 194 /** 195 * Sets abbreviated era strings. For example: "AD" and "BC". 196 * @param eras Array of era strings (DateFormatSymbols retains ownership.) 197 * @param count Filled in with length of the array. 198 * @stable ICU 2.0 199 */ 200 U_I18N_API void setEras(const UnicodeString* eras, int32_t count); 201 202 /** 203 * Gets era name strings. For example: "Anno Domini" and "Before Christ". 204 * 205 * @param count Filled in with length of the array. 206 * @return the era name strings. 207 * @stable ICU 3.4 208 */ 209 U_I18N_API const UnicodeString* getEraNames(int32_t& count) const; 210 211 /** 212 * Sets era name strings. For example: "Anno Domini" and "Before Christ". 213 * @param eraNames Array of era name strings (DateFormatSymbols retains ownership.) 214 * @param count Filled in with length of the array. 215 * @stable ICU 3.6 216 */ 217 U_I18N_API void setEraNames(const UnicodeString* eraNames, int32_t count); 218 219 /** 220 * Gets narrow era strings. For example: "A" and "B". 221 * 222 * @param count Filled in with length of the array. 223 * @return the narrow era strings. 224 * @stable ICU 4.2 225 */ 226 U_I18N_API const UnicodeString* getNarrowEras(int32_t& count) const; 227 228 /** 229 * Sets narrow era strings. For example: "A" and "B". 230 * @param narrowEras Array of narrow era strings (DateFormatSymbols retains ownership.) 231 * @param count Filled in with length of the array. 232 * @stable ICU 4.2 233 */ 234 U_I18N_API void setNarrowEras(const UnicodeString* narrowEras, int32_t count); 235 236 /** 237 * Gets month strings. For example: "January", "February", etc. 238 * @param count Filled in with length of the array. 239 * @return the month strings. (DateFormatSymbols retains ownership.) 240 * @stable ICU 2.0 241 */ 242 U_I18N_API const UnicodeString* getMonths(int32_t& count) const; 243 244 /** 245 * Sets month strings. For example: "January", "February", etc. 246 * 247 * @param months the new month strings. (not adopted; caller retains ownership) 248 * @param count Filled in with length of the array. 249 * @stable ICU 2.0 250 */ 251 U_I18N_API void setMonths(const UnicodeString* months, int32_t count); 252 253 /** 254 * Gets short month strings. For example: "Jan", "Feb", etc. 255 * 256 * @param count Filled in with length of the array. 257 * @return the short month strings. (DateFormatSymbols retains ownership.) 258 * @stable ICU 2.0 259 */ 260 U_I18N_API const UnicodeString* getShortMonths(int32_t& count) const; 261 262 /** 263 * Sets short month strings. For example: "Jan", "Feb", etc. 264 * @param count Filled in with length of the array. 265 * @param shortMonths the new short month strings. (not adopted; caller retains ownership) 266 * @stable ICU 2.0 267 */ 268 U_I18N_API void setShortMonths(const UnicodeString* shortMonths, int32_t count); 269 270 /** 271 * Selector for date formatting context 272 * @stable ICU 3.6 273 */ 274 enum DtContextType { 275 FORMAT, 276 STANDALONE, 277 #ifndef U_HIDE_DEPRECATED_API 278 /** 279 * One more than the highest normal DtContextType value. 280 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 281 */ 282 DT_CONTEXT_COUNT 283 #endif // U_HIDE_DEPRECATED_API 284 }; 285 286 /** 287 * Selector for date formatting width 288 * @stable ICU 3.6 289 */ 290 enum DtWidthType { 291 ABBREVIATED, 292 WIDE, 293 NARROW, 294 /** 295 * Short width is currently only supported for weekday names. 296 * @stable ICU 51 297 */ 298 SHORT, 299 #ifndef U_HIDE_DEPRECATED_API 300 /** 301 * One more than the highest normal DtWidthType value. 302 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 303 */ 304 DT_WIDTH_COUNT = 4 305 #endif // U_HIDE_DEPRECATED_API 306 }; 307 308 /** 309 * Gets month strings by width and context. For example: "January", "February", etc. 310 * @param count Filled in with length of the array. 311 * @param context The formatting context, either FORMAT or STANDALONE 312 * @param width The width of returned strings, either WIDE, ABBREVIATED, or NARROW. 313 * @return the month strings. (DateFormatSymbols retains ownership.) 314 * @stable ICU 3.4 315 */ 316 U_I18N_API const UnicodeString* getMonths(int32_t& count, 317 DtContextType context, 318 DtWidthType width) const; 319 320 /** 321 * Sets month strings by width and context. For example: "January", "February", etc. 322 * 323 * @param months The new month strings. (not adopted; caller retains ownership) 324 * @param count Filled in with length of the array. 325 * @param context The formatting context, either FORMAT or STANDALONE 326 * @param width The width of returned strings, either WIDE, ABBREVIATED, or NARROW. 327 * @stable ICU 3.6 328 */ 329 U_I18N_API void setMonths(const UnicodeString* months, 330 int32_t count, 331 DtContextType context, 332 DtWidthType width); 333 334 /** 335 * Gets wide weekday strings. For example: "Sunday", "Monday", etc. 336 * @param count Filled in with length of the array. 337 * @return the weekday strings. (DateFormatSymbols retains ownership.) 338 * @stable ICU 2.0 339 */ 340 U_I18N_API const UnicodeString* getWeekdays(int32_t& count) const; 341 342 /** 343 * Sets wide weekday strings. For example: "Sunday", "Monday", etc. 344 * @param weekdays the new weekday strings. (not adopted; caller retains ownership) 345 * @param count Filled in with length of the array. 346 * @stable ICU 2.0 347 */ 348 U_I18N_API void setWeekdays(const UnicodeString* weekdays, int32_t count); 349 350 /** 351 * Gets abbreviated weekday strings. For example: "Sun", "Mon", etc. (Note: The method name is 352 * misleading; it does not get the CLDR-style "short" weekday strings, e.g. "Su", "Mo", etc.) 353 * @param count Filled in with length of the array. 354 * @return the abbreviated weekday strings. (DateFormatSymbols retains ownership.) 355 * @stable ICU 2.0 356 */ 357 U_I18N_API const UnicodeString* getShortWeekdays(int32_t& count) const; 358 359 /** 360 * Sets abbreviated weekday strings. For example: "Sun", "Mon", etc. (Note: The method name is 361 * misleading; it does not set the CLDR-style "short" weekday strings, e.g. "Su", "Mo", etc.) 362 * @param abbrevWeekdays the new abbreviated weekday strings. (not adopted; caller retains ownership) 363 * @param count Filled in with length of the array. 364 * @stable ICU 2.0 365 */ 366 U_I18N_API void setShortWeekdays(const UnicodeString* abbrevWeekdays, int32_t count); 367 368 /** 369 * Gets weekday strings by width and context. For example: "Sunday", "Monday", etc. 370 * @param count Filled in with length of the array. 371 * @param context The formatting context, either FORMAT or STANDALONE 372 * @param width The width of returned strings, either WIDE, ABBREVIATED, SHORT, or NARROW 373 * @return the month strings. (DateFormatSymbols retains ownership.) 374 * @stable ICU 3.4 375 */ 376 U_I18N_API const UnicodeString* getWeekdays(int32_t& count, 377 DtContextType context, 378 DtWidthType width) const; 379 380 /** 381 * Sets weekday strings by width and context. For example: "Sunday", "Monday", etc. 382 * @param weekdays The new weekday strings. (not adopted; caller retains ownership) 383 * @param count Filled in with length of the array. 384 * @param context The formatting context, either FORMAT or STANDALONE 385 * @param width The width of returned strings, either WIDE, ABBREVIATED, SHORT, or NARROW 386 * @stable ICU 3.6 387 */ 388 U_I18N_API void setWeekdays(const UnicodeString* weekdays, 389 int32_t count, 390 DtContextType context, 391 DtWidthType width); 392 393 /** 394 * Gets quarter strings by width and context. For example: "1st Quarter", "2nd Quarter", etc. 395 * @param count Filled in with length of the array. 396 * @param context The formatting context, either FORMAT or STANDALONE 397 * @param width The width of returned strings, either WIDE, ABBREVIATED, or NARROW. 398 * @return the quarter strings. (DateFormatSymbols retains ownership.) 399 * @stable ICU 3.6 400 */ 401 U_I18N_API const UnicodeString* getQuarters(int32_t& count, 402 DtContextType context, 403 DtWidthType width) const; 404 405 /** 406 * Sets quarter strings by width and context. For example: "1st Quarter", "2nd Quarter", etc. 407 * 408 * @param quarters The new quarter strings. (not adopted; caller retains ownership) 409 * @param count The number of strings in the array. 410 * @param context The formatting context, either FORMAT or STANDALONE 411 * @param width The width of set strings, either WIDE, ABBREVIATED, or NARROW. 412 * @stable ICU 3.6 413 */ 414 U_I18N_API void setQuarters(const UnicodeString* quarters, 415 int32_t count, 416 DtContextType context, 417 DtWidthType width); 418 419 /** 420 * Gets AM/PM strings. For example: "AM" and "PM". 421 * @param count Filled in with length of the array. 422 * @return The AM/PM strings. (DateFormatSymbols retains ownership.) 423 * @stable ICU 2.0 424 */ 425 U_I18N_API const UnicodeString* getAmPmStrings(int32_t& count) const; 426 427 /** 428 * Sets ampm strings. For example: "AM" and "PM". 429 * @param ampms The new ampm strings. (not adopted; caller retains ownership) 430 * @param count The number of strings in the array. 431 * @stable ICU 2.0 432 */ 433 U_I18N_API void setAmPmStrings(const UnicodeString* ampms, int32_t count); 434 435 #ifndef U_HIDE_DRAFT_API 436 /** 437 * Gets AM/PM strings with the specified width. For example: "A" and "P". 438 * @param count Filled in with length of the array. 439 * @param context The usage context. Currently ignored; FORMAT names always returned. 440 * @param width The width of returned strings, either WIDE, ABBREVIATED, or NARROW. 441 * @return The AM/PM strings. (DateFormatSymbols retains ownership.) 442 * @draft ICU 78 443 */ 444 U_I18N_API const UnicodeString* getAmPmStrings(int32_t& count, 445 DtContextType context, 446 DtWidthType width) const; 447 448 /** 449 * Sets AM/PM strings with the specified width. For example: "A" and "P". 450 * @param ampms The new AM/PM strings. (not adopted; caller retains ownership) 451 * @param count The number of strings in the array. 452 * @param context The usage context. Currently ignored; always sets FORMAT names. 453 * @param width The width of set strings, either WIDE, ABBREVIATED, or NARROW. 454 * @draft ICU 78 455 */ 456 U_I18N_API void setAmPmStrings(const UnicodeString* ampms, 457 int32_t count, 458 DtContextType context, 459 DtWidthType width); 460 #endif /* U_HIDE_DRAFT_API */ 461 462 #ifndef U_HIDE_INTERNAL_API 463 /** 464 * This default time separator is used for formatting when the locale 465 * doesn't specify any time separator, and always recognized when parsing. 466 * @internal 467 */ 468 U_I18N_API static const char16_t DEFAULT_TIME_SEPARATOR = 0x003a; // ':' 469 470 /** 471 * This alternate time separator is always recognized when parsing. 472 * @internal 473 */ 474 U_I18N_API static const char16_t ALTERNATE_TIME_SEPARATOR = 0x002e; // '.' 475 476 /** 477 * Gets the time separator string. For example: ":". 478 * @param result Output param which will receive the time separator string. 479 * @return A reference to 'result'. 480 * @internal 481 */ 482 U_I18N_API UnicodeString& getTimeSeparatorString(UnicodeString& result) const; 483 484 /** 485 * Sets the time separator string. For example: ":". 486 * @param newTimeSeparator the new time separator string. 487 * @internal 488 */ 489 U_I18N_API void setTimeSeparatorString(const UnicodeString& newTimeSeparator); 490 #endif /* U_HIDE_INTERNAL_API */ 491 492 /** 493 * Gets cyclic year name strings if the calendar has them, by width and context. 494 * For example: "jia-zi", "yi-chou", etc. 495 * @param count Filled in with length of the array. 496 * @param context The usage context: FORMAT, STANDALONE. 497 * @param width The requested name width: WIDE, ABBREVIATED, NARROW. 498 * @return The year name strings (DateFormatSymbols retains ownership), 499 * or null if they are not available for this calendar. 500 * @stable ICU 54 501 */ 502 U_I18N_API const UnicodeString* getYearNames(int32_t& count, 503 DtContextType context, 504 DtWidthType width) const; 505 506 /** 507 * Sets cyclic year name strings by width and context. For example: "jia-zi", "yi-chou", etc. 508 * 509 * @param yearNames The new cyclic year name strings (not adopted; caller retains ownership). 510 * @param count The length of the array. 511 * @param context The usage context: FORMAT, STANDALONE (currently only FORMAT is supported). 512 * @param width The name width: WIDE, ABBREVIATED, NARROW (currently only ABBREVIATED is supported). 513 * @stable ICU 54 514 */ 515 U_I18N_API void setYearNames(const UnicodeString* yearNames, 516 int32_t count, 517 DtContextType context, 518 DtWidthType width); 519 520 /** 521 * Gets calendar zodiac name strings if the calendar has them, by width and context. 522 * For example: "Rat", "Ox", "Tiger", etc. 523 * @param count Filled in with length of the array. 524 * @param context The usage context: FORMAT, STANDALONE. 525 * @param width The requested name width: WIDE, ABBREVIATED, NARROW. 526 * @return The zodiac name strings (DateFormatSymbols retains ownership), 527 * or null if they are not available for this calendar. 528 * @stable ICU 54 529 */ 530 U_I18N_API const UnicodeString* getZodiacNames(int32_t& count, 531 DtContextType context, 532 DtWidthType width) const; 533 534 /** 535 * Sets calendar zodiac name strings by width and context. For example: "Rat", "Ox", "Tiger", etc. 536 * 537 * @param zodiacNames The new zodiac name strings (not adopted; caller retains ownership). 538 * @param count The length of the array. 539 * @param context The usage context: FORMAT, STANDALONE (currently only FORMAT is supported). 540 * @param width The name width: WIDE, ABBREVIATED, NARROW (currently only ABBREVIATED is supported). 541 * @stable ICU 54 542 */ 543 U_I18N_API void setZodiacNames(const UnicodeString* zodiacNames, 544 int32_t count, 545 DtContextType context, 546 DtWidthType width); 547 548 #ifndef U_HIDE_INTERNAL_API 549 /** 550 * Somewhat temporary constants for leap month pattern types, adequate for supporting 551 * just leap month patterns as needed for Chinese lunar calendar. 552 * Eventually we will add full support for different month pattern types (needed for 553 * other calendars such as Hindu) at which point this approach will be replaced by a 554 * more complete approach. 555 * @internal 556 */ 557 enum EMonthPatternType 558 { 559 kLeapMonthPatternFormatWide, 560 kLeapMonthPatternFormatAbbrev, 561 kLeapMonthPatternFormatNarrow, 562 kLeapMonthPatternStandaloneWide, 563 kLeapMonthPatternStandaloneAbbrev, 564 kLeapMonthPatternStandaloneNarrow, 565 kLeapMonthPatternNumeric, 566 kMonthPatternsCount 567 }; 568 569 /** 570 * Somewhat temporary function for getting complete set of leap month patterns for all 571 * contexts & widths, indexed by EMonthPatternType values. Returns nullptr if calendar 572 * does not have leap month patterns. Note, there is currently no setter for this. 573 * Eventually we will add full support for different month pattern types (needed for 574 * other calendars such as Hindu) at which point this approach will be replaced by a 575 * more complete approach. 576 * @param count Filled in with length of the array (may be 0). 577 * @return The leap month patterns (DateFormatSymbols retains ownership). 578 * May be nullptr if there are no leap month patterns for this calendar. 579 * @internal 580 */ 581 U_I18N_API const UnicodeString* getLeapMonthPatterns(int32_t& count) const; 582 583 #endif /* U_HIDE_INTERNAL_API */ 584 585 #ifndef U_HIDE_DEPRECATED_API 586 /** 587 * Gets timezone strings. These strings are stored in a 2-dimensional array. 588 * @param rowCount Output param to receive number of rows. 589 * @param columnCount Output param to receive number of columns. 590 * @return The timezone strings as a 2-d array. (DateFormatSymbols retains ownership.) 591 * @deprecated ICU 3.6 592 */ 593 U_I18N_API const UnicodeString** getZoneStrings(int32_t& rowCount, int32_t& columnCount) const; 594 #endif /* U_HIDE_DEPRECATED_API */ 595 596 /** 597 * Sets timezone strings. These strings are stored in a 2-dimensional array. 598 * <p><b>Note:</b> SimpleDateFormat no longer use the zone strings stored in 599 * a DateFormatSymbols. Therefore, the time zone strings set by this method 600 * have no effects in an instance of SimpleDateFormat for formatting time 601 * zones. 602 * @param strings The timezone strings as a 2-d array to be copied. (not adopted; caller retains ownership) 603 * @param rowCount The number of rows (count of first index). 604 * @param columnCount The number of columns (count of second index). 605 * @stable ICU 2.0 606 */ 607 U_I18N_API void setZoneStrings(const UnicodeString* const* strings, 608 int32_t rowCount, 609 int32_t columnCount); 610 611 /** 612 * Get the non-localized date-time pattern characters. 613 * @return the non-localized date-time pattern characters 614 * @stable ICU 2.0 615 */ 616 U_I18N_API static const char16_t* getPatternUChars(); 617 618 /** 619 * Gets localized date-time pattern characters. For example: 'u', 't', etc. 620 * <p> 621 * Note: ICU no longer provides localized date-time pattern characters for a locale 622 * starting ICU 3.8. This method returns the non-localized date-time pattern 623 * characters unless user defined localized data is set by setLocalPatternChars. 624 * @param result Output param which will receive the localized date-time pattern characters. 625 * @return A reference to 'result'. 626 * @stable ICU 2.0 627 */ 628 U_I18N_API UnicodeString& getLocalPatternChars(UnicodeString& result) const; 629 630 /** 631 * Sets localized date-time pattern characters. For example: 'u', 't', etc. 632 * @param newLocalPatternChars the new localized date-time 633 * pattern characters. 634 * @stable ICU 2.0 635 */ 636 U_I18N_API void setLocalPatternChars(const UnicodeString& newLocalPatternChars); 637 638 /** 639 * Returns the locale for this object. Two flavors are available: 640 * valid and actual locale. 641 * @stable ICU 2.8 642 */ 643 U_I18N_API Locale getLocale(ULocDataLocaleType type, UErrorCode& status) const; 644 645 /* The following type and kCapContextUsageTypeCount cannot be #ifndef U_HIDE_INTERNAL_API, 646 they are needed for .h file declarations. */ 647 /** 648 * Constants for capitalization context usage types. 649 * @internal 650 */ 651 enum ECapitalizationContextUsageType 652 { 653 #ifndef U_HIDE_INTERNAL_API 654 kCapContextUsageOther = 0, 655 kCapContextUsageMonthFormat, /* except narrow */ 656 kCapContextUsageMonthStandalone, /* except narrow */ 657 kCapContextUsageMonthNarrow, 658 kCapContextUsageDayFormat, /* except narrow */ 659 kCapContextUsageDayStandalone, /* except narrow */ 660 kCapContextUsageDayNarrow, 661 kCapContextUsageEraWide, 662 kCapContextUsageEraAbbrev, 663 kCapContextUsageEraNarrow, 664 kCapContextUsageZoneLong, 665 kCapContextUsageZoneShort, 666 kCapContextUsageMetazoneLong, 667 kCapContextUsageMetazoneShort, 668 #endif /* U_HIDE_INTERNAL_API */ 669 kCapContextUsageTypeCount = 14 670 }; 671 672 /** 673 * ICU "poor man's RTTI", returns a UClassID for the actual class. 674 * 675 * @stable ICU 2.2 676 */ 677 U_I18N_API virtual UClassID getDynamicClassID() const override; 678 679 /** 680 * ICU "poor man's RTTI", returns a UClassID for this class. 681 * 682 * @stable ICU 2.2 683 */ 684 U_I18N_API static UClassID getStaticClassID(); 685 686 private: 687 688 friend class SimpleDateFormat; 689 friend class DateFormatSymbolsSingleSetter; // see udat.cpp 690 691 /** 692 * Abbreviated era strings. For example: "AD" and "BC". 693 */ 694 UnicodeString* fEras; 695 int32_t fErasCount; 696 697 /** 698 * Era name strings. For example: "Anno Domini" and "Before Christ". 699 */ 700 UnicodeString* fEraNames; 701 int32_t fEraNamesCount; 702 703 /** 704 * Narrow era strings. For example: "A" and "B". 705 */ 706 UnicodeString* fNarrowEras; 707 int32_t fNarrowErasCount; 708 709 /** 710 * Month strings. For example: "January", "February", etc. 711 */ 712 UnicodeString* fMonths; 713 int32_t fMonthsCount; 714 715 /** 716 * Short month strings. For example: "Jan", "Feb", etc. 717 */ 718 UnicodeString* fShortMonths; 719 int32_t fShortMonthsCount; 720 721 /** 722 * Narrow month strings. For example: "J", "F", etc. 723 */ 724 UnicodeString* fNarrowMonths; 725 int32_t fNarrowMonthsCount; 726 727 /** 728 * Standalone Month strings. For example: "January", "February", etc. 729 */ 730 UnicodeString* fStandaloneMonths; 731 int32_t fStandaloneMonthsCount; 732 733 /** 734 * Standalone Short month strings. For example: "Jan", "Feb", etc. 735 */ 736 UnicodeString* fStandaloneShortMonths; 737 int32_t fStandaloneShortMonthsCount; 738 739 /** 740 * Standalone Narrow month strings. For example: "J", "F", etc. 741 */ 742 UnicodeString* fStandaloneNarrowMonths; 743 int32_t fStandaloneNarrowMonthsCount; 744 745 /** 746 * CLDR-style format wide weekday strings. For example: "Sunday", "Monday", etc. 747 */ 748 UnicodeString* fWeekdays; 749 int32_t fWeekdaysCount; 750 751 /** 752 * CLDR-style format abbreviated (not short) weekday strings. For example: "Sun", "Mon", etc. 753 */ 754 UnicodeString* fShortWeekdays; 755 int32_t fShortWeekdaysCount; 756 757 /** 758 * CLDR-style format short weekday strings. For example: "Su", "Mo", etc. 759 */ 760 UnicodeString* fShorterWeekdays; 761 int32_t fShorterWeekdaysCount; 762 763 /** 764 * CLDR-style format narrow weekday strings. For example: "S", "M", etc. 765 */ 766 UnicodeString* fNarrowWeekdays; 767 int32_t fNarrowWeekdaysCount; 768 769 /** 770 * CLDR-style standalone wide weekday strings. For example: "Sunday", "Monday", etc. 771 */ 772 UnicodeString* fStandaloneWeekdays; 773 int32_t fStandaloneWeekdaysCount; 774 775 /** 776 * CLDR-style standalone abbreviated (not short) weekday strings. For example: "Sun", "Mon", etc. 777 */ 778 UnicodeString* fStandaloneShortWeekdays; 779 int32_t fStandaloneShortWeekdaysCount; 780 781 /** 782 * CLDR-style standalone short weekday strings. For example: "Su", "Mo", etc. 783 */ 784 UnicodeString* fStandaloneShorterWeekdays; 785 int32_t fStandaloneShorterWeekdaysCount; 786 787 /** 788 * Standalone Narrow weekday strings. For example: "Sun", "Mon", etc. 789 */ 790 UnicodeString* fStandaloneNarrowWeekdays; 791 int32_t fStandaloneNarrowWeekdaysCount; 792 793 /** 794 * Ampm strings. For example: "AM" and "PM". 795 */ 796 UnicodeString* fAmPms; 797 int32_t fAmPmsCount; 798 799 /** 800 * Wide Ampm strings. For example: "ante meridiem" and "post meridiem". 801 * These strings are uncommon but exist in a handful of locales. 802 */ 803 UnicodeString* fWideAmPms; 804 int32_t fWideAmPmsCount; 805 806 /** 807 * Narrow Ampm strings. For example: "a" and "p". 808 */ 809 UnicodeString* fNarrowAmPms; 810 int32_t fNarrowAmPmsCount; 811 812 /** 813 * Time separator string. For example: ":". 814 */ 815 UnicodeString fTimeSeparator; 816 817 /** 818 * Quarter strings. For example: "1st quarter", "2nd quarter", etc. 819 */ 820 UnicodeString *fQuarters; 821 int32_t fQuartersCount; 822 823 /** 824 * Short quarters. For example: "Q1", "Q2", etc. 825 */ 826 UnicodeString *fShortQuarters; 827 int32_t fShortQuartersCount; 828 829 /** 830 * Narrow quarters. For example: "1", "2", etc. 831 * (In many, but not all, locales, this is the same as "Q", but there are locales for which this isn't true.) 832 */ 833 UnicodeString *fNarrowQuarters; 834 int32_t fNarrowQuartersCount; 835 836 /** 837 * Standalone quarter strings. For example: "1st quarter", "2nd quarter", etc. 838 */ 839 UnicodeString *fStandaloneQuarters; 840 int32_t fStandaloneQuartersCount; 841 842 /** 843 * Standalone short quarter strings. For example: "Q1", "Q2", etc. 844 */ 845 UnicodeString *fStandaloneShortQuarters; 846 int32_t fStandaloneShortQuartersCount; 847 848 /** 849 * Standalone narrow quarter strings. For example: "1", "2", etc. 850 * (In many, but not all, locales, this is the same as "q", but there are locales for which this isn't true.) 851 */ 852 UnicodeString *fStandaloneNarrowQuarters; 853 int32_t fStandaloneNarrowQuartersCount; 854 855 /** 856 * All leap month patterns, for example "{0}bis". 857 */ 858 UnicodeString *fLeapMonthPatterns; 859 int32_t fLeapMonthPatternsCount; 860 861 /** 862 * Cyclic year names, for example: "jia-zi", "yi-chou", ... "gui-hai"; 863 * currently we only have data for format/abbreviated. 864 * For the others, just get from format/abbreviated, ignore set. 865 */ 866 UnicodeString *fShortYearNames; 867 int32_t fShortYearNamesCount; 868 869 /** 870 * Cyclic zodiac names, for example "Rat", "Ox", "Tiger", etc.; 871 * currently we only have data for format/abbreviated. 872 * For the others, just get from format/abbreviated, ignore set. 873 */ 874 UnicodeString *fShortZodiacNames; 875 int32_t fShortZodiacNamesCount; 876 877 /** 878 * Localized names of time zones in this locale. This is a 879 * two-dimensional array of strings of size n by m, 880 * where m is at least 5 and up to 7. Each of the n rows is an 881 * entry containing the localized names for a single TimeZone. 882 * 883 * Each such row contains (with i ranging from 0..n-1): 884 * 885 * zoneStrings[i][0] - time zone ID 886 * example: America/Los_Angeles 887 * zoneStrings[i][1] - long name of zone in standard time 888 * example: Pacific Standard Time 889 * zoneStrings[i][2] - short name of zone in standard time 890 * example: PST 891 * zoneStrings[i][3] - long name of zone in daylight savings time 892 * example: Pacific Daylight Time 893 * zoneStrings[i][4] - short name of zone in daylight savings time 894 * example: PDT 895 * zoneStrings[i][5] - location name of zone 896 * example: United States (Los Angeles) 897 * zoneStrings[i][6] - long generic name of zone 898 * example: Pacific Time 899 * zoneStrings[i][7] - short generic of zone 900 * example: PT 901 * 902 * The zone ID is not localized; it corresponds to the ID 903 * value associated with a system time zone object. All other entries 904 * are localized names. If a zone does not implement daylight savings 905 * time, the daylight savings time names are ignored. 906 * 907 * Note:CLDR 1.5 introduced metazone and its historical mappings. 908 * This simple two-dimensional array is no longer sufficient to represent 909 * localized names and its historic changes. Since ICU 3.8.1, localized 910 * zone names extracted from ICU locale data is stored in a ZoneStringFormat 911 * instance. But we still need to support the old way of customizing 912 * localized zone names, so we keep this field for the purpose. 913 */ 914 UnicodeString **fZoneStrings; // Zone string array set by setZoneStrings 915 UnicodeString **fLocaleZoneStrings; // Zone string array created by the locale 916 int32_t fZoneStringsRowCount; 917 int32_t fZoneStringsColCount; 918 919 Locale fZSFLocale; // Locale used for getting ZoneStringFormat 920 921 /** 922 * Localized date-time pattern characters. For example: use 'u' as 'y'. 923 */ 924 UnicodeString fLocalPatternChars; 925 926 /** 927 * Capitalization transforms. For each usage type, the first array element indicates 928 * whether to titlecase for uiListOrMenu context, the second indicates whether to 929 * titlecase for stand-alone context. 930 */ 931 UBool fCapitalization[kCapContextUsageTypeCount][2]; 932 933 /** 934 * Abbreviated (== short) day period strings. 935 */ 936 UnicodeString *fAbbreviatedDayPeriods; 937 int32_t fAbbreviatedDayPeriodsCount; 938 939 /** 940 * Wide day period strings. 941 */ 942 UnicodeString *fWideDayPeriods; 943 int32_t fWideDayPeriodsCount; 944 945 /** 946 * Narrow day period strings. 947 */ 948 UnicodeString *fNarrowDayPeriods; 949 int32_t fNarrowDayPeriodsCount; 950 951 /** 952 * Stand-alone abbreviated (== short) day period strings. 953 */ 954 UnicodeString *fStandaloneAbbreviatedDayPeriods; 955 int32_t fStandaloneAbbreviatedDayPeriodsCount; 956 957 /** 958 * Stand-alone wide day period strings. 959 */ 960 UnicodeString *fStandaloneWideDayPeriods; 961 int32_t fStandaloneWideDayPeriodsCount; 962 963 /** 964 * Stand-alone narrow day period strings. 965 */ 966 UnicodeString *fStandaloneNarrowDayPeriods; 967 int32_t fStandaloneNarrowDayPeriodsCount; 968 969 private: 970 /** valid/actual locale information 971 * these are always ICU locales, so the length should not be a problem 972 */ 973 Locale validLocale; 974 Locale actualLocale; 975 976 DateFormatSymbols() = delete; // default constructor not implemented 977 978 /** 979 * Called by the constructors to actually load data from the resources 980 * 981 * @param locale The locale to get symbols for. 982 * @param type Calendar Type (as from Calendar::getType()) 983 * @param status Input/output parameter, set to success or 984 * failure code upon return. 985 * @param useLastResortData determine if use last resort data 986 */ 987 void initializeData(const Locale& locale, const char *type, 988 UErrorCode& status, UBool useLastResortData = false); 989 990 /** 991 * Copy or alias an array in another object, as appropriate. 992 * 993 * @param dstArray the copy destination array. 994 * @param dstCount fill in with the length of 'dstArray'. 995 * @param srcArray the source array to be copied. 996 * @param srcCount the length of items to be copied from the 'srcArray'. 997 */ 998 static void assignArray(UnicodeString*& dstArray, 999 int32_t& dstCount, 1000 const UnicodeString* srcArray, 1001 int32_t srcCount); 1002 1003 /** 1004 * Return true if the given arrays' contents are equal, or if the arrays are 1005 * identical (pointers are equal). 1006 * 1007 * @param array1 one array to be compared with. 1008 * @param array2 another array to be compared with. 1009 * @param count the length of items to be copied. 1010 * @return true if the given arrays' contents are equal, or if the arrays are 1011 * identical (pointers are equal). 1012 */ 1013 static UBool arrayCompare(const UnicodeString* array1, 1014 const UnicodeString* array2, 1015 int32_t count); 1016 1017 /** 1018 * Create a copy, in fZoneStrings, of the given zone strings array. The 1019 * member variables fZoneStringsRowCount and fZoneStringsColCount should be 1020 * set already by the caller. 1021 */ 1022 void createZoneStrings(const UnicodeString *const * otherStrings); 1023 1024 /** 1025 * Delete all the storage owned by this object. 1026 */ 1027 void dispose(); 1028 1029 /** 1030 * Copy all of the other's data to this. 1031 * @param other the object to be copied. 1032 */ 1033 void copyData(const DateFormatSymbols& other); 1034 1035 /** 1036 * Create zone strings array by locale if not yet available 1037 */ 1038 void initZoneStringsArray(); 1039 1040 /** 1041 * Delete just the zone strings. 1042 */ 1043 void disposeZoneStrings(); 1044 1045 /** 1046 * Returns the date format field index of the pattern character c, 1047 * or UDAT_FIELD_COUNT if c is not a pattern character. 1048 */ 1049 static UDateFormatField U_EXPORT2 getPatternCharIndex(char16_t c); 1050 1051 /** 1052 * Returns true if f (with its pattern character repeated count times) is a numeric field. 1053 */ 1054 static UBool U_EXPORT2 isNumericField(UDateFormatField f, int32_t count); 1055 1056 /** 1057 * Returns true if c (repeated count times) is the pattern character for a numeric field. 1058 */ 1059 static UBool U_EXPORT2 isNumericPatternChar(char16_t c, int32_t count); 1060 public: 1061 #ifndef U_HIDE_INTERNAL_API 1062 /** 1063 * Gets a DateFormatSymbols by locale. 1064 * Unlike the constructors which always use gregorian calendar, this 1065 * method uses the calendar in the locale. If the locale contains no 1066 * explicit calendar, this method uses the default calendar for that 1067 * locale. 1068 * @param locale the locale. 1069 * @param status error returned here. 1070 * @return the new DateFormatSymbols which the caller owns. 1071 * @internal For ICU use only. 1072 */ 1073 U_I18N_API static DateFormatSymbols* createForLocale(const Locale& locale, UErrorCode& status); 1074 #endif /* U_HIDE_INTERNAL_API */ 1075 }; 1076 1077 U_NAMESPACE_END 1078 1079 #endif /* #if !UCONFIG_NO_FORMATTING */ 1080 1081 #endif /* U_SHOW_CPLUSPLUS_API */ 1082 1083 #endif // _DTFMTSYM 1084 //eof