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