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