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