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