1 /* 2 * Copyright (C) 1997-2010, International Business Machines Corporation and 3 * others. All Rights Reserved. 4 ******************************************************************************* 5 * 6 * File SMPDTFMT.H 7 * 8 * Modification History: 9 * 10 * Date Name Description 11 * 02/19/97 aliu Converted from java. 12 * 07/09/97 helena Make ParsePosition into a class. 13 * 07/21/98 stephen Added GMT_PLUS, GMT_MINUS 14 * Changed setTwoDigitStartDate to set2DigitYearStart 15 * Changed getTwoDigitStartDate to get2DigitYearStart 16 * Removed subParseLong 17 * Removed getZoneIndex (added in DateFormatSymbols) 18 * 06/14/99 stephen Removed fgTimeZoneDataSuffix 19 * 10/14/99 aliu Updated class doc to describe 2-digit year parsing 20 * {j28 4182066}. 21 ******************************************************************************* 22 */ 23 24 #ifndef SMPDTFMT_H 25 #define SMPDTFMT_H 26 27 #include "unicode/utypes.h" 28 29 /** 30 * \file 31 * \brief C++ API: Format and parse dates in a language-independent manner. 32 */ 33 34 #if !UCONFIG_NO_FORMATTING 35 36 #include "unicode/datefmt.h" 37 38 U_NAMESPACE_BEGIN 39 40 class DateFormatSymbols; 41 class DateFormat; 42 class MessageFormat; 43 class FieldPositionHandler; 44 45 /** 46 * 47 * SimpleDateFormat is a concrete class for formatting and parsing dates in a 48 * language-independent manner. It allows for formatting (millis -> text), 49 * parsing (text -> millis), and normalization. Formats/Parses a date or time, 50 * which is the standard milliseconds since 24:00 GMT, Jan 1, 1970. 51 * <P> 52 * Clients are encouraged to create a date-time formatter using DateFormat::getInstance(), 53 * getDateInstance(), getDateInstance(), or getDateTimeInstance() rather than 54 * explicitly constructing an instance of SimpleDateFormat. This way, the client 55 * is guaranteed to get an appropriate formatting pattern for whatever locale the 56 * program is running in. However, if the client needs something more unusual than 57 * the default patterns in the locales, he can construct a SimpleDateFormat directly 58 * and give it an appropriate pattern (or use one of the factory methods on DateFormat 59 * and modify the pattern after the fact with toPattern() and applyPattern(). 60 * <P> 61 * Date/Time format syntax: 62 * <P> 63 * The date/time format is specified by means of a string time pattern. In this 64 * pattern, all ASCII letters are reserved as pattern letters, which are defined 65 * as the following: 66 * <pre> 67 * \code 68 * Symbol Meaning Presentation Example 69 * ------ ------- ------------ ------- 70 * G era designator (Text) AD 71 * y year (Number) 1996 72 * Y year (week of year) (Number) 1997 73 * u extended year (Number) 4601 74 * Q Quarter (Text & Number) Q2 & 02 75 * M month in year (Text & Number) July & 07 76 * d day in month (Number) 10 77 * h hour in am/pm (1~12) (Number) 12 78 * H hour in day (0~23) (Number) 0 79 * m minute in hour (Number) 30 80 * s second in minute (Number) 55 81 * S fractional second (Number) 978 82 * E day of week (Text) Tuesday 83 * e day of week (local 1~7) (Text & Number) Tues & 2 84 * D day in year (Number) 189 85 * F day of week in month (Number) 2 (2nd Wed in July) 86 * w week in year (Number) 27 87 * W week in month (Number) 2 88 * a am/pm marker (Text) PM 89 * k hour in day (1~24) (Number) 24 90 * K hour in am/pm (0~11) (Number) 0 91 * z time zone (Time) Pacific Standard Time 92 * Z time zone (RFC 822) (Number) -0800 93 * v time zone (generic) (Text) Pacific Time 94 * V time zone (abreviation) (Text) PT 95 * VVVV time zone (location) (Text) United States (Los Angeles) 96 * g Julian day (Number) 2451334 97 * A milliseconds in day (Number) 69540000 98 * q stand alone quarter (Text & Number) Q2 & 02 99 * L stand alone month (Text & Number) July & 07 100 * c stand alone day of week (Text & Number) Tuesday & 2 101 * ' escape for text (Delimiter) 'Date=' 102 * '' single quote (Literal) 'o''clock' 103 * \endcode 104 * </pre> 105 * The count of pattern letters determine the format. 106 * <P> 107 * (Text): 4 or more, use full form, <4, use short or abbreviated form if it 108 * exists. (e.g., "EEEE" produces "Monday", "EEE" produces "Mon") 109 * <P> 110 * (Number): the minimum number of digits. Shorter numbers are zero-padded to 111 * this amount (e.g. if "m" produces "6", "mm" produces "06"). Year is handled 112 * specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits. 113 * (e.g., if "yyyy" produces "1997", "yy" produces "97".) 114 * Unlike other fields, fractional seconds are padded on the right with zero. 115 * <P> 116 * (Text & Number): 3 or over, use text, otherwise use number. (e.g., "M" produces "1", 117 * "MM" produces "01", "MMM" produces "Jan", and "MMMM" produces "January".) 118 * <P> 119 * Any characters in the pattern that are not in the ranges of ['a'..'z'] and 120 * ['A'..'Z'] will be treated as quoted text. For instance, characters 121 * like ':', '.', ' ', '#' and '@' will appear in the resulting time text 122 * even they are not embraced within single quotes. 123 * <P> 124 * A pattern containing any invalid pattern letter will result in a failing 125 * UErrorCode result during formatting or parsing. 126 * <P> 127 * Examples using the US locale: 128 * <pre> 129 * \code 130 * Format Pattern Result 131 * -------------- ------- 132 * "yyyy.MM.dd G 'at' HH:mm:ss vvvv" ->> 1996.07.10 AD at 15:08:56 Pacific Time 133 * "EEE, MMM d, ''yy" ->> Wed, July 10, '96 134 * "h:mm a" ->> 12:08 PM 135 * "hh 'o''clock' a, zzzz" ->> 12 o'clock PM, Pacific Daylight Time 136 * "K:mm a, vvv" ->> 0:00 PM, PT 137 * "yyyyy.MMMMM.dd GGG hh:mm aaa" ->> 1996.July.10 AD 12:08 PM 138 * \endcode 139 * </pre> 140 * Code Sample: 141 * <pre> 142 * \code 143 * UErrorCode success = U_ZERO_ERROR; 144 * SimpleTimeZone* pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST"); 145 * pdt->setStartRule( Calendar::APRIL, 1, Calendar::SUNDAY, 2*60*60*1000); 146 * pdt->setEndRule( Calendar::OCTOBER, -1, Calendar::SUNDAY, 2*60*60*1000); 147 * 148 * // Format the current time. 149 * SimpleDateFormat* formatter 150 * = new SimpleDateFormat ("yyyy.MM.dd G 'at' hh:mm:ss a zzz", success ); 151 * GregorianCalendar cal(success); 152 * UDate currentTime_1 = cal.getTime(success); 153 * FieldPosition fp(0); 154 * UnicodeString dateString; 155 * formatter->format( currentTime_1, dateString, fp ); 156 * cout << "result: " << dateString << endl; 157 * 158 * // Parse the previous string back into a Date. 159 * ParsePosition pp(0); 160 * UDate currentTime_2 = formatter->parse(dateString, pp ); 161 * \endcode 162 * </pre> 163 * In the above example, the time value "currentTime_2" obtained from parsing 164 * will be equal to currentTime_1. However, they may not be equal if the am/pm 165 * marker 'a' is left out from the format pattern while the "hour in am/pm" 166 * pattern symbol is used. This information loss can happen when formatting the 167 * time in PM. 168 * 169 * <p> 170 * When parsing a date string using the abbreviated year pattern ("y" or "yy"), 171 * SimpleDateFormat must interpret the abbreviated year 172 * relative to some century. It does this by adjusting dates to be 173 * within 80 years before and 20 years after the time the SimpleDateFormat 174 * instance is created. For example, using a pattern of "MM/dd/yy" and a 175 * SimpleDateFormat instance created on Jan 1, 1997, the string 176 * "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" 177 * would be interpreted as May 4, 1964. 178 * During parsing, only strings consisting of exactly two digits, as defined by 179 * <code>Unicode::isDigit()</code>, will be parsed into the default century. 180 * Any other numeric string, such as a one digit string, a three or more digit 181 * string, or a two digit string that isn't all digits (for example, "-1"), is 182 * interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the 183 * same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC. 184 * 185 * <p> 186 * If the year pattern has more than two 'y' characters, the year is 187 * interpreted literally, regardless of the number of digits. So using the 188 * pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D. 189 * 190 * <p> 191 * When numeric fields abut one another directly, with no intervening delimiter 192 * characters, they constitute a run of abutting numeric fields. Such runs are 193 * parsed specially. For example, the format "HHmmss" parses the input text 194 * "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to 195 * parse "1234". In other words, the leftmost field of the run is flexible, 196 * while the others keep a fixed width. If the parse fails anywhere in the run, 197 * then the leftmost field is shortened by one character, and the entire run is 198 * parsed again. This is repeated until either the parse succeeds or the 199 * leftmost field is one character in length. If the parse still fails at that 200 * point, the parse of the run fails. 201 * 202 * <P> 203 * For time zones that have no names, SimpleDateFormat uses strings GMT+hours:minutes or 204 * GMT-hours:minutes. 205 * <P> 206 * The calendar defines what is the first day of the week, the first week of the 207 * year, whether hours are zero based or not (0 vs 12 or 24), and the timezone. 208 * There is one common number format to handle all the numbers; the digit count 209 * is handled programmatically according to the pattern. 210 * 211 * <p><em>User subclasses are not supported.</em> While clients may write 212 * subclasses, such code will not necessarily work and will not be 213 * guaranteed to work stably from release to release. 214 */ 215 class U_I18N_API SimpleDateFormat: public DateFormat { 216 public: 217 /** 218 * Construct a SimpleDateFormat using the default pattern for the default 219 * locale. 220 * <P> 221 * [Note:] Not all locales support SimpleDateFormat; for full generality, 222 * use the factory methods in the DateFormat class. 223 * @param status Output param set to success/failure code. 224 * @stable ICU 2.0 225 */ 226 SimpleDateFormat(UErrorCode& status); 227 228 /** 229 * Construct a SimpleDateFormat using the given pattern and the default locale. 230 * The locale is used to obtain the symbols used in formatting (e.g., the 231 * names of the months), but not to provide the pattern. 232 * <P> 233 * [Note:] Not all locales support SimpleDateFormat; for full generality, 234 * use the factory methods in the DateFormat class. 235 * @param pattern the pattern for the format. 236 * @param status Output param set to success/failure code. 237 * @stable ICU 2.0 238 */ 239 SimpleDateFormat(const UnicodeString& pattern, 240 UErrorCode& status); 241 242 /** 243 * Construct a SimpleDateFormat using the given pattern, numbering system override, and the default locale. 244 * The locale is used to obtain the symbols used in formatting (e.g., the 245 * names of the months), but not to provide the pattern. 246 * <P> 247 * A numbering system override is a string containing either the name of a known numbering system, 248 * or a set of field and numbering system pairs that specify which fields are to be formattied with 249 * the alternate numbering system. For example, to specify that all numeric fields in the specified 250 * date or time pattern are to be rendered using Thai digits, simply specify the numbering system override 251 * as "thai". To specify that just the year portion of the date be formatted using Hebrew numbering, 252 * use the override string "y=hebrew". Numbering system overrides can be combined using a semi-colon 253 * character in the override string, such as "d=decimal;M=arabic;y=hebrew", etc. 254 * 255 * <P> 256 * [Note:] Not all locales support SimpleDateFormat; for full generality, 257 * use the factory methods in the DateFormat class. 258 * @param pattern the pattern for the format. 259 * @param override the override string. 260 * @param status Output param set to success/failure code. 261 * @stable ICU 4.2 262 */ 263 SimpleDateFormat(const UnicodeString& pattern, 264 const UnicodeString& override, 265 UErrorCode& status); 266 267 /** 268 * Construct a SimpleDateFormat using the given pattern and locale. 269 * The locale is used to obtain the symbols used in formatting (e.g., the 270 * names of the months), but not to provide the pattern. 271 * <P> 272 * [Note:] Not all locales support SimpleDateFormat; for full generality, 273 * use the factory methods in the DateFormat class. 274 * @param pattern the pattern for the format. 275 * @param locale the given locale. 276 * @param status Output param set to success/failure code. 277 * @stable ICU 2.0 278 */ 279 SimpleDateFormat(const UnicodeString& pattern, 280 const Locale& locale, 281 UErrorCode& status); 282 283 /** 284 * Construct a SimpleDateFormat using the given pattern, numbering system override, and locale. 285 * The locale is used to obtain the symbols used in formatting (e.g., the 286 * names of the months), but not to provide the pattern. 287 * <P> 288 * A numbering system override is a string containing either the name of a known numbering system, 289 * or a set of field and numbering system pairs that specify which fields are to be formattied with 290 * the alternate numbering system. For example, to specify that all numeric fields in the specified 291 * date or time pattern are to be rendered using Thai digits, simply specify the numbering system override 292 * as "thai". To specify that just the year portion of the date be formatted using Hebrew numbering, 293 * use the override string "y=hebrew". Numbering system overrides can be combined using a semi-colon 294 * character in the override string, such as "d=decimal;M=arabic;y=hebrew", etc. 295 * <P> 296 * [Note:] Not all locales support SimpleDateFormat; for full generality, 297 * use the factory methods in the DateFormat class. 298 * @param pattern the pattern for the format. 299 * @param override the numbering system override. 300 * @param locale the given locale. 301 * @param status Output param set to success/failure code. 302 * @stable ICU 4.2 303 */ 304 SimpleDateFormat(const UnicodeString& pattern, 305 const UnicodeString& override, 306 const Locale& locale, 307 UErrorCode& status); 308 309 /** 310 * Construct a SimpleDateFormat using the given pattern and locale-specific 311 * symbol data. The formatter takes ownership of the DateFormatSymbols object; 312 * the caller is no longer responsible for deleting it. 313 * @param pattern the given pattern for the format. 314 * @param formatDataToAdopt the symbols to be adopted. 315 * @param status Output param set to success/faulure code. 316 * @stable ICU 2.0 317 */ 318 SimpleDateFormat(const UnicodeString& pattern, 319 DateFormatSymbols* formatDataToAdopt, 320 UErrorCode& status); 321 322 /** 323 * Construct a SimpleDateFormat using the given pattern and locale-specific 324 * symbol data. The DateFormatSymbols object is NOT adopted; the caller 325 * remains responsible for deleting it. 326 * @param pattern the given pattern for the format. 327 * @param formatData the formatting symbols to be use. 328 * @param status Output param set to success/faulure code. 329 * @stable ICU 2.0 330 */ 331 SimpleDateFormat(const UnicodeString& pattern, 332 const DateFormatSymbols& formatData, 333 UErrorCode& status); 334 335 /** 336 * Copy constructor. 337 * @stable ICU 2.0 338 */ 339 SimpleDateFormat(const SimpleDateFormat&); 340 341 /** 342 * Assignment operator. 343 * @stable ICU 2.0 344 */ 345 SimpleDateFormat& operator=(const SimpleDateFormat&); 346 347 /** 348 * Destructor. 349 * @stable ICU 2.0 350 */ 351 virtual ~SimpleDateFormat(); 352 353 /** 354 * Clone this Format object polymorphically. The caller owns the result and 355 * should delete it when done. 356 * @return A copy of the object. 357 * @stable ICU 2.0 358 */ 359 virtual Format* clone(void) const; 360 361 /** 362 * Return true if the given Format objects are semantically equal. Objects 363 * of different subclasses are considered unequal. 364 * @param other the object to be compared with. 365 * @return true if the given Format objects are semantically equal. 366 * @stable ICU 2.0 367 */ 368 virtual UBool operator==(const Format& other) const; 369 370 371 using DateFormat::format; 372 373 /** 374 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 375 * 1, 1970. Overrides DateFormat pure virtual method. 376 * <P> 377 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 378 * 1996.07.10 AD at 15:08:56 PDT 379 * 380 * @param cal Calendar set to the date and time to be formatted 381 * into a date/time string. 382 * @param appendTo Output parameter to receive result. 383 * Result is appended to existing contents. 384 * @param pos The formatting position. On input: an alignment field, 385 * if desired. On output: the offsets of the alignment field. 386 * @return Reference to 'appendTo' parameter. 387 * @stable ICU 2.1 388 */ 389 virtual UnicodeString& format( Calendar& cal, 390 UnicodeString& appendTo, 391 FieldPosition& pos) const; 392 393 /** 394 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 395 * 1, 1970. Overrides DateFormat pure virtual method. 396 * <P> 397 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 398 * 1996.07.10 AD at 15:08:56 PDT 399 * 400 * @param cal Calendar set to the date and time to be formatted 401 * into a date/time string. 402 * @param appendTo Output parameter to receive result. 403 * Result is appended to existing contents. 404 * @param posIter On return, can be used to iterate over positions 405 * of fields generated by this format call. Field values 406 * are defined in UDateFormatField. 407 * @param status Input/output param set to success/failure code. 408 * @return Reference to 'appendTo' parameter. 409 * @stable ICU 4.4 410 */ 411 virtual UnicodeString& format( Calendar& cal, 412 UnicodeString& appendTo, 413 FieldPositionIterator* posIter, 414 UErrorCode& status) const; 415 416 /** 417 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 418 * 1, 1970. Overrides DateFormat pure virtual method. 419 * <P> 420 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 421 * 1996.07.10 AD at 15:08:56 PDT 422 * 423 * @param obj A Formattable containing the date-time value to be formatted 424 * into a date-time string. If the type of the Formattable 425 * is a numeric type, it is treated as if it were an 426 * instance of Date. 427 * @param appendTo Output parameter to receive result. 428 * Result is appended to existing contents. 429 * @param pos The formatting position. On input: an alignment field, 430 * if desired. On output: the offsets of the alignment field. 431 * @param status Input/output param set to success/failure code. 432 * @return Reference to 'appendTo' parameter. 433 * @stable ICU 2.0 434 */ 435 virtual UnicodeString& format( const Formattable& obj, 436 UnicodeString& appendTo, 437 FieldPosition& pos, 438 UErrorCode& status) const; 439 440 /** 441 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 442 * 1, 1970. Overrides DateFormat pure virtual method. 443 * <P> 444 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 445 * 1996.07.10 AD at 15:08:56 PDT 446 * 447 * @param obj A Formattable containing the date-time value to be formatted 448 * into a date-time string. If the type of the Formattable 449 * is a numeric type, it is treated as if it were an 450 * instance of Date. 451 * @param appendTo Output parameter to receive result. 452 * Result is appended to existing contents. 453 * @param posIter On return, can be used to iterate over positions 454 * of fields generated by this format call. Field values 455 * are defined in UDateFormatField. 456 * @param status Input/output param set to success/failure code. 457 * @return Reference to 'appendTo' parameter. 458 * @stable ICU 4.4 459 */ 460 virtual UnicodeString& format( const Formattable& obj, 461 UnicodeString& appendTo, 462 FieldPositionIterator* posIter, 463 UErrorCode& status) const; 464 465 /** 466 * Redeclared DateFormat method. 467 * @param date the Date value to be formatted. 468 * @param appendTo Output parameter to receive result. 469 * Result is appended to existing contents. 470 * @param fieldPosition The formatting position. On input: an alignment field, 471 * if desired. On output: the offsets of the alignment field. 472 * @return Reference to 'appendTo' parameter. 473 * @stable ICU 2.1 474 */ 475 UnicodeString& format(UDate date, 476 UnicodeString& appendTo, 477 FieldPosition& fieldPosition) const; 478 479 /** 480 * Redeclared DateFormat method. 481 * @param date the Date value to be formatted. 482 * @param appendTo Output parameter to receive result. 483 * Result is appended to existing contents. 484 * @param posIter On return, can be used to iterate over positions 485 * of fields generated by this format call. Field values 486 * are defined in UDateFormatField. 487 * @param status Input/output param set to success/failure code. 488 * @return Reference to 'appendTo' parameter. 489 * @stable ICU 4.4 490 */ 491 UnicodeString& format(UDate date, 492 UnicodeString& appendTo, 493 FieldPositionIterator* posIter, 494 UErrorCode& status) const; 495 496 /** 497 * Redeclared DateFormat method. 498 * @param obj Object to be formatted. 499 * @param appendTo Output parameter to receive result. 500 * Result is appended to existing contents. 501 * @param status Input/output success/failure code. 502 * @return Reference to 'appendTo' parameter. 503 * @stable ICU 2.0 504 */ 505 UnicodeString& format(const Formattable& obj, 506 UnicodeString& appendTo, 507 UErrorCode& status) const; 508 509 /** 510 * Redeclared DateFormat method. 511 * @param date Date value to be formatted. 512 * @param appendTo Output parameter to receive result. 513 * Result is appended to existing contents. 514 * @return Reference to 'appendTo' parameter. 515 * @stable ICU 2.0 516 */ 517 UnicodeString& format(UDate date, UnicodeString& appendTo) const; 518 519 /** 520 * Parse a date/time string beginning at the given parse position. For 521 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 522 * that is equivalent to Date(837039928046). 523 * <P> 524 * By default, parsing is lenient: If the input is not in the form used by 525 * this object's format method but can still be parsed as a date, then the 526 * parse succeeds. Clients may insist on strict adherence to the format by 527 * calling setLenient(false). 528 * 529 * @param text The date/time string to be parsed 530 * @param cal a Calendar set to the date and time to be formatted 531 * into a date/time string. 532 * @param pos On input, the position at which to start parsing; on 533 * output, the position at which parsing terminated, or the 534 * start position if the parse failed. 535 * @return A valid UDate if the input could be parsed. 536 * @stable ICU 2.1 537 */ 538 virtual void parse( const UnicodeString& text, 539 Calendar& cal, 540 ParsePosition& pos) const; 541 542 /** 543 * Parse a date/time string starting at the given parse position. For 544 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 545 * that is equivalent to Date(837039928046). 546 * <P> 547 * By default, parsing is lenient: If the input is not in the form used by 548 * this object's format method but can still be parsed as a date, then the 549 * parse succeeds. Clients may insist on strict adherence to the format by 550 * calling setLenient(false). 551 * 552 * @see DateFormat::setLenient(boolean) 553 * 554 * @param text The date/time string to be parsed 555 * @param pos On input, the position at which to start parsing; on 556 * output, the position at which parsing terminated, or the 557 * start position if the parse failed. 558 * @return A valid UDate if the input could be parsed. 559 * @stable ICU 2.0 560 */ 561 UDate parse( const UnicodeString& text, 562 ParsePosition& pos) const; 563 564 565 /** 566 * Parse a date/time string. For example, a time text "07/10/96 4:5 PM, PDT" 567 * will be parsed into a UDate that is equivalent to Date(837039928046). 568 * Parsing begins at the beginning of the string and proceeds as far as 569 * possible. Assuming no parse errors were encountered, this function 570 * doesn't return any information about how much of the string was consumed 571 * by the parsing. If you need that information, use the version of 572 * parse() that takes a ParsePosition. 573 * 574 * @param text The date/time string to be parsed 575 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 576 * an error value if there was a parse error. 577 * @return A valid UDate if the input could be parsed. 578 * @stable ICU 2.0 579 */ 580 virtual UDate parse( const UnicodeString& text, 581 UErrorCode& status) const; 582 583 /** 584 * Set the start UDate used to interpret two-digit year strings. 585 * When dates are parsed having 2-digit year strings, they are placed within 586 * a assumed range of 100 years starting on the two digit start date. For 587 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or 588 * some other year. SimpleDateFormat chooses a year so that the resultant 589 * date is on or after the two digit start date and within 100 years of the 590 * two digit start date. 591 * <P> 592 * By default, the two digit start date is set to 80 years before the current 593 * time at which a SimpleDateFormat object is created. 594 * @param d start UDate used to interpret two-digit year strings. 595 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 596 * an error value if there was a parse error. 597 * @stable ICU 2.0 598 */ 599 virtual void set2DigitYearStart(UDate d, UErrorCode& status); 600 601 /** 602 * Get the start UDate used to interpret two-digit year strings. 603 * When dates are parsed having 2-digit year strings, they are placed within 604 * a assumed range of 100 years starting on the two digit start date. For 605 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or 606 * some other year. SimpleDateFormat chooses a year so that the resultant 607 * date is on or after the two digit start date and within 100 years of the 608 * two digit start date. 609 * <P> 610 * By default, the two digit start date is set to 80 years before the current 611 * time at which a SimpleDateFormat object is created. 612 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 613 * an error value if there was a parse error. 614 * @stable ICU 2.0 615 */ 616 UDate get2DigitYearStart(UErrorCode& status) const; 617 618 /** 619 * Return a pattern string describing this date format. 620 * @param result Output param to receive the pattern. 621 * @return A reference to 'result'. 622 * @stable ICU 2.0 623 */ 624 virtual UnicodeString& toPattern(UnicodeString& result) const; 625 626 /** 627 * Return a localized pattern string describing this date format. 628 * In most cases, this will return the same thing as toPattern(), 629 * but a locale can specify characters to use in pattern descriptions 630 * in place of the ones described in this class's class documentation. 631 * (Presumably, letters that would be more mnemonic in that locale's 632 * language.) This function would produce a pattern using those 633 * letters. 634 * 635 * @param result Receives the localized pattern. 636 * @param status Output param set to success/failure code on 637 * exit. If the pattern is invalid, this will be 638 * set to a failure result. 639 * @return A reference to 'result'. 640 * @stable ICU 2.0 641 */ 642 virtual UnicodeString& toLocalizedPattern(UnicodeString& result, 643 UErrorCode& status) const; 644 645 /** 646 * Apply the given unlocalized pattern string to this date format. 647 * (i.e., after this call, this formatter will format dates according to 648 * the new pattern) 649 * 650 * @param pattern The pattern to be applied. 651 * @stable ICU 2.0 652 */ 653 virtual void applyPattern(const UnicodeString& pattern); 654 655 /** 656 * Apply the given localized pattern string to this date format. 657 * (see toLocalizedPattern() for more information on localized patterns.) 658 * 659 * @param pattern The localized pattern to be applied. 660 * @param status Output param set to success/failure code on 661 * exit. If the pattern is invalid, this will be 662 * set to a failure result. 663 * @stable ICU 2.0 664 */ 665 virtual void applyLocalizedPattern(const UnicodeString& pattern, 666 UErrorCode& status); 667 668 /** 669 * Gets the date/time formatting symbols (this is an object carrying 670 * the various strings and other symbols used in formatting: e.g., month 671 * names and abbreviations, time zone names, AM/PM strings, etc.) 672 * @return a copy of the date-time formatting data associated 673 * with this date-time formatter. 674 * @stable ICU 2.0 675 */ 676 virtual const DateFormatSymbols* getDateFormatSymbols(void) const; 677 678 /** 679 * Set the date/time formatting symbols. The caller no longer owns the 680 * DateFormatSymbols object and should not delete it after making this call. 681 * @param newFormatSymbols the given date-time formatting symbols to copy. 682 * @stable ICU 2.0 683 */ 684 virtual void adoptDateFormatSymbols(DateFormatSymbols* newFormatSymbols); 685 686 /** 687 * Set the date/time formatting data. 688 * @param newFormatSymbols the given date-time formatting symbols to copy. 689 * @stable ICU 2.0 690 */ 691 virtual void setDateFormatSymbols(const DateFormatSymbols& newFormatSymbols); 692 693 /** 694 * Return the class ID for this class. This is useful only for comparing to 695 * a return value from getDynamicClassID(). For example: 696 * <pre> 697 * . Base* polymorphic_pointer = createPolymorphicObject(); 698 * . if (polymorphic_pointer->getDynamicClassID() == 699 * . erived::getStaticClassID()) ... 700 * </pre> 701 * @return The class ID for all objects of this class. 702 * @stable ICU 2.0 703 */ 704 static UClassID U_EXPORT2 getStaticClassID(void); 705 706 /** 707 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 708 * method is to implement a simple version of RTTI, since not all C++ 709 * compilers support genuine RTTI. Polymorphic operator==() and clone() 710 * methods call this method. 711 * 712 * @return The class ID for this object. All objects of a 713 * given class have the same class ID. Objects of 714 * other classes have different class IDs. 715 * @stable ICU 2.0 716 */ 717 virtual UClassID getDynamicClassID(void) const; 718 719 /** 720 * Set the calendar to be used by this date format. Initially, the default 721 * calendar for the specified or default locale is used. The caller should 722 * not delete the Calendar object after it is adopted by this call. 723 * Adopting a new calendar will change to the default symbols. 724 * 725 * @param calendarToAdopt Calendar object to be adopted. 726 * @stable ICU 2.0 727 */ 728 virtual void adoptCalendar(Calendar* calendarToAdopt); 729 730 /** 731 * This is for ICU internal use only. Please do not use. 732 * Check whether the 'field' is smaller than all the fields covered in 733 * pattern, return TRUE if it is. The sequence of calendar field, 734 * from large to small is: ERA, YEAR, MONTH, DATE, AM_PM, HOUR, MINUTE,... 735 * @param field the calendar field need to check against 736 * @return TRUE if the 'field' is smaller than all the fields 737 * covered in pattern. FALSE otherwise. 738 * @internal ICU 4.0 739 */ 740 UBool isFieldUnitIgnored(UCalendarDateFields field) const; 741 742 743 /** 744 * This is for ICU internal use only. Please do not use. 745 * Check whether the 'field' is smaller than all the fields covered in 746 * pattern, return TRUE if it is. The sequence of calendar field, 747 * from large to small is: ERA, YEAR, MONTH, DATE, AM_PM, HOUR, MINUTE,... 748 * @param pattern the pattern to check against 749 * @param field the calendar field need to check against 750 * @return TRUE if the 'field' is smaller than all the fields 751 * covered in pattern. FALSE otherwise. 752 * @internal ICU 4.0 753 */ 754 static UBool isFieldUnitIgnored(const UnicodeString& pattern, 755 UCalendarDateFields field); 756 757 758 759 /** 760 * This is for ICU internal use only. Please do not use. 761 * Get the locale of this simple date formatter. 762 * It is used in DateIntervalFormat. 763 * 764 * @return locale in this simple date formatter 765 * @internal ICU 4.0 766 */ 767 const Locale& getSmpFmtLocale(void) const; 768 769 770 private: 771 friend class DateFormat; 772 773 void initializeDefaultCentury(void); 774 775 SimpleDateFormat(); // default constructor not implemented 776 777 /** 778 * Used by the DateFormat factory methods to construct a SimpleDateFormat. 779 * @param timeStyle the time style. 780 * @param dateStyle the date style. 781 * @param locale the given locale. 782 * @param status Output param set to success/failure code on 783 * exit. 784 */ 785 SimpleDateFormat(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status); 786 787 /** 788 * Construct a SimpleDateFormat for the given locale. If no resource data 789 * is available, create an object of last resort, using hard-coded strings. 790 * This is an internal method, called by DateFormat. It should never fail. 791 * @param locale the given locale. 792 * @param status Output param set to success/failure code on 793 * exit. 794 */ 795 SimpleDateFormat(const Locale& locale, UErrorCode& status); // Use default pattern 796 797 /** 798 * Hook called by format(... FieldPosition& ...) and format(...FieldPositionIterator&...) 799 */ 800 UnicodeString& _format(Calendar& cal, UnicodeString& appendTo, FieldPositionHandler& handler, 801 UErrorCode& status) const; 802 803 /** 804 * Called by format() to format a single field. 805 * 806 * @param appendTo Output parameter to receive result. 807 * Result is appended to existing contents. 808 * @param ch The format character we encountered in the pattern. 809 * @param count Number of characters in the current pattern symbol (e.g., 810 * "yyyy" in the pattern would result in a call to this function 811 * with ch equal to 'y' and count equal to 4) 812 * @param handler Records information about field positions. 813 * @param status Receives a status code, which will be U_ZERO_ERROR if the operation 814 * succeeds. 815 */ 816 void subFormat(UnicodeString &appendTo, 817 UChar ch, 818 int32_t count, 819 FieldPositionHandler& handler, 820 Calendar& cal, 821 UErrorCode& status) const; // in case of illegal argument 822 823 /** 824 * Used by subFormat() to format a numeric value. 825 * Appends to toAppendTo a string representation of "value" 826 * having a number of digits between "minDigits" and 827 * "maxDigits". Uses the DateFormat's NumberFormat. 828 * 829 * @param appendTo Output parameter to receive result. 830 * Formatted number is appended to existing contents. 831 * @param value Value to format. 832 * @param minDigits Minimum number of digits the result should have 833 * @param maxDigits Maximum number of digits the result should have 834 */ 835 void zeroPaddingNumber(NumberFormat *currentNumberFormat, 836 UnicodeString &appendTo, 837 int32_t value, 838 int32_t minDigits, 839 int32_t maxDigits) const; 840 841 /** 842 * Return true if the given format character, occuring count 843 * times, represents a numeric field. 844 */ 845 static UBool isNumeric(UChar formatChar, int32_t count); 846 847 /** 848 * initializes fCalendar from parameters. Returns fCalendar as a convenience. 849 * @param adoptZone Zone to be adopted, or NULL for TimeZone::createDefault(). 850 * @param locale Locale of the calendar 851 * @param status Error code 852 * @return the newly constructed fCalendar 853 */ 854 Calendar *initializeCalendar(TimeZone* adoptZone, const Locale& locale, UErrorCode& status); 855 856 /** 857 * initializes fSymbols from parameters. 858 * @param locale Locale of the symbols 859 * @param calendar Alias to Calendar that will be used. 860 * @param status Error code 861 */ 862 void initializeSymbols(const Locale& locale, Calendar* calendar, UErrorCode& status); 863 864 /** 865 * Called by several of the constructors to load pattern data and formatting symbols 866 * out of a resource bundle and initialize the locale based on it. 867 * @param timeStyle The time style, as passed to DateFormat::createDateInstance(). 868 * @param dateStyle The date style, as passed to DateFormat::createTimeInstance(). 869 * @param locale The locale to load the patterns from. 870 * @param status Filled in with an error code if loading the data from the 871 * resources fails. 872 */ 873 void construct(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status); 874 875 /** 876 * Called by construct() and the various constructors to set up the SimpleDateFormat's 877 * Calendar and NumberFormat objects. 878 * @param locale The locale for which we want a Calendar and a NumberFormat. 879 * @param statuc Filled in with an error code if creating either subobject fails. 880 */ 881 void initialize(const Locale& locale, UErrorCode& status); 882 883 /** 884 * Private code-size reduction function used by subParse. 885 * @param text the time text being parsed. 886 * @param start where to start parsing. 887 * @param field the date field being parsed. 888 * @param stringArray the string array to parsed. 889 * @param stringArrayCount the size of the array. 890 * @param cal a Calendar set to the date and time to be formatted 891 * into a date/time string. 892 * @return the new start position if matching succeeded; a negative number 893 * indicating matching failure, otherwise. 894 */ 895 int32_t matchString(const UnicodeString& text, int32_t start, UCalendarDateFields field, 896 const UnicodeString* stringArray, int32_t stringArrayCount, Calendar& cal) const; 897 898 /** 899 * Private code-size reduction function used by subParse. 900 * @param text the time text being parsed. 901 * @param start where to start parsing. 902 * @param field the date field being parsed. 903 * @param stringArray the string array to parsed. 904 * @param stringArrayCount the size of the array. 905 * @param cal a Calendar set to the date and time to be formatted 906 * into a date/time string. 907 * @return the new start position if matching succeeded; a negative number 908 * indicating matching failure, otherwise. 909 */ 910 int32_t matchQuarterString(const UnicodeString& text, int32_t start, UCalendarDateFields field, 911 const UnicodeString* stringArray, int32_t stringArrayCount, Calendar& cal) const; 912 913 /** 914 * Private member function that converts the parsed date strings into 915 * timeFields. Returns -start (for ParsePosition) if failed. 916 * @param text the time text to be parsed. 917 * @param start where to start parsing. 918 * @param ch the pattern character for the date field text to be parsed. 919 * @param count the count of a pattern character. 920 * @param obeyCount if true then the count is strictly obeyed. 921 * @param ambiguousYear If true then the two-digit year == the default start year. 922 * @param saveHebrewMonth Used to hang onto month until year is known. 923 * @param cal a Calendar set to the date and time to be formatted 924 * into a date/time string. 925 * @return the new start position if matching succeeded; a negative number 926 * indicating matching failure, otherwise. 927 */ 928 int32_t subParse(const UnicodeString& text, int32_t& start, UChar ch, int32_t count, 929 UBool obeyCount, UBool allowNegative, UBool ambiguousYear[], int32_t& saveHebrewMonth, Calendar& cal, 930 int32_t patLoc) const; 931 932 void parseInt(const UnicodeString& text, 933 Formattable& number, 934 ParsePosition& pos, 935 UBool allowNegative, 936 NumberFormat *fmt) const; 937 938 void parseInt(const UnicodeString& text, 939 Formattable& number, 940 int32_t maxDigits, 941 ParsePosition& pos, 942 UBool allowNegative, 943 NumberFormat *fmt) const; 944 945 int32_t checkIntSuffix(const UnicodeString& text, int32_t start, 946 int32_t patLoc, UBool isNegative) const; 947 948 /** 949 * Translate a pattern, mapping each character in the from string to the 950 * corresponding character in the to string. Return an error if the original 951 * pattern contains an unmapped character, or if a quote is unmatched. 952 * Quoted (single quotes only) material is not translated. 953 * @param originalPattern the original pattern. 954 * @param translatedPattern Output param to receive the translited pattern. 955 * @param from the characters to be translited from. 956 * @param to the characters to be translited to. 957 * @param status Receives a status code, which will be U_ZERO_ERROR 958 * if the operation succeeds. 959 */ 960 static void translatePattern(const UnicodeString& originalPattern, 961 UnicodeString& translatedPattern, 962 const UnicodeString& from, 963 const UnicodeString& to, 964 UErrorCode& status); 965 966 /** 967 * Sets the starting date of the 100-year window that dates with 2-digit years 968 * are considered to fall within. 969 * @param startDate the start date 970 * @param status Receives a status code, which will be U_ZERO_ERROR 971 * if the operation succeeds. 972 */ 973 void parseAmbiguousDatesAsAfter(UDate startDate, UErrorCode& status); 974 975 /** 976 * Return the length matched by the given affix, or -1 if none. 977 * Runs of white space in the affix, match runs of white space in 978 * the input. 979 * @param affix pattern string, taken as a literal 980 * @param input input text 981 * @param pos offset into input at which to begin matching 982 * @return length of input that matches, or -1 if match failure 983 */ 984 int32_t compareSimpleAffix(const UnicodeString& affix, 985 const UnicodeString& input, 986 int32_t pos) const; 987 988 /** 989 * Skip over a run of zero or more isRuleWhiteSpace() characters at 990 * pos in text. 991 */ 992 int32_t skipRuleWhiteSpace(const UnicodeString& text, int32_t pos) const; 993 994 /** 995 * Skip over a run of zero or more isUWhiteSpace() characters at pos 996 * in text. 997 */ 998 int32_t skipUWhiteSpace(const UnicodeString& text, int32_t pos) const; 999 1000 /** 1001 * Private methods for formatting/parsing GMT string 1002 */ 1003 void appendGMT(NumberFormat *currentNumberFormat,UnicodeString &appendTo, Calendar& cal, UErrorCode& status) const; 1004 void formatGMTDefault(NumberFormat *currentNumberFormat,UnicodeString &appendTo, int32_t offset) const; 1005 int32_t parseGMT(const UnicodeString &text, ParsePosition &pos) const; 1006 int32_t parseGMTDefault(const UnicodeString &text, ParsePosition &pos) const; 1007 UBool isDefaultGMTFormat() const; 1008 1009 void formatRFC822TZ(UnicodeString &appendTo, int32_t offset) const; 1010 1011 /** 1012 * Initialize MessageFormat instances used for GMT formatting/parsing 1013 */ 1014 void initGMTFormatters(UErrorCode &status); 1015 1016 /** 1017 * Initialize NumberFormat instances used for numbering system overrides. 1018 */ 1019 void initNumberFormatters(const Locale &locale,UErrorCode &status); 1020 1021 /** 1022 * Get the numbering system to be used for a particular field. 1023 */ 1024 NumberFormat * getNumberFormatByIndex(UDateFormatField index) const; 1025 1026 /** 1027 * Parse the given override string and set up structures for number formats 1028 */ 1029 void processOverrideString(const Locale &locale, const UnicodeString &str, int8_t type, UErrorCode &status); 1030 1031 /** 1032 * Used to map pattern characters to Calendar field identifiers. 1033 */ 1034 static const UCalendarDateFields fgPatternIndexToCalendarField[]; 1035 1036 /** 1037 * Map index into pattern character string to DateFormat field number 1038 */ 1039 static const UDateFormatField fgPatternIndexToDateFormatField[]; 1040 1041 /** 1042 * Used to map Calendar field to field level. 1043 * The larger the level, the smaller the field unit. 1044 * For example, UCAL_ERA level is 0, UCAL_YEAR level is 10, 1045 * UCAL_MONTH level is 20. 1046 */ 1047 static const int32_t fgCalendarFieldToLevel[]; 1048 static const int32_t fgPatternCharToLevel[]; 1049 1050 /** 1051 * The formatting pattern for this formatter. 1052 */ 1053 UnicodeString fPattern; 1054 1055 /** 1056 * The numbering system override for dates. 1057 */ 1058 UnicodeString fDateOverride; 1059 1060 /** 1061 * The numbering system override for times. 1062 */ 1063 UnicodeString fTimeOverride; 1064 1065 1066 /** 1067 * The original locale used (for reloading symbols) 1068 */ 1069 Locale fLocale; 1070 1071 /** 1072 * A pointer to an object containing the strings to use in formatting (e.g., 1073 * month and day names, AM and PM strings, time zone names, etc.) 1074 */ 1075 DateFormatSymbols* fSymbols; // Owned 1076 1077 /** 1078 * If dates have ambiguous years, we map them into the century starting 1079 * at defaultCenturyStart, which may be any date. If defaultCenturyStart is 1080 * set to SYSTEM_DEFAULT_CENTURY, which it is by default, then the system 1081 * values are used. The instance values defaultCenturyStart and 1082 * defaultCenturyStartYear are only used if explicitly set by the user 1083 * through the API method parseAmbiguousDatesAsAfter(). 1084 */ 1085 UDate fDefaultCenturyStart; 1086 1087 /** 1088 * See documentation for defaultCenturyStart. 1089 */ 1090 /*transient*/ int32_t fDefaultCenturyStartYear; 1091 1092 enum ParsedTZType { 1093 TZTYPE_UNK, 1094 TZTYPE_STD, 1095 TZTYPE_DST 1096 }; 1097 1098 ParsedTZType tztype; // here to avoid api change 1099 1100 typedef struct NSOverride { 1101 NumberFormat *nf; 1102 int32_t hash; 1103 NSOverride *next; 1104 } NSOverride; 1105 1106 /* 1107 * MessageFormat instances used for localized GMT format 1108 */ 1109 enum { 1110 kGMTNegativeHMS = 0, 1111 kGMTNegativeHM, 1112 kGMTPositiveHMS, 1113 kGMTPositiveHM, 1114 1115 kNumGMTFormatters 1116 }; 1117 enum { 1118 kGMTNegativeHMSMinLenIdx = 0, 1119 kGMTPositiveHMSMinLenIdx, 1120 1121 kNumGMTFormatMinLengths 1122 }; 1123 1124 MessageFormat **fGMTFormatters; 1125 // If a GMT hour format has a second field, we need to make sure 1126 // the length of input localized GMT string must match the expected 1127 // length. Otherwise, sub DateForamt handling offset format may 1128 // unexpectedly success parsing input GMT string without second field. 1129 // See #6880 about this issue. 1130 // TODO: SimpleDateFormat should provide an option to invalidate 1131 // 1132 int32_t fGMTFormatHmsMinLen[kNumGMTFormatMinLengths]; 1133 1134 NumberFormat **fNumberFormatters; 1135 1136 NSOverride *fOverrideList; 1137 1138 UBool fHaveDefaultCentury; 1139 }; 1140 1141 inline UDate 1142 SimpleDateFormat::get2DigitYearStart(UErrorCode& /*status*/) const 1143 { 1144 return fDefaultCenturyStart; 1145 } 1146 1147 inline UnicodeString& 1148 SimpleDateFormat::format(const Formattable& obj, 1149 UnicodeString& appendTo, 1150 UErrorCode& status) const { 1151 // Don't use Format:: - use immediate base class only, 1152 // in case immediate base modifies behavior later. 1153 return DateFormat::format(obj, appendTo, status); 1154 } 1155 1156 inline UnicodeString& 1157 SimpleDateFormat::format(const Formattable& obj, 1158 UnicodeString& appendTo, 1159 FieldPosition& pos, 1160 UErrorCode& status) const 1161 { 1162 // Don't use Format:: - use immediate base class only, 1163 // in case immediate base modifies behavior later. 1164 return DateFormat::format(obj, appendTo, pos, status); 1165 } 1166 1167 inline UnicodeString& 1168 SimpleDateFormat::format(const Formattable& obj, 1169 UnicodeString& appendTo, 1170 FieldPositionIterator* posIter, 1171 UErrorCode& status) const 1172 { 1173 // Don't use Format:: - use immediate base class only, 1174 // in case immediate base modifies behavior later. 1175 return DateFormat::format(obj, appendTo, posIter, status); 1176 } 1177 1178 inline UnicodeString& 1179 SimpleDateFormat::format(UDate date, 1180 UnicodeString& appendTo, 1181 FieldPosition& fieldPosition) const { 1182 // Don't use Format:: - use immediate base class only, 1183 // in case immediate base modifies behavior later. 1184 return DateFormat::format(date, appendTo, fieldPosition); 1185 } 1186 1187 inline UnicodeString& 1188 SimpleDateFormat::format(UDate date, 1189 UnicodeString& appendTo, 1190 FieldPositionIterator* posIter, 1191 UErrorCode& status) const { 1192 // Don't use Format:: - use immediate base class only, 1193 // in case immediate base modifies behavior later. 1194 return DateFormat::format(date, appendTo, posIter, status); 1195 } 1196 1197 inline UnicodeString& 1198 SimpleDateFormat::format(UDate date, UnicodeString& appendTo) const { 1199 return DateFormat::format(date, appendTo); 1200 } 1201 1202 U_NAMESPACE_END 1203 1204 #endif /* #if !UCONFIG_NO_FORMATTING */ 1205 1206 #endif // _SMPDTFMT 1207 //eof 1208
