1 // 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ******************************************************************************* 5 * Copyright (C) 2007-2016, International Business Machines Corporation and 6 * others. All Rights Reserved. 7 ******************************************************************************* 8 * 9 * File DTPTNGEN.H 10 * 11 ******************************************************************************* 12 */ 13 14 #ifndef __DTPTNGEN_H__ 15 #define __DTPTNGEN_H__ 16 17 #include "unicode/datefmt.h" 18 #include "unicode/locid.h" 19 #include "unicode/udat.h" 20 #include "unicode/udatpg.h" 21 #include "unicode/unistr.h" 22 23 U_NAMESPACE_BEGIN 24 25 /** 26 * \file 27 * \brief C++ API: Date/Time Pattern Generator 28 */ 29 30 31 class CharString; 32 class Hashtable; 33 class FormatParser; 34 class DateTimeMatcher; 35 class DistanceInfo; 36 class PatternMap; 37 class PtnSkeleton; 38 class SharedDateTimePatternGenerator; 39 40 /** 41 * This class provides flexible generation of date format patterns, like "yy-MM-dd". 42 * The user can build up the generator by adding successive patterns. Once that 43 * is done, a query can be made using a "skeleton", which is a pattern which just 44 * includes the desired fields and lengths. The generator will return the "best fit" 45 * pattern corresponding to that skeleton. 46 * <p>The main method people will use is getBestPattern(String skeleton), 47 * since normally this class is pre-built with data from a particular locale. 48 * However, generators can be built directly from other data as well. 49 * <p><i>Issue: may be useful to also have a function that returns the list of 50 * fields in a pattern, in order, since we have that internally. 51 * That would be useful for getting the UI order of field elements.</i> 52 * @stable ICU 3.8 53 **/ 54 class U_I18N_API DateTimePatternGenerator : public UObject { 55 public: 56 /** 57 * Construct a flexible generator according to default locale. 58 * @param status Output param set to success/failure code on exit, 59 * which must not indicate a failure before the function call. 60 * @stable ICU 3.8 61 */ 62 static DateTimePatternGenerator* U_EXPORT2 createInstance(UErrorCode& status); 63 64 /** 65 * Construct a flexible generator according to data for a given locale. 66 * @param uLocale 67 * @param status Output param set to success/failure code on exit, 68 * which must not indicate a failure before the function call. 69 * @stable ICU 3.8 70 */ 71 static DateTimePatternGenerator* U_EXPORT2 createInstance(const Locale& uLocale, UErrorCode& status); 72 73 #ifndef U_HIDE_INTERNAL_API 74 75 /** 76 * For ICU use only 77 * 78 * @internal 79 */ 80 static DateTimePatternGenerator* U_EXPORT2 internalMakeInstance(const Locale& uLocale, UErrorCode& status); 81 82 #endif /* U_HIDE_INTERNAL_API */ 83 84 /** 85 * Create an empty generator, to be constructed with addPattern(...) etc. 86 * @param status Output param set to success/failure code on exit, 87 * which must not indicate a failure before the function call. 88 * @stable ICU 3.8 89 */ 90 static DateTimePatternGenerator* U_EXPORT2 createEmptyInstance(UErrorCode& status); 91 92 /** 93 * Destructor. 94 * @stable ICU 3.8 95 */ 96 virtual ~DateTimePatternGenerator(); 97 98 /** 99 * Clone DateTimePatternGenerator object. Clients are responsible for 100 * deleting the DateTimePatternGenerator object cloned. 101 * @stable ICU 3.8 102 */ 103 DateTimePatternGenerator* clone() const; 104 105 /** 106 * Return true if another object is semantically equal to this one. 107 * 108 * @param other the DateTimePatternGenerator object to be compared with. 109 * @return true if other is semantically equal to this. 110 * @stable ICU 3.8 111 */ 112 UBool operator==(const DateTimePatternGenerator& other) const; 113 114 /** 115 * Return true if another object is semantically unequal to this one. 116 * 117 * @param other the DateTimePatternGenerator object to be compared with. 118 * @return true if other is semantically unequal to this. 119 * @stable ICU 3.8 120 */ 121 UBool operator!=(const DateTimePatternGenerator& other) const; 122 123 /** 124 * Utility to return a unique skeleton from a given pattern. For example, 125 * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd". 126 * 127 * @param pattern Input pattern, such as "dd/MMM" 128 * @param status Output param set to success/failure code on exit, 129 * which must not indicate a failure before the function call. 130 * @return skeleton such as "MMMdd" 131 * @stable ICU 56 132 */ 133 static UnicodeString staticGetSkeleton(const UnicodeString& pattern, UErrorCode& status); 134 135 /** 136 * Utility to return a unique skeleton from a given pattern. For example, 137 * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd". 138 * getSkeleton() works exactly like staticGetSkeleton(). 139 * Use staticGetSkeleton() instead of getSkeleton(). 140 * 141 * @param pattern Input pattern, such as "dd/MMM" 142 * @param status Output param set to success/failure code on exit, 143 * which must not indicate a failure before the function call. 144 * @return skeleton such as "MMMdd" 145 * @stable ICU 3.8 146 */ 147 UnicodeString getSkeleton(const UnicodeString& pattern, UErrorCode& status); /* { 148 The function is commented out because it is a stable API calling a draft API. 149 After staticGetSkeleton becomes stable, staticGetSkeleton can be used and 150 these comments and the definition of getSkeleton in dtptngen.cpp should be removed. 151 return staticGetSkeleton(pattern, status); 152 }*/ 153 154 /** 155 * Utility to return a unique base skeleton from a given pattern. This is 156 * the same as the skeleton, except that differences in length are minimized 157 * so as to only preserve the difference between string and numeric form. So 158 * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd" 159 * (notice the single d). 160 * 161 * @param pattern Input pattern, such as "dd/MMM" 162 * @param status Output param set to success/failure code on exit, 163 * which must not indicate a failure before the function call. 164 * @return base skeleton, such as "MMMd" 165 * @stable ICU 56 166 */ 167 static UnicodeString staticGetBaseSkeleton(const UnicodeString& pattern, UErrorCode& status); 168 169 /** 170 * Utility to return a unique base skeleton from a given pattern. This is 171 * the same as the skeleton, except that differences in length are minimized 172 * so as to only preserve the difference between string and numeric form. So 173 * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd" 174 * (notice the single d). 175 * getBaseSkeleton() works exactly like staticGetBaseSkeleton(). 176 * Use staticGetBaseSkeleton() instead of getBaseSkeleton(). 177 * 178 * @param pattern Input pattern, such as "dd/MMM" 179 * @param status Output param set to success/failure code on exit, 180 * which must not indicate a failure before the function call. 181 * @return base skeleton, such as "MMMd" 182 * @stable ICU 3.8 183 */ 184 UnicodeString getBaseSkeleton(const UnicodeString& pattern, UErrorCode& status); /* { 185 The function is commented out because it is a stable API calling a draft API. 186 After staticGetBaseSkeleton becomes stable, staticGetBaseSkeleton can be used and 187 these comments and the definition of getBaseSkeleton in dtptngen.cpp should be removed. 188 return staticGetBaseSkeleton(pattern, status); 189 }*/ 190 191 /** 192 * Adds a pattern to the generator. If the pattern has the same skeleton as 193 * an existing pattern, and the override parameter is set, then the previous 194 * value is overriden. Otherwise, the previous value is retained. In either 195 * case, the conflicting status is set and previous vale is stored in 196 * conflicting pattern. 197 * <p> 198 * Note that single-field patterns (like "MMM") are automatically added, and 199 * don't need to be added explicitly! 200 * 201 * @param pattern Input pattern, such as "dd/MMM" 202 * @param override When existing values are to be overridden use true, 203 * otherwise use false. 204 * @param conflictingPattern Previous pattern with the same skeleton. 205 * @param status Output param set to success/failure code on exit, 206 * which must not indicate a failure before the function call. 207 * @return conflicting status. The value could be UDATPG_NO_CONFLICT, 208 * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT. 209 * @stable ICU 3.8 210 * <p> 211 * <h4>Sample code</h4> 212 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1 213 * \snippet samples/dtptngsample/dtptngsample.cpp addPatternExample 214 * <p> 215 */ 216 UDateTimePatternConflict addPattern(const UnicodeString& pattern, 217 UBool override, 218 UnicodeString& conflictingPattern, 219 UErrorCode& status); 220 221 /** 222 * An AppendItem format is a pattern used to append a field if there is no 223 * good match. For example, suppose that the input skeleton is "GyyyyMMMd", 224 * and there is no matching pattern internally, but there is a pattern 225 * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the 226 * G. The way these two are conjoined is by using the AppendItemFormat for G 227 * (era). So if that value is, say "{0}, {1}" then the final resulting 228 * pattern is "d-MM-yyyy, G". 229 * <p> 230 * There are actually three available variables: {0} is the pattern so far, 231 * {1} is the element we are adding, and {2} is the name of the element. 232 * <p> 233 * This reflects the way that the CLDR data is organized. 234 * 235 * @param field such as UDATPG_ERA_FIELD. 236 * @param value pattern, such as "{0}, {1}" 237 * @stable ICU 3.8 238 */ 239 void setAppendItemFormat(UDateTimePatternField field, const UnicodeString& value); 240 241 /** 242 * Getter corresponding to setAppendItemFormat. Values below 0 or at or 243 * above UDATPG_FIELD_COUNT are illegal arguments. 244 * 245 * @param field such as UDATPG_ERA_FIELD. 246 * @return append pattern for field 247 * @stable ICU 3.8 248 */ 249 const UnicodeString& getAppendItemFormat(UDateTimePatternField field) const; 250 251 /** 252 * Sets the names of field, eg "era" in English for ERA. These are only 253 * used if the corresponding AppendItemFormat is used, and if it contains a 254 * {2} variable. 255 * <p> 256 * This reflects the way that the CLDR data is organized. 257 * 258 * @param field such as UDATPG_ERA_FIELD. 259 * @param value name of the field 260 * @stable ICU 3.8 261 */ 262 void setAppendItemName(UDateTimePatternField field, const UnicodeString& value); 263 264 /** 265 * Getter corresponding to setAppendItemNames. Values below 0 or at or above 266 * UDATPG_FIELD_COUNT are illegal arguments. 267 * 268 * @param field such as UDATPG_ERA_FIELD. 269 * @return name for field 270 * @stable ICU 3.8 271 */ 272 const UnicodeString& getAppendItemName(UDateTimePatternField field) const; 273 274 /** 275 * The DateTimeFormat is a message format pattern used to compose date and 276 * time patterns. The default pattern in the root locale is "{1} {0}", where 277 * {1} will be replaced by the date pattern and {0} will be replaced by the 278 * time pattern; however, other locales may specify patterns such as 279 * "{1}, {0}" or "{1} 'at' {0}", etc. 280 * <p> 281 * This is used when the input skeleton contains both date and time fields, 282 * but there is not a close match among the added patterns. For example, 283 * suppose that this object was created by adding "dd-MMM" and "hh:mm", and 284 * its datetimeFormat is the default "{1} {0}". Then if the input skeleton 285 * is "MMMdhmm", there is not an exact match, so the input skeleton is 286 * broken up into two components "MMMd" and "hmm". There are close matches 287 * for those two skeletons, so the result is put together with this pattern, 288 * resulting in "d-MMM h:mm". 289 * 290 * @param dateTimeFormat 291 * message format pattern, here {1} will be replaced by the date 292 * pattern and {0} will be replaced by the time pattern. 293 * @stable ICU 3.8 294 */ 295 void setDateTimeFormat(const UnicodeString& dateTimeFormat); 296 297 /** 298 * Getter corresponding to setDateTimeFormat. 299 * @return DateTimeFormat. 300 * @stable ICU 3.8 301 */ 302 const UnicodeString& getDateTimeFormat() const; 303 304 /** 305 * Return the best pattern matching the input skeleton. It is guaranteed to 306 * have all of the fields in the skeleton. 307 * 308 * @param skeleton 309 * The skeleton is a pattern containing only the variable fields. 310 * For example, "MMMdd" and "mmhh" are skeletons. 311 * @param status Output param set to success/failure code on exit, 312 * which must not indicate a failure before the function call. 313 * @return bestPattern 314 * The best pattern found from the given skeleton. 315 * @stable ICU 3.8 316 * <p> 317 * <h4>Sample code</h4> 318 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1 319 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample 320 * <p> 321 */ 322 UnicodeString getBestPattern(const UnicodeString& skeleton, UErrorCode& status); 323 324 325 /** 326 * Return the best pattern matching the input skeleton. It is guaranteed to 327 * have all of the fields in the skeleton. 328 * 329 * @param skeleton 330 * The skeleton is a pattern containing only the variable fields. 331 * For example, "MMMdd" and "mmhh" are skeletons. 332 * @param options 333 * Options for forcing the length of specified fields in the 334 * returned pattern to match those in the skeleton (when this 335 * would not happen otherwise). For default behavior, use 336 * UDATPG_MATCH_NO_OPTIONS. 337 * @param status 338 * Output param set to success/failure code on exit, 339 * which must not indicate a failure before the function call. 340 * @return bestPattern 341 * The best pattern found from the given skeleton. 342 * @stable ICU 4.4 343 */ 344 UnicodeString getBestPattern(const UnicodeString& skeleton, 345 UDateTimePatternMatchOptions options, 346 UErrorCode& status); 347 348 349 /** 350 * Adjusts the field types (width and subtype) of a pattern to match what is 351 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a 352 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be 353 * "dd-MMMM hh:mm". This is used internally to get the best match for the 354 * input skeleton, but can also be used externally. 355 * 356 * @param pattern Input pattern 357 * @param skeleton 358 * The skeleton is a pattern containing only the variable fields. 359 * For example, "MMMdd" and "mmhh" are skeletons. 360 * @param status Output param set to success/failure code on exit, 361 * which must not indicate a failure before the function call. 362 * @return pattern adjusted to match the skeleton fields widths and subtypes. 363 * @stable ICU 3.8 364 * <p> 365 * <h4>Sample code</h4> 366 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1 367 * \snippet samples/dtptngsample/dtptngsample.cpp replaceFieldTypesExample 368 * <p> 369 */ 370 UnicodeString replaceFieldTypes(const UnicodeString& pattern, 371 const UnicodeString& skeleton, 372 UErrorCode& status); 373 374 /** 375 * Adjusts the field types (width and subtype) of a pattern to match what is 376 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a 377 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be 378 * "dd-MMMM hh:mm". This is used internally to get the best match for the 379 * input skeleton, but can also be used externally. 380 * 381 * @param pattern Input pattern 382 * @param skeleton 383 * The skeleton is a pattern containing only the variable fields. 384 * For example, "MMMdd" and "mmhh" are skeletons. 385 * @param options 386 * Options controlling whether the length of specified fields in the 387 * pattern are adjusted to match those in the skeleton (when this 388 * would not happen otherwise). For default behavior, use 389 * UDATPG_MATCH_NO_OPTIONS. 390 * @param status 391 * Output param set to success/failure code on exit, 392 * which must not indicate a failure before the function call. 393 * @return pattern adjusted to match the skeleton fields widths and subtypes. 394 * @stable ICU 4.4 395 */ 396 UnicodeString replaceFieldTypes(const UnicodeString& pattern, 397 const UnicodeString& skeleton, 398 UDateTimePatternMatchOptions options, 399 UErrorCode& status); 400 401 /** 402 * Return a list of all the skeletons (in canonical form) from this class. 403 * 404 * Call getPatternForSkeleton() to get the corresponding pattern. 405 * 406 * @param status Output param set to success/failure code on exit, 407 * which must not indicate a failure before the function call. 408 * @return StringEnumeration with the skeletons. 409 * The caller must delete the object. 410 * @stable ICU 3.8 411 */ 412 StringEnumeration* getSkeletons(UErrorCode& status) const; 413 414 /** 415 * Get the pattern corresponding to a given skeleton. 416 * @param skeleton 417 * @return pattern corresponding to a given skeleton. 418 * @stable ICU 3.8 419 */ 420 const UnicodeString& getPatternForSkeleton(const UnicodeString& skeleton) const; 421 422 /** 423 * Return a list of all the base skeletons (in canonical form) from this class. 424 * 425 * @param status Output param set to success/failure code on exit, 426 * which must not indicate a failure before the function call. 427 * @return a StringEnumeration with the base skeletons. 428 * The caller must delete the object. 429 * @stable ICU 3.8 430 */ 431 StringEnumeration* getBaseSkeletons(UErrorCode& status) const; 432 433 #ifndef U_HIDE_INTERNAL_API 434 /** 435 * Return a list of redundant patterns are those which if removed, make no 436 * difference in the resulting getBestPattern values. This method returns a 437 * list of them, to help check the consistency of the patterns used to build 438 * this generator. 439 * 440 * @param status Output param set to success/failure code on exit, 441 * which must not indicate a failure before the function call. 442 * @return a StringEnumeration with the redundant pattern. 443 * The caller must delete the object. 444 * @internal ICU 3.8 445 */ 446 StringEnumeration* getRedundants(UErrorCode& status); 447 #endif /* U_HIDE_INTERNAL_API */ 448 449 /** 450 * The decimal value is used in formatting fractions of seconds. If the 451 * skeleton contains fractional seconds, then this is used with the 452 * fractional seconds. For example, suppose that the input pattern is 453 * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and 454 * the decimal string is ",". Then the resulting pattern is modified to be 455 * "H:mm:ss,SSSS" 456 * 457 * @param decimal 458 * @stable ICU 3.8 459 */ 460 void setDecimal(const UnicodeString& decimal); 461 462 /** 463 * Getter corresponding to setDecimal. 464 * @return UnicodeString corresponding to the decimal point 465 * @stable ICU 3.8 466 */ 467 const UnicodeString& getDecimal() const; 468 469 /** 470 * ICU "poor man's RTTI", returns a UClassID for the actual class. 471 * 472 * @stable ICU 3.8 473 */ 474 virtual UClassID getDynamicClassID() const; 475 476 /** 477 * ICU "poor man's RTTI", returns a UClassID for this class. 478 * 479 * @stable ICU 3.8 480 */ 481 static UClassID U_EXPORT2 getStaticClassID(void); 482 483 private: 484 /** 485 * Constructor. 486 * @stable ICU 3.8 487 */ 488 DateTimePatternGenerator(UErrorCode & status); 489 490 /** 491 * Constructor. 492 * @stable ICU 3.8 493 */ 494 DateTimePatternGenerator(const Locale& locale, UErrorCode & status); 495 496 /** 497 * Copy constructor. 498 * @param other DateTimePatternGenerator to copy 499 * @stable ICU 3.8 500 */ 501 DateTimePatternGenerator(const DateTimePatternGenerator& other); 502 503 /** 504 * Default assignment operator. 505 * @param other DateTimePatternGenerator to copy 506 * @stable ICU 3.8 507 */ 508 DateTimePatternGenerator& operator=(const DateTimePatternGenerator& other); 509 510 Locale pLocale; // pattern locale 511 FormatParser *fp; 512 DateTimeMatcher* dtMatcher; 513 DistanceInfo *distanceInfo; 514 PatternMap *patternMap; 515 UnicodeString appendItemFormats[UDATPG_FIELD_COUNT]; 516 UnicodeString appendItemNames[UDATPG_FIELD_COUNT]; 517 UnicodeString dateTimeFormat; 518 UnicodeString decimal; 519 DateTimeMatcher *skipMatcher; 520 Hashtable *fAvailableFormatKeyHash; 521 UnicodeString emptyString; 522 char16_t fDefaultHourFormatChar; 523 524 int32_t fAllowedHourFormats[7]; // Actually an array of AllowedHourFormat enum type, ending with UNKNOWN. 525 526 /* internal flags masks for adjustFieldTypes etc. */ 527 enum { 528 kDTPGNoFlags = 0, 529 kDTPGFixFractionalSeconds = 1, 530 kDTPGSkeletonUsesCapJ = 2 531 // with #13183, no longer need flags for b, B 532 }; 533 534 void initData(const Locale &locale, UErrorCode &status); 535 void addCanonicalItems(UErrorCode &status); 536 void addICUPatterns(const Locale& locale, UErrorCode& status); 537 void hackTimes(const UnicodeString& hackPattern, UErrorCode& status); 538 void getCalendarTypeToUse(const Locale& locale, CharString& destination, UErrorCode& err); 539 void consumeShortTimePattern(const UnicodeString& shortTimePattern, UErrorCode& status); 540 void addCLDRData(const Locale& locale, UErrorCode& status); 541 UDateTimePatternConflict addPatternWithSkeleton(const UnicodeString& pattern, const UnicodeString * skeletonToUse, UBool override, UnicodeString& conflictingPattern, UErrorCode& status); 542 void initHashtable(UErrorCode& status); 543 void setDateTimeFromCalendar(const Locale& locale, UErrorCode& status); 544 void setDecimalSymbols(const Locale& locale, UErrorCode& status); 545 UDateTimePatternField getAppendFormatNumber(const char* field) const; 546 UDateTimePatternField getAppendNameNumber(const char* field) const; 547 UnicodeString& getMutableAppendItemName(UDateTimePatternField field); 548 void getAppendName(UDateTimePatternField field, UnicodeString& value); 549 UnicodeString mapSkeletonMetacharacters(const UnicodeString& patternForm, int32_t* flags, UErrorCode& status); 550 int32_t getCanonicalIndex(const UnicodeString& field); 551 const UnicodeString* getBestRaw(DateTimeMatcher& source, int32_t includeMask, DistanceInfo* missingFields, const PtnSkeleton** specifiedSkeletonPtr = 0); 552 UnicodeString adjustFieldTypes(const UnicodeString& pattern, const PtnSkeleton* specifiedSkeleton, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS); 553 UnicodeString getBestAppending(int32_t missingFields, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS); 554 int32_t getTopBitNumber(int32_t foundMask); 555 void setAvailableFormat(const UnicodeString &key, UErrorCode& status); 556 UBool isAvailableFormatSet(const UnicodeString &key) const; 557 void copyHashtable(Hashtable *other, UErrorCode &status); 558 UBool isCanonicalItem(const UnicodeString& item) const; 559 static void U_CALLCONV loadAllowedHourFormatsData(UErrorCode &status); 560 void getAllowedHourFormats(const Locale &locale, UErrorCode &status); 561 562 struct AppendItemFormatsSink; 563 struct AppendItemNamesSink; 564 struct AvailableFormatsSink; 565 } ;// end class DateTimePatternGenerator 566 567 U_NAMESPACE_END 568 569 #endif 570
