datefmt.h (42284B)
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 DATEFMT.H 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 02/19/97 aliu Converted from java. 15 * 04/01/97 aliu Added support for centuries. 16 * 07/23/98 stephen JDK 1.2 sync 17 * 11/15/99 weiv Added support for week of year/day of week formatting 18 ******************************************************************************** 19 */ 20 21 #ifndef DATEFMT_H 22 #define DATEFMT_H 23 24 #include "unicode/utypes.h" 25 26 #if U_SHOW_CPLUSPLUS_API 27 28 #if !UCONFIG_NO_FORMATTING 29 30 #include "unicode/udat.h" 31 #include "unicode/calendar.h" 32 #include "unicode/numfmt.h" 33 #include "unicode/format.h" 34 #include "unicode/locid.h" 35 #include "unicode/enumset.h" 36 #include "unicode/udisplaycontext.h" 37 38 /** 39 * \file 40 * \brief C++ API: Abstract class for converting dates. 41 */ 42 43 U_NAMESPACE_BEGIN 44 45 class TimeZone; 46 class DateTimePatternGenerator; 47 48 /** 49 * DateFormat is an abstract class for a family of classes that convert dates and 50 * times from their internal representations to textual form and back again in a 51 * language-independent manner. Converting from the internal representation (milliseconds 52 * since midnight, January 1, 1970) to text is known as "formatting," and converting 53 * from text to millis is known as "parsing." We currently define only one concrete 54 * subclass of DateFormat: SimpleDateFormat, which can handle pretty much all normal 55 * date formatting and parsing actions. 56 * <P> 57 * DateFormat helps you to format and parse dates for any locale. Your code can 58 * be completely independent of the locale conventions for months, days of the 59 * week, or even the calendar format: lunar vs. solar. 60 * <P> 61 * To format a date for the current Locale, use one of the static factory 62 * methods: 63 * <pre> 64 * \code 65 * DateFormat* dfmt = DateFormat::createDateInstance(); 66 * UDate myDate = Calendar::getNow(); 67 * UnicodeString myString; 68 * myString = dfmt->format( myDate, myString ); 69 * \endcode 70 * </pre> 71 * If you are formatting multiple numbers, it is more efficient to get the 72 * format and use it multiple times so that the system doesn't have to fetch the 73 * information about the local language and country conventions multiple times. 74 * <pre> 75 * \code 76 * DateFormat* df = DateFormat::createDateInstance(); 77 * UnicodeString myString; 78 * UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values 79 * for (int32_t i = 0; i < 3; ++i) { 80 * myString.remove(); 81 * cout << df->format( myDateArr[i], myString ) << endl; 82 * } 83 * \endcode 84 * </pre> 85 * To get specific fields of a date, you can use UFieldPosition to 86 * get specific fields. 87 * <pre> 88 * \code 89 * DateFormat* dfmt = DateFormat::createDateInstance(); 90 * FieldPosition pos(DateFormat::YEAR_FIELD); 91 * UnicodeString myString; 92 * myString = dfmt->format( myDate, myString ); 93 * cout << myString << endl; 94 * cout << pos.getBeginIndex() << "," << pos. getEndIndex() << endl; 95 * \endcode 96 * </pre> 97 * To format a date for a different Locale, specify it in the call to 98 * createDateInstance(). 99 * <pre> 100 * \code 101 * DateFormat* df = 102 * DateFormat::createDateInstance( DateFormat::SHORT, Locale::getFrance()); 103 * \endcode 104 * </pre> 105 * You can use a DateFormat to parse also. 106 * <pre> 107 * \code 108 * UErrorCode status = U_ZERO_ERROR; 109 * UDate myDate = df->parse(myString, status); 110 * \endcode 111 * </pre> 112 * Use createDateInstance() to produce the normal date format for that country. 113 * There are other static factory methods available. Use createTimeInstance() 114 * to produce the normal time format for that country. Use createDateTimeInstance() 115 * to produce a DateFormat that formats both date and time. You can pass in 116 * different options to these factory methods to control the length of the 117 * result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the 118 * locale, but generally: 119 * <ul type=round> 120 * <li> SHORT is completely numeric, such as 12/13/52 or 3:30pm 121 * <li> MEDIUM is longer, such as Jan 12, 1952 122 * <li> LONG is longer, such as January 12, 1952 or 3:30:32pm 123 * <li> FULL is pretty completely specified, such as 124 * Tuesday, April 12, 1952 AD or 3:30:42pm PST. 125 * </ul> 126 * You can also set the time zone on the format if you wish. If you want even 127 * more control over the format or parsing, (or want to give your users more 128 * control), you can try casting the DateFormat you get from the factory methods 129 * to a SimpleDateFormat. This will work for the majority of countries; just 130 * remember to check getDynamicClassID() before carrying out the cast. 131 * <P> 132 * You can also use forms of the parse and format methods with ParsePosition and 133 * FieldPosition to allow you to 134 * <ul type=round> 135 * <li> Progressively parse through pieces of a string. 136 * <li> Align any particular field, or find out where it is for selection 137 * on the screen. 138 * </ul> 139 * 140 * <p><em>User subclasses are not supported.</em> While clients may write 141 * subclasses, such code will not necessarily work and will not be 142 * guaranteed to work stably from release to release. 143 */ 144 class U_I18N_API_CLASS DateFormat : public Format { 145 public: 146 147 /** 148 * Constants for various style patterns. These reflect the order of items in 149 * the DateTimePatterns resource. There are 4 time patterns, 4 date patterns, 150 * the default date-time pattern, and 4 date-time patterns. Each block of 4 values 151 * in the resource occurs in the order full, long, medium, short. 152 * @stable ICU 2.4 153 */ 154 enum EStyle 155 { 156 kNone = -1, 157 158 kFull = 0, 159 kLong = 1, 160 kMedium = 2, 161 kShort = 3, 162 163 kDateOffset = kShort + 1, 164 // kFull + kDateOffset = 4 165 // kLong + kDateOffset = 5 166 // kMedium + kDateOffset = 6 167 // kShort + kDateOffset = 7 168 169 kDateTime = 8, 170 // Default DateTime 171 172 kDateTimeOffset = kDateTime + 1, 173 // kFull + kDateTimeOffset = 9 174 // kLong + kDateTimeOffset = 10 175 // kMedium + kDateTimeOffset = 11 176 // kShort + kDateTimeOffset = 12 177 178 // relative dates 179 kRelative = (1 << 7), 180 181 kFullRelative = (kFull | kRelative), 182 183 kLongRelative = kLong | kRelative, 184 185 kMediumRelative = kMedium | kRelative, 186 187 kShortRelative = kShort | kRelative, 188 189 190 kDefault = kMedium, 191 192 193 194 /** 195 * These constants are provided for backwards compatibility only. 196 * Please use the C++ style constants defined above. 197 */ 198 FULL = kFull, 199 LONG = kLong, 200 MEDIUM = kMedium, 201 SHORT = kShort, 202 DEFAULT = kDefault, 203 DATE_OFFSET = kDateOffset, 204 NONE = kNone, 205 DATE_TIME = kDateTime 206 }; 207 208 /** 209 * Destructor. 210 * @stable ICU 2.0 211 */ 212 U_I18N_API virtual ~DateFormat(); 213 214 /** 215 * Clones this object polymorphically. 216 * The caller owns the result and should delete it when done. 217 * @return clone, or nullptr if an error occurred 218 * @stable ICU 2.0 219 */ 220 U_I18N_API virtual DateFormat* clone() const override = 0; 221 222 /** 223 * Equality operator. Returns true if the two formats have the same behavior. 224 * @stable ICU 2.0 225 */ 226 U_I18N_API virtual bool operator==(const Format&) const override; 227 228 229 using Format::format; 230 231 /** 232 * Format an object to produce a string. This method handles Formattable 233 * objects with a UDate type. If a the Formattable object type is not a Date, 234 * then it returns a failing UErrorCode. 235 * 236 * @param obj The object to format. Must be a Date. 237 * @param appendTo Output parameter to receive result. 238 * Result is appended to existing contents. 239 * @param pos On input: an alignment field, if desired. 240 * On output: the offsets of the alignment field. 241 * @param status Output param filled with success/failure status. 242 * @return Reference to 'appendTo' parameter. 243 * @stable ICU 2.0 244 */ 245 U_I18N_API virtual UnicodeString& format(const Formattable& obj, 246 UnicodeString& appendTo, 247 FieldPosition& pos, 248 UErrorCode& status) const override; 249 250 /** 251 * Format an object to produce a string. This method handles Formattable 252 * objects with a UDate type. If a the Formattable object type is not a Date, 253 * then it returns a failing UErrorCode. 254 * 255 * @param obj The object to format. Must be a Date. 256 * @param appendTo Output parameter to receive result. 257 * Result is appended to existing contents. 258 * @param posIter On return, can be used to iterate over positions 259 * of fields generated by this format call. Field values 260 * are defined in UDateFormatField. Can be nullptr. 261 * @param status Output param filled with success/failure status. 262 * @return Reference to 'appendTo' parameter. 263 * @stable ICU 4.4 264 */ 265 U_I18N_API virtual UnicodeString& format(const Formattable& obj, 266 UnicodeString& appendTo, 267 FieldPositionIterator* posIter, 268 UErrorCode& status) const override; 269 /** 270 * Formats a date into a date/time string. This is an abstract method which 271 * concrete subclasses must implement. 272 * <P> 273 * On input, the FieldPosition parameter may have its "field" member filled with 274 * an enum value specifying a field. On output, the FieldPosition will be filled 275 * in with the text offsets for that field. 276 * <P> For example, given a time text 277 * "1996.07.10 AD at 15:08:56 PDT", if the given fieldPosition.field is 278 * UDAT_YEAR_FIELD, the offsets fieldPosition.beginIndex and 279 * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively. 280 * <P> Notice 281 * that if the same time field appears more than once in a pattern, the status will 282 * be set for the first occurrence of that time field. For instance, 283 * formatting a UDate to the time string "1 PM PDT (Pacific Daylight Time)" 284 * using the pattern "h a z (zzzz)" and the alignment field 285 * DateFormat::TIMEZONE_FIELD, the offsets fieldPosition.beginIndex and 286 * fieldPosition.getEndIndex will be set to 5 and 8, respectively, for the first 287 * occurrence of the timezone pattern character 'z'. 288 * 289 * @param cal Calendar set to the date and time to be formatted 290 * into a date/time string. When the calendar type is 291 * different from the internal calendar held by this 292 * DateFormat instance, the date and the time zone will 293 * be inherited from the input calendar, but other calendar 294 * field values will be calculated by the internal calendar. 295 * @param appendTo Output parameter to receive result. 296 * Result is appended to existing contents. 297 * @param fieldPosition On input: an alignment field, if desired (see examples above) 298 * On output: the offsets of the alignment field (see examples above) 299 * @return Reference to 'appendTo' parameter. 300 * @stable ICU 2.1 301 */ 302 U_I18N_API virtual UnicodeString& format(Calendar& cal, 303 UnicodeString& appendTo, 304 FieldPosition& fieldPosition) const = 0; 305 306 /** 307 * Formats a date into a date/time string. Subclasses should implement this method. 308 * 309 * @param cal Calendar set to the date and time to be formatted 310 * into a date/time string. When the calendar type is 311 * different from the internal calendar held by this 312 * DateFormat instance, the date and the time zone will 313 * be inherited from the input calendar, but other calendar 314 * field values will be calculated by the internal calendar. 315 * @param appendTo Output parameter to receive result. 316 * Result is appended to existing contents. 317 * @param posIter On return, can be used to iterate over positions 318 * of fields generated by this format call. Field values 319 * are defined in UDateFormatField. Can be nullptr. 320 * @param status error status. 321 * @return Reference to 'appendTo' parameter. 322 * @stable ICU 4.4 323 */ 324 U_I18N_API virtual UnicodeString& format(Calendar& cal, 325 UnicodeString& appendTo, 326 FieldPositionIterator* posIter, 327 UErrorCode& status) const; 328 /** 329 * Formats a UDate into a date/time string. 330 * <P> 331 * On input, the FieldPosition parameter may have its "field" member filled with 332 * an enum value specifying a field. On output, the FieldPosition will be filled 333 * in with the text offsets for that field. 334 * <P> For example, given a time text 335 * "1996.07.10 AD at 15:08:56 PDT", if the given fieldPosition.field is 336 * UDAT_YEAR_FIELD, the offsets fieldPosition.beginIndex and 337 * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively. 338 * <P> Notice 339 * that if the same time field appears more than once in a pattern, the status will 340 * be set for the first occurrence of that time field. For instance, 341 * formatting a UDate to the time string "1 PM PDT (Pacific Daylight Time)" 342 * using the pattern "h a z (zzzz)" and the alignment field 343 * DateFormat::TIMEZONE_FIELD, the offsets fieldPosition.beginIndex and 344 * fieldPosition.getEndIndex will be set to 5 and 8, respectively, for the first 345 * occurrence of the timezone pattern character 'z'. 346 * 347 * @param date UDate to be formatted into a date/time string. 348 * @param appendTo Output parameter to receive result. 349 * Result is appended to existing contents. 350 * @param fieldPosition On input: an alignment field, if desired (see examples above) 351 * On output: the offsets of the alignment field (see examples above) 352 * @return Reference to 'appendTo' parameter. 353 * @stable ICU 2.0 354 */ 355 U_I18N_API UnicodeString& format(UDate date, 356 UnicodeString& appendTo, 357 FieldPosition& fieldPosition) const; 358 359 /** 360 * Formats a UDate into a date/time string. 361 * 362 * @param date UDate to be formatted into a date/time string. 363 * @param appendTo Output parameter to receive result. 364 * Result is appended to existing contents. 365 * @param posIter On return, can be used to iterate over positions 366 * of fields generated by this format call. Field values 367 * are defined in UDateFormatField. Can be nullptr. 368 * @param status error status. 369 * @return Reference to 'appendTo' parameter. 370 * @stable ICU 4.4 371 */ 372 U_I18N_API UnicodeString& format(UDate date, 373 UnicodeString& appendTo, 374 FieldPositionIterator* posIter, 375 UErrorCode& status) const; 376 /** 377 * Formats a UDate into a date/time string. If there is a problem, you won't 378 * know, using this method. Use the overloaded format() method which takes a 379 * FieldPosition& to detect formatting problems. 380 * 381 * @param date The UDate value to be formatted into a string. 382 * @param appendTo Output parameter to receive result. 383 * Result is appended to existing contents. 384 * @return Reference to 'appendTo' parameter. 385 * @stable ICU 2.0 386 */ 387 U_I18N_API UnicodeString& format(UDate date, UnicodeString& appendTo) const; 388 389 /** 390 * Parse a date/time string. For example, a time text "07/10/96 4:5 PM, PDT" 391 * will be parsed into a UDate that is equivalent to Date(837039928046). 392 * Parsing begins at the beginning of the string and proceeds as far as 393 * possible. Assuming no parse errors were encountered, this function 394 * doesn't return any information about how much of the string was consumed 395 * by the parsing. If you need that information, use the version of 396 * parse() that takes a ParsePosition. 397 * <P> 398 * By default, parsing is lenient: If the input is not in the form used by 399 * this object's format method but can still be parsed as a date, then the 400 * parse succeeds. Clients may insist on strict adherence to the format by 401 * calling setLenient(false). 402 * @see DateFormat::setLenient(boolean) 403 * <P> 404 * Note that the normal date formats associated with some calendars - such 405 * as the Chinese lunar calendar - do not specify enough fields to enable 406 * dates to be parsed unambiguously. In the case of the Chinese lunar 407 * calendar, while the year within the current 60-year cycle is specified, 408 * the number of such cycles since the start date of the calendar (in the 409 * ERA field of the Calendar object) is not normally part of the format, 410 * and parsing may assume the wrong era. For cases such as this it is 411 * recommended that clients parse using the method 412 * parse(const UnicodeString&, Calendar& cal, ParsePosition&) 413 * with the Calendar passed in set to the current date, or to a date 414 * within the era/cycle that should be assumed if absent in the format. 415 * 416 * @param text The date/time string to be parsed into a UDate value. 417 * @param status Output param to be set to success/failure code. If 418 * 'text' cannot be parsed, it will be set to a failure 419 * code. 420 * @return The parsed UDate value, if successful. 421 * @stable ICU 2.0 422 */ 423 U_I18N_API virtual UDate parse(const UnicodeString& text, UErrorCode& status) const; 424 425 /** 426 * Parse a date/time string beginning at the given parse position. For 427 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 428 * that is equivalent to Date(837039928046). 429 * <P> 430 * By default, parsing is lenient: If the input is not in the form used by 431 * this object's format method but can still be parsed as a date, then the 432 * parse succeeds. Clients may insist on strict adherence to the format by 433 * calling setLenient(false). 434 * @see DateFormat::setLenient(boolean) 435 * 436 * @param text The date/time string to be parsed. 437 * @param cal A Calendar set on input to the date and time to be used for 438 * missing values in the date/time string being parsed, and set 439 * on output to the parsed date/time. When the calendar type is 440 * different from the internal calendar held by this DateFormat 441 * instance, the internal calendar will be cloned to a work 442 * calendar set to the same milliseconds and time zone as the 443 * cal parameter, field values will be parsed based on the work 444 * calendar, then the result (milliseconds and time zone) will 445 * be set in this calendar. 446 * @param pos On input, the position at which to start parsing; on 447 * output, the position at which parsing terminated, or the 448 * start position if the parse failed. 449 * @stable ICU 2.1 450 */ 451 U_I18N_API virtual void parse(const UnicodeString& text, 452 Calendar& cal, 453 ParsePosition& pos) const = 0; 454 455 /** 456 * Parse a date/time string beginning at the given parse position. For 457 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 458 * that is equivalent to Date(837039928046). 459 * <P> 460 * By default, parsing is lenient: If the input is not in the form used by 461 * this object's format method but can still be parsed as a date, then the 462 * parse succeeds. Clients may insist on strict adherence to the format by 463 * calling setLenient(false). 464 * @see DateFormat::setLenient(boolean) 465 * <P> 466 * Note that the normal date formats associated with some calendars - such 467 * as the Chinese lunar calendar - do not specify enough fields to enable 468 * dates to be parsed unambiguously. In the case of the Chinese lunar 469 * calendar, while the year within the current 60-year cycle is specified, 470 * the number of such cycles since the start date of the calendar (in the 471 * ERA field of the Calendar object) is not normally part of the format, 472 * and parsing may assume the wrong era. For cases such as this it is 473 * recommended that clients parse using the method 474 * parse(const UnicodeString&, Calendar& cal, ParsePosition&) 475 * with the Calendar passed in set to the current date, or to a date 476 * within the era/cycle that should be assumed if absent in the format. 477 * 478 * @param text The date/time string to be parsed into a UDate value. 479 * @param pos On input, the position at which to start parsing; on 480 * output, the position at which parsing terminated, or the 481 * start position if the parse failed. 482 * @return A valid UDate if the input could be parsed. 483 * @stable ICU 2.0 484 */ 485 U_I18N_API UDate parse(const UnicodeString& text, ParsePosition& pos) const; 486 487 /** 488 * Parse a string to produce an object. This methods handles parsing of 489 * date/time strings into Formattable objects with UDate types. 490 * <P> 491 * Before calling, set parse_pos.index to the offset you want to start 492 * parsing at in the source. After calling, parse_pos.index is the end of 493 * the text you parsed. If error occurs, index is unchanged. 494 * <P> 495 * When parsing, leading whitespace is discarded (with a successful parse), 496 * while trailing whitespace is left as is. 497 * <P> 498 * See Format::parseObject() for more. 499 * 500 * @param source The string to be parsed into an object. 501 * @param result Formattable to be set to the parse result. 502 * If parse fails, return contents are undefined. 503 * @param parse_pos The position to start parsing at. Upon return 504 * this param is set to the position after the 505 * last character successfully parsed. If the 506 * source is not parsed successfully, this param 507 * will remain unchanged. 508 * @stable ICU 2.0 509 */ 510 U_I18N_API virtual void parseObject(const UnicodeString& source, 511 Formattable& result, 512 ParsePosition& parse_pos) const override; 513 514 /** 515 * Create a default date/time formatter that uses the SHORT style for both 516 * the date and the time. 517 * 518 * @return A date/time formatter which the caller owns. 519 * @stable ICU 2.0 520 */ 521 U_I18N_API static DateFormat* U_EXPORT2 createInstance(); 522 523 /** 524 * Creates a time formatter with the given formatting style for the given 525 * locale. 526 * 527 * @param style The given formatting style. For example, 528 * SHORT for "h:mm a" in the US locale. Relative 529 * time styles are not currently supported. 530 * @param aLocale The given locale. 531 * @return A time formatter which the caller owns. 532 * @stable ICU 2.0 533 */ 534 U_I18N_API static DateFormat* U_EXPORT2 535 createTimeInstance(EStyle style = kDefault, const Locale& aLocale = Locale::getDefault()); 536 537 /** 538 * Creates a date formatter with the given formatting style for the given 539 * const locale. 540 * 541 * @param style The given formatting style. For example, SHORT for "M/d/yy" in the 542 * US locale. As currently implemented, relative date formatting only 543 * affects a limited range of calendar days before or after the 544 * current date, based on the CLDR <field type="day">/<relative> data: 545 * For example, in English, "Yesterday", "Today", and "Tomorrow". 546 * Outside of this range, dates are formatted using the corresponding 547 * non-relative style. 548 * @param aLocale The given locale. 549 * @return A date formatter which the caller owns. 550 * @stable ICU 2.0 551 */ 552 U_I18N_API static DateFormat* U_EXPORT2 553 createDateInstance(EStyle style = kDefault, const Locale& aLocale = Locale::getDefault()); 554 555 /** 556 * Creates a date/time formatter with the given formatting styles for the 557 * given locale. 558 * 559 * @param dateStyle The given formatting style for the date portion of the result. 560 * For example, SHORT for "M/d/yy" in the US locale. As currently 561 * implemented, relative date formatting only affects a limited range 562 * of calendar days before or after the current date, based on the 563 * CLDR <field type="day">/<relative> data: For example, in English, 564 * "Yesterday", "Today", and "Tomorrow". Outside of this range, dates 565 * are formatted using the corresponding non-relative style. 566 * @param timeStyle The given formatting style for the time portion of the result. 567 * For example, SHORT for "h:mm a" in the US locale. Relative 568 * time styles are not currently supported. 569 * @param aLocale The given locale. 570 * @return A date/time formatter which the caller owns. 571 * @stable ICU 2.0 572 */ 573 U_I18N_API static DateFormat* U_EXPORT2 574 createDateTimeInstance(EStyle dateStyle = kDefault, 575 EStyle timeStyle = kDefault, 576 const Locale& aLocale = Locale::getDefault()); 577 578 #ifndef U_HIDE_INTERNAL_API 579 /** 580 * Returns the best pattern given a skeleton and locale. 581 * @param locale the locale 582 * @param skeleton the skeleton 583 * @param status ICU error returned here 584 * @return the best pattern. 585 * @internal For ICU use only. 586 */ 587 U_I18N_API static UnicodeString getBestPattern(const Locale& locale, 588 const UnicodeString& skeleton, 589 UErrorCode& status); 590 #endif /* U_HIDE_INTERNAL_API */ 591 592 /** 593 * Creates a date/time formatter for the given skeleton and 594 * default locale. 595 * 596 * @param skeleton The skeleton e.g "yMMMMd." Fields in the skeleton can 597 * be in any order, and this method uses the locale to 598 * map the skeleton to a pattern that includes locale 599 * specific separators with the fields in the appropriate 600 * order for that locale. 601 * @param status Any error returned here. 602 * @return A date/time formatter which the caller owns. 603 * @stable ICU 55 604 */ 605 U_I18N_API static DateFormat* U_EXPORT2 createInstanceForSkeleton(const UnicodeString& skeleton, 606 UErrorCode& status); 607 608 /** 609 * Creates a date/time formatter for the given skeleton and locale. 610 * 611 * @param skeleton The skeleton e.g "yMMMMd." Fields in the skeleton can 612 * be in any order, and this method uses the locale to 613 * map the skeleton to a pattern that includes locale 614 * specific separators with the fields in the appropriate 615 * order for that locale. 616 * @param locale The given locale. 617 * @param status Any error returned here. 618 * @return A date/time formatter which the caller owns. 619 * @stable ICU 55 620 */ 621 U_I18N_API static DateFormat* U_EXPORT2 createInstanceForSkeleton(const UnicodeString& skeleton, 622 const Locale& locale, 623 UErrorCode& status); 624 625 /** 626 * Creates a date/time formatter for the given skeleton and locale. 627 * 628 * @param calendarToAdopt the calendar returned DateFormat is to use. 629 * @param skeleton The skeleton e.g "yMMMMd." Fields in the skeleton can 630 * be in any order, and this method uses the locale to 631 * map the skeleton to a pattern that includes locale 632 * specific separators with the fields in the appropriate 633 * order for that locale. 634 * @param locale The given locale. 635 * @param status Any error returned here. 636 * @return A date/time formatter which the caller owns. 637 * @stable ICU 55 638 */ 639 U_I18N_API static DateFormat* U_EXPORT2 createInstanceForSkeleton(Calendar* calendarToAdopt, 640 const UnicodeString& skeleton, 641 const Locale& locale, 642 UErrorCode& status); 643 644 /** 645 * Gets the set of locales for which DateFormats are installed. 646 * @param count Filled in with the number of locales in the list that is returned. 647 * @return the set of locales for which DateFormats are installed. The caller 648 * does NOT own this list and must not delete it. 649 * @stable ICU 2.0 650 */ 651 U_I18N_API static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); 652 653 /** 654 * Returns whether both date/time parsing in the encapsulated Calendar object and DateFormat whitespace & 655 * numeric processing is lenient. 656 * @stable ICU 2.0 657 */ 658 U_I18N_API virtual UBool isLenient() const; 659 660 /** 661 * Specifies whether date/time parsing is to be lenient. With 662 * lenient parsing, the parser may use heuristics to interpret inputs that 663 * do not precisely match this object's format. Without lenient parsing, 664 * inputs must match this object's format more closely. 665 * 666 * Note: ICU 53 introduced finer grained control of leniency (and added 667 * new control points) making the preferred method a combination of 668 * setCalendarLenient() & setBooleanAttribute() calls. 669 * This method supports prior functionality but may not support all 670 * future leniency control & behavior of DateFormat. For control of pre 53 leniency, 671 * Calendar and DateFormat whitespace & numeric tolerance, this method is safe to 672 * use. However, mixing leniency control via this method and modification of the 673 * newer attributes via setBooleanAttribute() may produce undesirable 674 * results. 675 * 676 * @param lenient True specifies date/time interpretation to be lenient. 677 * @see Calendar::setLenient 678 * @stable ICU 2.0 679 */ 680 U_I18N_API virtual void setLenient(UBool lenient); 681 682 683 /** 684 * Returns whether date/time parsing in the encapsulated Calendar object processing is lenient. 685 * @stable ICU 53 686 */ 687 U_I18N_API virtual UBool isCalendarLenient() const; 688 689 /** 690 * Specifies whether encapsulated Calendar date/time parsing is to be lenient. With 691 * lenient parsing, the parser may use heuristics to interpret inputs that 692 * do not precisely match this object's format. Without lenient parsing, 693 * inputs must match this object's format more closely. 694 * @param lenient when true, parsing is lenient 695 * @see com.ibm.icu.util.Calendar#setLenient 696 * @stable ICU 53 697 */ 698 U_I18N_API virtual void setCalendarLenient(UBool lenient); 699 700 701 /** 702 * Gets the calendar associated with this date/time formatter. 703 * The calendar is owned by the formatter and must not be modified. 704 * Also, the calendar does not reflect the results of a parse operation. 705 * To parse to a calendar, use {@link #parse(const UnicodeString&, Calendar& cal, ParsePosition&) const parse(const UnicodeString&, Calendar& cal, ParsePosition&)} 706 * @return the calendar associated with this date/time formatter. 707 * @stable ICU 2.0 708 */ 709 U_I18N_API virtual const Calendar* getCalendar() const; 710 711 /** 712 * Set the calendar to be used by this date format. Initially, the default 713 * calendar for the specified or default locale is used. The caller should 714 * not delete the Calendar object after it is adopted by this call. 715 * Adopting a new calendar will change to the default symbols. 716 * 717 * @param calendarToAdopt Calendar object to be adopted. 718 * @stable ICU 2.0 719 */ 720 U_I18N_API virtual void adoptCalendar(Calendar* calendarToAdopt); 721 722 /** 723 * Set the calendar to be used by this date format. Initially, the default 724 * calendar for the specified or default locale is used. 725 * 726 * @param newCalendar Calendar object to be set. 727 * @stable ICU 2.0 728 */ 729 U_I18N_API virtual void setCalendar(const Calendar& newCalendar); 730 731 /** 732 * Gets the number formatter which this date/time formatter uses to format 733 * and parse the numeric portions of the pattern. 734 * @return the number formatter which this date/time formatter uses. 735 * @stable ICU 2.0 736 */ 737 U_I18N_API virtual const NumberFormat* getNumberFormat() const; 738 739 /** 740 * Allows you to set the number formatter. The caller should 741 * not delete the NumberFormat object after it is adopted by this call. 742 * @param formatToAdopt NumberFormat object to be adopted. 743 * @stable ICU 2.0 744 */ 745 U_I18N_API virtual void adoptNumberFormat(NumberFormat* formatToAdopt); 746 747 /** 748 * Allows you to set the number formatter. 749 * @param newNumberFormat NumberFormat object to be set. 750 * @stable ICU 2.0 751 */ 752 U_I18N_API virtual void setNumberFormat(const NumberFormat& newNumberFormat); 753 754 /** 755 * Returns a reference to the TimeZone used by this DateFormat's calendar. 756 * @return the time zone associated with the calendar of DateFormat. 757 * @stable ICU 2.0 758 */ 759 U_I18N_API virtual const TimeZone& getTimeZone() const; 760 761 /** 762 * Sets the time zone for the calendar of this DateFormat object. The caller 763 * no longer owns the TimeZone object and should not delete it after this call. 764 * @param zoneToAdopt the TimeZone to be adopted. 765 * @stable ICU 2.0 766 */ 767 U_I18N_API virtual void adoptTimeZone(TimeZone* zoneToAdopt); 768 769 /** 770 * Sets the time zone for the calendar of this DateFormat object. 771 * @param zone the new time zone. 772 * @stable ICU 2.0 773 */ 774 U_I18N_API virtual void setTimeZone(const TimeZone& zone); 775 776 /** 777 * Set a particular UDisplayContext value in the formatter, such as 778 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. 779 * @param value The UDisplayContext value to set. 780 * @param status Input/output status. If at entry this indicates a failure 781 * status, the function will do nothing; otherwise this will be 782 * updated with any new status from the function. 783 * @stable ICU 53 784 */ 785 U_I18N_API virtual void setContext(UDisplayContext value, UErrorCode& status); 786 787 /** 788 * Get the formatter's UDisplayContext value for the specified UDisplayContextType, 789 * such as UDISPCTX_TYPE_CAPITALIZATION. 790 * @param type The UDisplayContextType whose value to return 791 * @param status Input/output status. If at entry this indicates a failure 792 * status, the function will do nothing; otherwise this will be 793 * updated with any new status from the function. 794 * @return The UDisplayContextValue for the specified type. 795 * @stable ICU 53 796 */ 797 U_I18N_API virtual UDisplayContext getContext(UDisplayContextType type, UErrorCode& status) const; 798 799 /** 800 * Sets an boolean attribute on this DateFormat. 801 * May return U_UNSUPPORTED_ERROR if this instance does not support 802 * the specified attribute. 803 * @param attr the attribute to set 804 * @param newvalue new value 805 * @param status the error type 806 * @return *this - for chaining (example: format.setAttribute(...).setAttribute(...) ) 807 * @stable ICU 53 808 */ 809 U_I18N_API virtual DateFormat& U_EXPORT2 setBooleanAttribute(UDateFormatBooleanAttribute attr, 810 UBool newvalue, UErrorCode& status); 811 812 /** 813 * Returns a boolean from this DateFormat 814 * May return U_UNSUPPORTED_ERROR if this instance does not support 815 * the specified attribute. 816 * @param attr the attribute to set 817 * @param status the error type 818 * @return the attribute value. Undefined if there is an error. 819 * @stable ICU 53 820 */ 821 U_I18N_API virtual UBool U_EXPORT2 getBooleanAttribute(UDateFormatBooleanAttribute attr, 822 UErrorCode& status) const; 823 824 protected: 825 /** 826 * Default constructor. Creates a DateFormat with no Calendar or NumberFormat 827 * associated with it. This constructor depends on the subclasses to fill in 828 * the calendar and numberFormat fields. 829 * @stable ICU 2.0 830 */ 831 U_I18N_API DateFormat(); 832 833 /** 834 * Copy constructor. 835 * @stable ICU 2.0 836 */ 837 U_I18N_API DateFormat(const DateFormat&); 838 839 /** 840 * Default assignment operator. 841 * @stable ICU 2.0 842 */ 843 U_I18N_API DateFormat& operator=(const DateFormat&); 844 845 /** 846 * The calendar that DateFormat uses to produce the time field values needed 847 * to implement date/time formatting. Subclasses should generally initialize 848 * this to the default calendar for the locale associated with this DateFormat. 849 * @stable ICU 2.4 850 */ 851 Calendar* fCalendar; 852 853 /** 854 * The number formatter that DateFormat uses to format numbers in dates and 855 * times. Subclasses should generally initialize this to the default number 856 * format for the locale associated with this DateFormat. 857 * @stable ICU 2.4 858 */ 859 NumberFormat* fNumberFormat; 860 861 862 private: 863 864 /** 865 * Gets the date/time formatter with the given formatting styles for the 866 * given locale. 867 * @param dateStyle the given date formatting style. 868 * @param timeStyle the given time formatting style. 869 * @param inLocale the given locale. 870 * @return a date/time formatter, or 0 on failure. 871 */ 872 static DateFormat* U_EXPORT2 create(EStyle timeStyle, EStyle dateStyle, const Locale& inLocale); 873 874 875 /** 876 * enum set of active boolean attributes for this instance 877 */ 878 EnumSet<UDateFormatBooleanAttribute, 0, UDAT_BOOLEAN_ATTRIBUTE_COUNT> fBoolFlags; 879 880 881 UDisplayContext fCapitalizationContext; 882 friend class DateFmtKeyByStyle; 883 884 public: 885 #ifndef U_HIDE_OBSOLETE_API 886 /** 887 * Field selector for FieldPosition for DateFormat fields. 888 * @obsolete ICU 3.4 use UDateFormatField instead, since this API will be 889 * removed in that release 890 */ 891 enum EField 892 { 893 // Obsolete; use UDateFormatField instead 894 kEraField = UDAT_ERA_FIELD, 895 kYearField = UDAT_YEAR_FIELD, 896 kMonthField = UDAT_MONTH_FIELD, 897 kDateField = UDAT_DATE_FIELD, 898 kHourOfDay1Field = UDAT_HOUR_OF_DAY1_FIELD, 899 kHourOfDay0Field = UDAT_HOUR_OF_DAY0_FIELD, 900 kMinuteField = UDAT_MINUTE_FIELD, 901 kSecondField = UDAT_SECOND_FIELD, 902 kMillisecondField = UDAT_FRACTIONAL_SECOND_FIELD, 903 kDayOfWeekField = UDAT_DAY_OF_WEEK_FIELD, 904 kDayOfYearField = UDAT_DAY_OF_YEAR_FIELD, 905 kDayOfWeekInMonthField = UDAT_DAY_OF_WEEK_IN_MONTH_FIELD, 906 kWeekOfYearField = UDAT_WEEK_OF_YEAR_FIELD, 907 kWeekOfMonthField = UDAT_WEEK_OF_MONTH_FIELD, 908 kAmPmField = UDAT_AM_PM_FIELD, 909 kHour1Field = UDAT_HOUR1_FIELD, 910 kHour0Field = UDAT_HOUR0_FIELD, 911 kTimezoneField = UDAT_TIMEZONE_FIELD, 912 kYearWOYField = UDAT_YEAR_WOY_FIELD, 913 kDOWLocalField = UDAT_DOW_LOCAL_FIELD, 914 kExtendedYearField = UDAT_EXTENDED_YEAR_FIELD, 915 kJulianDayField = UDAT_JULIAN_DAY_FIELD, 916 kMillisecondsInDayField = UDAT_MILLISECONDS_IN_DAY_FIELD, 917 918 // Obsolete; use UDateFormatField instead 919 ERA_FIELD = UDAT_ERA_FIELD, 920 YEAR_FIELD = UDAT_YEAR_FIELD, 921 MONTH_FIELD = UDAT_MONTH_FIELD, 922 DATE_FIELD = UDAT_DATE_FIELD, 923 HOUR_OF_DAY1_FIELD = UDAT_HOUR_OF_DAY1_FIELD, 924 HOUR_OF_DAY0_FIELD = UDAT_HOUR_OF_DAY0_FIELD, 925 MINUTE_FIELD = UDAT_MINUTE_FIELD, 926 SECOND_FIELD = UDAT_SECOND_FIELD, 927 MILLISECOND_FIELD = UDAT_FRACTIONAL_SECOND_FIELD, 928 DAY_OF_WEEK_FIELD = UDAT_DAY_OF_WEEK_FIELD, 929 DAY_OF_YEAR_FIELD = UDAT_DAY_OF_YEAR_FIELD, 930 DAY_OF_WEEK_IN_MONTH_FIELD = UDAT_DAY_OF_WEEK_IN_MONTH_FIELD, 931 WEEK_OF_YEAR_FIELD = UDAT_WEEK_OF_YEAR_FIELD, 932 WEEK_OF_MONTH_FIELD = UDAT_WEEK_OF_MONTH_FIELD, 933 AM_PM_FIELD = UDAT_AM_PM_FIELD, 934 HOUR1_FIELD = UDAT_HOUR1_FIELD, 935 HOUR0_FIELD = UDAT_HOUR0_FIELD, 936 TIMEZONE_FIELD = UDAT_TIMEZONE_FIELD 937 }; 938 #endif /* U_HIDE_OBSOLETE_API */ 939 }; 940 941 U_NAMESPACE_END 942 943 #endif /* #if !UCONFIG_NO_FORMATTING */ 944 945 #endif /* U_SHOW_CPLUSPLUS_API */ 946 947 #endif // _DATEFMT 948 //eof