1/* 2* Copyright (C) 1997-2013, 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#include "unicode/udisplaycontext.h" 38 39U_NAMESPACE_BEGIN 40 41class DateFormatSymbols; 42class DateFormat; 43class MessageFormat; 44class FieldPositionHandler; 45class TimeZoneFormat; 46 47/** 48 * 49 * SimpleDateFormat is a concrete class for formatting and parsing dates in a 50 * language-independent manner. It allows for formatting (millis -> text), 51 * parsing (text -> millis), and normalization. Formats/Parses a date or time, 52 * which is the standard milliseconds since 24:00 GMT, Jan 1, 1970. 53 * <P> 54 * Clients are encouraged to create a date-time formatter using DateFormat::getInstance(), 55 * getDateInstance(), getDateInstance(), or getDateTimeInstance() rather than 56 * explicitly constructing an instance of SimpleDateFormat. This way, the client 57 * is guaranteed to get an appropriate formatting pattern for whatever locale the 58 * program is running in. However, if the client needs something more unusual than 59 * the default patterns in the locales, he can construct a SimpleDateFormat directly 60 * and give it an appropriate pattern (or use one of the factory methods on DateFormat 61 * and modify the pattern after the fact with toPattern() and applyPattern(). 62 * 63 * <p><strong>Date and Time Patterns:</strong></p> 64 * 65 * <p>Date and time formats are specified by <em>date and time pattern</em> strings. 66 * Within date and time pattern strings, all unquoted ASCII letters [A-Za-z] are reserved 67 * as pattern letters representing calendar fields. <code>SimpleDateFormat</code> supports 68 * the date and time formatting algorithm and pattern letters defined by <a href="http://www.unicode.org/reports/tr35/">UTS#35 69 * Unicode Locale Data Markup Language (LDML)</a>. The following pattern letters are 70 * currently available:</p> 71 * 72 * <table border="1"> 73 * <tr> 74 * <th>Field</th> 75 * <th style="text-align: center">Sym.</th> 76 * <th style="text-align: center">No.</th> 77 * <th>Example</th> 78 * <th>Description</th> 79 * </tr> 80 * <tr> 81 * <th rowspan="3">era</th> 82 * <td style="text-align: center" rowspan="3">G</td> 83 * <td style="text-align: center">1..3</td> 84 * <td>AD</td> 85 * <td rowspan="3">Era - Replaced with the Era string for the current date. One to three letters for the 86 * abbreviated form, four letters for the long form, five for the narrow form.</td> 87 * </tr> 88 * <tr> 89 * <td style="text-align: center">4</td> 90 * <td>Anno Domini</td> 91 * </tr> 92 * <tr> 93 * <td style="text-align: center">5</td> 94 * <td>A</td> 95 * </tr> 96 * <tr> 97 * <th rowspan="6">year</th> 98 * <td style="text-align: center">y</td> 99 * <td style="text-align: center">1..n</td> 100 * <td>1996</td> 101 * <td>Year. Normally the length specifies the padding, but for two letters it also specifies the maximum 102 * length. Example:<div align="center"> 103 * <center> 104 * <table border="1" cellpadding="2" cellspacing="0"> 105 * <tr> 106 * <th>Year</th> 107 * <th style="text-align: right">y</th> 108 * <th style="text-align: right">yy</th> 109 * <th style="text-align: right">yyy</th> 110 * <th style="text-align: right">yyyy</th> 111 * <th style="text-align: right">yyyyy</th> 112 * </tr> 113 * <tr> 114 * <td>AD 1</td> 115 * <td style="text-align: right">1</td> 116 * <td style="text-align: right">01</td> 117 * <td style="text-align: right">001</td> 118 * <td style="text-align: right">0001</td> 119 * <td style="text-align: right">00001</td> 120 * </tr> 121 * <tr> 122 * <td>AD 12</td> 123 * <td style="text-align: right">12</td> 124 * <td style="text-align: right">12</td> 125 * <td style="text-align: right">012</td> 126 * <td style="text-align: right">0012</td> 127 * <td style="text-align: right">00012</td> 128 * </tr> 129 * <tr> 130 * <td>AD 123</td> 131 * <td style="text-align: right">123</td> 132 * <td style="text-align: right">23</td> 133 * <td style="text-align: right">123</td> 134 * <td style="text-align: right">0123</td> 135 * <td style="text-align: right">00123</td> 136 * </tr> 137 * <tr> 138 * <td>AD 1234</td> 139 * <td style="text-align: right">1234</td> 140 * <td style="text-align: right">34</td> 141 * <td style="text-align: right">1234</td> 142 * <td style="text-align: right">1234</td> 143 * <td style="text-align: right">01234</td> 144 * </tr> 145 * <tr> 146 * <td>AD 12345</td> 147 * <td style="text-align: right">12345</td> 148 * <td style="text-align: right">45</td> 149 * <td style="text-align: right">12345</td> 150 * <td style="text-align: right">12345</td> 151 * <td style="text-align: right">12345</td> 152 * </tr> 153 * </table> 154 * </center></div> 155 * </td> 156 * </tr> 157 * <tr> 158 * <td style="text-align: center">Y</td> 159 * <td style="text-align: center">1..n</td> 160 * <td>1997</td> 161 * <td>Year (in "Week of Year" based calendars). Normally the length specifies the padding, 162 * but for two letters it also specifies the maximum length. This year designation is used in ISO 163 * year-week calendar as defined by ISO 8601, but can be used in non-Gregorian based calendar systems 164 * where week date processing is desired. May not always be the same value as calendar year.</td> 165 * </tr> 166 * <tr> 167 * <td style="text-align: center">u</td> 168 * <td style="text-align: center">1..n</td> 169 * <td>4601</td> 170 * <td>Extended year. This is a single number designating the year of this calendar system, encompassing 171 * all supra-year fields. For example, for the Julian calendar system, year numbers are positive, with an 172 * era of BCE or CE. An extended year value for the Julian calendar system assigns positive values to CE 173 * years and negative values to BCE years, with 1 BCE being year 0.</td> 174 * </tr> 175 * <tr> 176 * <td style="text-align: center" rowspan="3">U</td> 177 * <td style="text-align: center">1..3</td> 178 * <td>甲子</td> 179 * <td rowspan="3">Cyclic year name. Calendars such as the Chinese lunar calendar (and related calendars) 180 * and the Hindu calendars use 60-year cycles of year names. Use one through three letters for the abbreviated 181 * name, four for the full name, or five for the narrow name (currently the data only provides abbreviated names, 182 * which will be used for all requested name widths). If the calendar does not provide cyclic year name data, 183 * or if the year value to be formatted is out of the range of years for which cyclic name data is provided, 184 * then numeric formatting is used (behaves like 'y').</td> 185 * </tr> 186 * <tr> 187 * <td style="text-align: center">4</td> 188 * <td>(currently also 甲子)</td> 189 * </tr> 190 * <tr> 191 * <td style="text-align: center">5</td> 192 * <td>(currently also 甲子)</td> 193 * </tr> 194 * <tr> 195 * <th rowspan="6">quarter</th> 196 * <td rowspan="3" style="text-align: center">Q</td> 197 * <td style="text-align: center">1..2</td> 198 * <td>02</td> 199 * <td rowspan="3">Quarter - Use one or two for the numerical quarter, three for the abbreviation, or four 200 * for the full name.</td> 201 * </tr> 202 * <tr> 203 * <td style="text-align: center">3</td> 204 * <td>Q2</td> 205 * </tr> 206 * <tr> 207 * <td style="text-align: center">4</td> 208 * <td>2nd quarter</td> 209 * </tr> 210 * <tr> 211 * <td rowspan="3" style="text-align: center">q</td> 212 * <td style="text-align: center">1..2</td> 213 * <td>02</td> 214 * <td rowspan="3"><b>Stand-Alone</b> Quarter - Use one or two for the numerical quarter, three for the abbreviation, 215 * or four for the full name.</td> 216 * </tr> 217 * <tr> 218 * <td style="text-align: center">3</td> 219 * <td>Q2</td> 220 * </tr> 221 * <tr> 222 * <td style="text-align: center">4</td> 223 * <td>2nd quarter</td> 224 * </tr> 225 * <tr> 226 * <th rowspan="8">month</th> 227 * <td rowspan="4" style="text-align: center">M</td> 228 * <td style="text-align: center">1..2</td> 229 * <td>09</td> 230 * <td rowspan="4">Month - Use one or two for the numerical month, three for the abbreviation, four for 231 * the full name, or five for the narrow name.</td> 232 * </tr> 233 * <tr> 234 * <td style="text-align: center">3</td> 235 * <td>Sept</td> 236 * </tr> 237 * <tr> 238 * <td style="text-align: center">4</td> 239 * <td>September</td> 240 * </tr> 241 * <tr> 242 * <td style="text-align: center">5</td> 243 * <td>S</td> 244 * </tr> 245 * <tr> 246 * <td rowspan="4" style="text-align: center">L</td> 247 * <td style="text-align: center">1..2</td> 248 * <td>09</td> 249 * <td rowspan="4"><b>Stand-Alone</b> Month - Use one or two for the numerical month, three for the abbreviation, 250 * or four for the full name, or 5 for the narrow name.</td> 251 * </tr> 252 * <tr> 253 * <td style="text-align: center">3</td> 254 * <td>Sept</td> 255 * </tr> 256 * <tr> 257 * <td style="text-align: center">4</td> 258 * <td>September</td> 259 * </tr> 260 * <tr> 261 * <td style="text-align: center">5</td> 262 * <td>S</td> 263 * </tr> 264 * <tr> 265 * <th rowspan="2">week</th> 266 * <td style="text-align: center">w</td> 267 * <td style="text-align: center">1..2</td> 268 * <td>27</td> 269 * <td>Week of Year.</td> 270 * </tr> 271 * <tr> 272 * <td style="text-align: center">W</td> 273 * <td style="text-align: center">1</td> 274 * <td>3</td> 275 * <td>Week of Month</td> 276 * </tr> 277 * <tr> 278 * <th rowspan="4">day</th> 279 * <td style="text-align: center">d</td> 280 * <td style="text-align: center">1..2</td> 281 * <td>1</td> 282 * <td>Date - Day of the month</td> 283 * </tr> 284 * <tr> 285 * <td style="text-align: center">D</td> 286 * <td style="text-align: center">1..3</td> 287 * <td>345</td> 288 * <td>Day of year</td> 289 * </tr> 290 * <tr> 291 * <td style="text-align: center">F</td> 292 * <td style="text-align: center">1</td> 293 * <td>2</td> 294 * <td>Day of Week in Month. The example is for the 2nd Wed in July</td> 295 * </tr> 296 * <tr> 297 * <td style="text-align: center">g</td> 298 * <td style="text-align: center">1..n</td> 299 * <td>2451334</td> 300 * <td>Modified Julian day. This is different from the conventional Julian day number in two regards. 301 * First, it demarcates days at local zone midnight, rather than noon GMT. Second, it is a local number; 302 * that is, it depends on the local time zone. It can be thought of as a single number that encompasses 303 * all the date-related fields.</td> 304 * </tr> 305 * <tr> 306 * <th rowspan="14">week<br> 307 * day</th> 308 * <td rowspan="4" style="text-align: center">E</td> 309 * <td style="text-align: center">1..3</td> 310 * <td>Tues</td> 311 * <td rowspan="4">Day of week - Use one through three letters for the short day, or four for the full name, 312 * five for the narrow name, or six for the short name.</td> 313 * </tr> 314 * <tr> 315 * <td style="text-align: center">4</td> 316 * <td>Tuesday</td> 317 * </tr> 318 * <tr> 319 * <td style="text-align: center">5</td> 320 * <td>T</td> 321 * </tr> 322 * <tr> 323 * <td style="text-align: center">6</td> 324 * <td>Tu</td> 325 * </tr> 326 * <tr> 327 * <td rowspan="5" style="text-align: center">e</td> 328 * <td style="text-align: center">1..2</td> 329 * <td>2</td> 330 * <td rowspan="5">Local day of week. Same as E except adds a numeric value that will depend on the local 331 * starting day of the week, using one or two letters. For this example, Monday is the first day of the week.</td> 332 * </tr> 333 * <tr> 334 * <td style="text-align: center">3</td> 335 * <td>Tues</td> 336 * </tr> 337 * <tr> 338 * <td style="text-align: center">4</td> 339 * <td>Tuesday</td> 340 * </tr> 341 * <tr> 342 * <td style="text-align: center">5</td> 343 * <td>T</td> 344 * </tr> 345 * <tr> 346 * <td style="text-align: center">6</td> 347 * <td>Tu</td> 348 * </tr> 349 * <tr> 350 * <td rowspan="5" style="text-align: center">c</td> 351 * <td style="text-align: center">1</td> 352 * <td>2</td> 353 * <td rowspan="5"><b>Stand-Alone</b> local day of week - Use one letter for the local numeric value (same 354 * as 'e'), three for the short day, four for the full name, five for the narrow name, or six for 355 * the short name.</td> 356 * </tr> 357 * <tr> 358 * <td style="text-align: center">3</td> 359 * <td>Tues</td> 360 * </tr> 361 * <tr> 362 * <td style="text-align: center">4</td> 363 * <td>Tuesday</td> 364 * </tr> 365 * <tr> 366 * <td style="text-align: center">5</td> 367 * <td>T</td> 368 * </tr> 369 * <tr> 370 * <td style="text-align: center">6</td> 371 * <td>Tu</td> 372 * </tr> 373 * <tr> 374 * <th>period</th> 375 * <td style="text-align: center">a</td> 376 * <td style="text-align: center">1</td> 377 * <td>AM</td> 378 * <td>AM or PM</td> 379 * </tr> 380 * <tr> 381 * <th rowspan="4">hour</th> 382 * <td style="text-align: center">h</td> 383 * <td style="text-align: center">1..2</td> 384 * <td>11</td> 385 * <td>Hour [1-12]. When used in skeleton data or in a skeleton passed in an API for flexible data pattern 386 * generation, it should match the 12-hour-cycle format preferred by the locale (h or K); it should not match 387 * a 24-hour-cycle format (H or k). Use hh for zero padding.</td> 388 * </tr> 389 * <tr> 390 * <td style="text-align: center">H</td> 391 * <td style="text-align: center">1..2</td> 392 * <td>13</td> 393 * <td>Hour [0-23]. When used in skeleton data or in a skeleton passed in an API for flexible data pattern 394 * generation, it should match the 24-hour-cycle format preferred by the locale (H or k); it should not match a 395 * 12-hour-cycle format (h or K). Use HH for zero padding.</td> 396 * </tr> 397 * <tr> 398 * <td style="text-align: center">K</td> 399 * <td style="text-align: center">1..2</td> 400 * <td>0</td> 401 * <td>Hour [0-11]. When used in a skeleton, only matches K or h, see above. Use KK for zero padding.</td> 402 * </tr> 403 * <tr> 404 * <td style="text-align: center">k</td> 405 * <td style="text-align: center">1..2</td> 406 * <td>24</td> 407 * <td>Hour [1-24]. When used in a skeleton, only matches k or H, see above. Use kk for zero padding.</td> 408 * </tr> 409 * <tr> 410 * <th>minute</th> 411 * <td style="text-align: center">m</td> 412 * <td style="text-align: center">1..2</td> 413 * <td>59</td> 414 * <td>Minute. Use one or two for zero padding.</td> 415 * </tr> 416 * <tr> 417 * <th rowspan="3">second</th> 418 * <td style="text-align: center">s</td> 419 * <td style="text-align: center">1..2</td> 420 * <td>12</td> 421 * <td>Second. Use one or two for zero padding.</td> 422 * </tr> 423 * <tr> 424 * <td style="text-align: center">S</td> 425 * <td style="text-align: center">1..n</td> 426 * <td>3456</td> 427 * <td>Fractional Second - truncates (like other time fields) to the count of letters. 428 * (example shows display using pattern SSSS for seconds value 12.34567)</td> 429 * </tr> 430 * <tr> 431 * <td style="text-align: center">A</td> 432 * <td style="text-align: center">1..n</td> 433 * <td>69540000</td> 434 * <td>Milliseconds in day. This field behaves <i>exactly</i> like a composite of all time-related fields, 435 * not including the zone fields. As such, it also reflects discontinuities of those fields on DST transition 436 * days. On a day of DST onset, it will jump forward. On a day of DST cessation, it will jump backward. This 437 * reflects the fact that is must be combined with the offset field to obtain a unique local time value.</td> 438 * </tr> 439 * <tr> 440 * <th rowspan="23">zone</th> 441 * <td rowspan="2" style="text-align: center">z</td> 442 * <td style="text-align: center">1..3</td> 443 * <td>PDT</td> 444 * <td>The <i>short specific non-location format</i>. 445 * Where that is unavailable, falls back to the <i>short localized GMT format</i> ("O").</td> 446 * </tr> 447 * <tr> 448 * <td style="text-align: center">4</td> 449 * <td>Pacific Daylight Time</td> 450 * <td>The <i>long specific non-location format</i>. 451 * Where that is unavailable, falls back to the <i>long localized GMT format</i> ("OOOO").</td> 452 * </tr> 453 * <tr> 454 * <td rowspan="3" style="text-align: center">Z</td> 455 * <td style="text-align: center">1..3</td> 456 * <td>-0800</td> 457 * <td>The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 458 * The format is equivalent to RFC 822 zone format (when optional seconds field is absent). 459 * This is equivalent to the "xxxx" specifier.</td> 460 * </tr> 461 * <tr> 462 * <td style="text-align: center">4</td> 463 * <td>GMT-8:00</td> 464 * <td>The <i>long localized GMT format</i>. 465 * This is equivalent to the "OOOO" specifier.</td> 466 * </tr> 467 * <tr> 468 * <td style="text-align: center">5</td> 469 * <td>-08:00<br> 470 * -07:52:58</td> 471 * <td>The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 472 * The ISO8601 UTC indicator "Z" is used when local time offset is 0. 473 * This is equivalent to the "XXXXX" specifier.</td> 474 * </tr> 475 * <tr> 476 * <td rowspan="2" style="text-align: center">O</td> 477 * <td style="text-align: center">1</td> 478 * <td>GMT-8</td> 479 * <td>The <i>short localized GMT format</i>.</td> 480 * </tr> 481 * <tr> 482 * <td style="text-align: center">4</td> 483 * <td>GMT-08:00</td> 484 * <td>The <i>long localized GMT format</i>.</td> 485 * </tr> 486 * <tr> 487 * <td rowspan="2" style="text-align: center">v</td> 488 * <td style="text-align: center">1</td> 489 * <td>PT</td> 490 * <td>The <i>short generic non-location format</i>. 491 * Where that is unavailable, falls back to the <i>generic location format</i> ("VVVV"), 492 * then the <i>short localized GMT format</i> as the final fallback.</td> 493 * </tr> 494 * <tr> 495 * <td style="text-align: center">4</td> 496 * <td>Pacific Time</td> 497 * <td>The <i>long generic non-location format</i>. 498 * Where that is unavailable, falls back to <i>generic location format</i> ("VVVV"). 499 * </tr> 500 * <tr> 501 * <td rowspan="4" style="text-align: center">V</td> 502 * <td style="text-align: center">1</td> 503 * <td>uslax</td> 504 * <td>The short time zone ID. 505 * Where that is unavailable, the special short time zone ID <i>unk</i> (Unknown Zone) is used.<br> 506 * <i><b>Note</b>: This specifier was originally used for a variant of the short specific non-location format, 507 * but it was deprecated in the later version of the LDML specification. In CLDR 23/ICU 51, the definition of 508 * the specifier was changed to designate a short time zone ID.</i></td> 509 * </tr> 510 * <tr> 511 * <td style="text-align: center">2</td> 512 * <td>America/Los_Angeles</td> 513 * <td>The long time zone ID.</td> 514 * </tr> 515 * <tr> 516 * <td style="text-align: center">3</td> 517 * <td>Los Angeles</td> 518 * <td>The exemplar city (location) for the time zone. 519 * Where that is unavailable, the localized exemplar city name for the special zone <i>Etc/Unknown</i> is used 520 * as the fallback (for example, "Unknown City"). </td> 521 * </tr> 522 * <tr> 523 * <td style="text-align: center">4</td> 524 * <td>Los Angeles Time</td> 525 * <td>The <i>generic location format</i>. 526 * Where that is unavailable, falls back to the <i>long localized GMT format</i> ("OOOO"; 527 * Note: Fallback is only necessary with a GMT-style Time Zone ID, like Etc/GMT-830.)<br> 528 * This is especially useful when presenting possible timezone choices for user selection, 529 * since the naming is more uniform than the "v" format.</td> 530 * </tr> 531 * <tr> 532 * <td rowspan="5" style="text-align: center">X</td> 533 * <td style="text-align: center">1</td> 534 * <td>-08<br> 535 * +0530<br> 536 * Z</td> 537 * <td>The <i>ISO8601 basic format</i> with hours field and optional minutes field. 538 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 539 * </tr> 540 * <tr> 541 * <td style="text-align: center">2</td> 542 * <td>-0800<br> 543 * Z</td> 544 * <td>The <i>ISO8601 basic format</i> with hours and minutes fields. 545 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 546 * </tr> 547 * <tr> 548 * <td style="text-align: center">3</td> 549 * <td>-08:00<br> 550 * Z</td> 551 * <td>The <i>ISO8601 extended format</i> with hours and minutes fields. 552 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 553 * </tr> 554 * <tr> 555 * <td style="text-align: center">4</td> 556 * <td>-0800<br> 557 * -075258<br> 558 * Z</td> 559 * <td>The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 560 * (Note: The seconds field is not supported by the ISO8601 specification.) 561 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 562 * </tr> 563 * <tr> 564 * <td style="text-align: center">5</td> 565 * <td>-08:00<br> 566 * -07:52:58<br> 567 * Z</td> 568 * <td>The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 569 * (Note: The seconds field is not supported by the ISO8601 specification.) 570 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 571 * </tr> 572 * <tr> 573 * <td rowspan="5" style="text-align: center">x</td> 574 * <td style="text-align: center">1</td> 575 * <td>-08<br> 576 * +0530</td> 577 * <td>The <i>ISO8601 basic format</i> with hours field and optional minutes field.</td> 578 * </tr> 579 * <tr> 580 * <td style="text-align: center">2</td> 581 * <td>-0800</td> 582 * <td>The <i>ISO8601 basic format</i> with hours and minutes fields.</td> 583 * </tr> 584 * <tr> 585 * <td style="text-align: center">3</td> 586 * <td>-08:00</td> 587 * <td>The <i>ISO8601 extended format</i> with hours and minutes fields.</td> 588 * </tr> 589 * <tr> 590 * <td style="text-align: center">4</td> 591 * <td>-0800<br> 592 * -075258</td> 593 * <td>The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 594 * (Note: The seconds field is not supported by the ISO8601 specification.)</td> 595 * </tr> 596 * <tr> 597 * <td style="text-align: center">5</td> 598 * <td>-08:00<br> 599 * -07:52:58</td> 600 * <td>The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 601 * (Note: The seconds field is not supported by the ISO8601 specification.)</td> 602 * </tr> 603 * </table> 604 * 605 * <P> 606 * Any characters in the pattern that are not in the ranges of ['a'..'z'] and 607 * ['A'..'Z'] will be treated as quoted text. For instance, characters 608 * like ':', '.', ' ', '#' and '@' will appear in the resulting time text 609 * even they are not embraced within single quotes. 610 * <P> 611 * A pattern containing any invalid pattern letter will result in a failing 612 * UErrorCode result during formatting or parsing. 613 * <P> 614 * Examples using the US locale: 615 * <pre> 616 * \code 617 * Format Pattern Result 618 * -------------- ------- 619 * "yyyy.MM.dd G 'at' HH:mm:ss vvvv" ->> 1996.07.10 AD at 15:08:56 Pacific Time 620 * "EEE, MMM d, ''yy" ->> Wed, July 10, '96 621 * "h:mm a" ->> 12:08 PM 622 * "hh 'o''clock' a, zzzz" ->> 12 o'clock PM, Pacific Daylight Time 623 * "K:mm a, vvv" ->> 0:00 PM, PT 624 * "yyyyy.MMMMM.dd GGG hh:mm aaa" ->> 1996.July.10 AD 12:08 PM 625 * \endcode 626 * </pre> 627 * Code Sample: 628 * <pre> 629 * \code 630 * UErrorCode success = U_ZERO_ERROR; 631 * SimpleTimeZone* pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST"); 632 * pdt->setStartRule( Calendar::APRIL, 1, Calendar::SUNDAY, 2*60*60*1000); 633 * pdt->setEndRule( Calendar::OCTOBER, -1, Calendar::SUNDAY, 2*60*60*1000); 634 * 635 * // Format the current time. 636 * SimpleDateFormat* formatter 637 * = new SimpleDateFormat ("yyyy.MM.dd G 'at' hh:mm:ss a zzz", success ); 638 * GregorianCalendar cal(success); 639 * UDate currentTime_1 = cal.getTime(success); 640 * FieldPosition fp(0); 641 * UnicodeString dateString; 642 * formatter->format( currentTime_1, dateString, fp ); 643 * cout << "result: " << dateString << endl; 644 * 645 * // Parse the previous string back into a Date. 646 * ParsePosition pp(0); 647 * UDate currentTime_2 = formatter->parse(dateString, pp ); 648 * \endcode 649 * </pre> 650 * In the above example, the time value "currentTime_2" obtained from parsing 651 * will be equal to currentTime_1. However, they may not be equal if the am/pm 652 * marker 'a' is left out from the format pattern while the "hour in am/pm" 653 * pattern symbol is used. This information loss can happen when formatting the 654 * time in PM. 655 * 656 * <p> 657 * When parsing a date string using the abbreviated year pattern ("y" or "yy"), 658 * SimpleDateFormat must interpret the abbreviated year 659 * relative to some century. It does this by adjusting dates to be 660 * within 80 years before and 20 years after the time the SimpleDateFormat 661 * instance is created. For example, using a pattern of "MM/dd/yy" and a 662 * SimpleDateFormat instance created on Jan 1, 1997, the string 663 * "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" 664 * would be interpreted as May 4, 1964. 665 * During parsing, only strings consisting of exactly two digits, as defined by 666 * <code>Unicode::isDigit()</code>, will be parsed into the default century. 667 * Any other numeric string, such as a one digit string, a three or more digit 668 * string, or a two digit string that isn't all digits (for example, "-1"), is 669 * interpreted literally. So "01/02/3" or "01/02/003" are parsed (for the 670 * Gregorian calendar), using the same pattern, as Jan 2, 3 AD. Likewise (but 671 * only in lenient parse mode, the default) "01/02/-3" is parsed as Jan 2, 4 BC. 672 * 673 * <p> 674 * If the year pattern has more than two 'y' characters, the year is 675 * interpreted literally, regardless of the number of digits. So using the 676 * pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D. 677 * 678 * <p> 679 * When numeric fields abut one another directly, with no intervening delimiter 680 * characters, they constitute a run of abutting numeric fields. Such runs are 681 * parsed specially. For example, the format "HHmmss" parses the input text 682 * "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to 683 * parse "1234". In other words, the leftmost field of the run is flexible, 684 * while the others keep a fixed width. If the parse fails anywhere in the run, 685 * then the leftmost field is shortened by one character, and the entire run is 686 * parsed again. This is repeated until either the parse succeeds or the 687 * leftmost field is one character in length. If the parse still fails at that 688 * point, the parse of the run fails. 689 * 690 * <P> 691 * For time zones that have no names, SimpleDateFormat uses strings GMT+hours:minutes or 692 * GMT-hours:minutes. 693 * <P> 694 * The calendar defines what is the first day of the week, the first week of the 695 * year, whether hours are zero based or not (0 vs 12 or 24), and the timezone. 696 * There is one common number format to handle all the numbers; the digit count 697 * is handled programmatically according to the pattern. 698 * 699 * <p><em>User subclasses are not supported.</em> While clients may write 700 * subclasses, such code will not necessarily work and will not be 701 * guaranteed to work stably from release to release. 702 */ 703class U_I18N_API SimpleDateFormat: public DateFormat { 704public: 705 /** 706 * Construct a SimpleDateFormat using the default pattern for the default 707 * locale. 708 * <P> 709 * [Note:] Not all locales support SimpleDateFormat; for full generality, 710 * use the factory methods in the DateFormat class. 711 * @param status Output param set to success/failure code. 712 * @stable ICU 2.0 713 */ 714 SimpleDateFormat(UErrorCode& status); 715 716 /** 717 * Construct a SimpleDateFormat using the given pattern and the default locale. 718 * The locale is used to obtain the symbols used in formatting (e.g., the 719 * names of the months), but not to provide the pattern. 720 * <P> 721 * [Note:] Not all locales support SimpleDateFormat; for full generality, 722 * use the factory methods in the DateFormat class. 723 * @param pattern the pattern for the format. 724 * @param status Output param set to success/failure code. 725 * @stable ICU 2.0 726 */ 727 SimpleDateFormat(const UnicodeString& pattern, 728 UErrorCode& status); 729 730 /** 731 * Construct a SimpleDateFormat using the given pattern, numbering system override, and the default locale. 732 * The locale is used to obtain the symbols used in formatting (e.g., the 733 * names of the months), but not to provide the pattern. 734 * <P> 735 * A numbering system override is a string containing either the name of a known numbering system, 736 * or a set of field and numbering system pairs that specify which fields are to be formattied with 737 * the alternate numbering system. For example, to specify that all numeric fields in the specified 738 * date or time pattern are to be rendered using Thai digits, simply specify the numbering system override 739 * as "thai". To specify that just the year portion of the date be formatted using Hebrew numbering, 740 * use the override string "y=hebrew". Numbering system overrides can be combined using a semi-colon 741 * character in the override string, such as "d=decimal;M=arabic;y=hebrew", etc. 742 * 743 * <P> 744 * [Note:] Not all locales support SimpleDateFormat; for full generality, 745 * use the factory methods in the DateFormat class. 746 * @param pattern the pattern for the format. 747 * @param override the override string. 748 * @param status Output param set to success/failure code. 749 * @stable ICU 4.2 750 */ 751 SimpleDateFormat(const UnicodeString& pattern, 752 const UnicodeString& override, 753 UErrorCode& status); 754 755 /** 756 * Construct a SimpleDateFormat using the given pattern and locale. 757 * The locale is used to obtain the symbols used in formatting (e.g., the 758 * names of the months), but not to provide the pattern. 759 * <P> 760 * [Note:] Not all locales support SimpleDateFormat; for full generality, 761 * use the factory methods in the DateFormat class. 762 * @param pattern the pattern for the format. 763 * @param locale the given locale. 764 * @param status Output param set to success/failure code. 765 * @stable ICU 2.0 766 */ 767 SimpleDateFormat(const UnicodeString& pattern, 768 const Locale& locale, 769 UErrorCode& status); 770 771 /** 772 * Construct a SimpleDateFormat using the given pattern, numbering system override, and locale. 773 * The locale is used to obtain the symbols used in formatting (e.g., the 774 * names of the months), but not to provide the pattern. 775 * <P> 776 * A numbering system override is a string containing either the name of a known numbering system, 777 * or a set of field and numbering system pairs that specify which fields are to be formattied with 778 * the alternate numbering system. For example, to specify that all numeric fields in the specified 779 * date or time pattern are to be rendered using Thai digits, simply specify the numbering system override 780 * as "thai". To specify that just the year portion of the date be formatted using Hebrew numbering, 781 * use the override string "y=hebrew". Numbering system overrides can be combined using a semi-colon 782 * character in the override string, such as "d=decimal;M=arabic;y=hebrew", etc. 783 * <P> 784 * [Note:] Not all locales support SimpleDateFormat; for full generality, 785 * use the factory methods in the DateFormat class. 786 * @param pattern the pattern for the format. 787 * @param override the numbering system override. 788 * @param locale the given locale. 789 * @param status Output param set to success/failure code. 790 * @stable ICU 4.2 791 */ 792 SimpleDateFormat(const UnicodeString& pattern, 793 const UnicodeString& override, 794 const Locale& locale, 795 UErrorCode& status); 796 797 /** 798 * Construct a SimpleDateFormat using the given pattern and locale-specific 799 * symbol data. The formatter takes ownership of the DateFormatSymbols object; 800 * the caller is no longer responsible for deleting it. 801 * @param pattern the given pattern for the format. 802 * @param formatDataToAdopt the symbols to be adopted. 803 * @param status Output param set to success/faulure code. 804 * @stable ICU 2.0 805 */ 806 SimpleDateFormat(const UnicodeString& pattern, 807 DateFormatSymbols* formatDataToAdopt, 808 UErrorCode& status); 809 810 /** 811 * Construct a SimpleDateFormat using the given pattern and locale-specific 812 * symbol data. The DateFormatSymbols object is NOT adopted; the caller 813 * remains responsible for deleting it. 814 * @param pattern the given pattern for the format. 815 * @param formatData the formatting symbols to be use. 816 * @param status Output param set to success/faulure code. 817 * @stable ICU 2.0 818 */ 819 SimpleDateFormat(const UnicodeString& pattern, 820 const DateFormatSymbols& formatData, 821 UErrorCode& status); 822 823 /** 824 * Copy constructor. 825 * @stable ICU 2.0 826 */ 827 SimpleDateFormat(const SimpleDateFormat&); 828 829 /** 830 * Assignment operator. 831 * @stable ICU 2.0 832 */ 833 SimpleDateFormat& operator=(const SimpleDateFormat&); 834 835 /** 836 * Destructor. 837 * @stable ICU 2.0 838 */ 839 virtual ~SimpleDateFormat(); 840 841 /** 842 * Clone this Format object polymorphically. The caller owns the result and 843 * should delete it when done. 844 * @return A copy of the object. 845 * @stable ICU 2.0 846 */ 847 virtual Format* clone(void) const; 848 849 /** 850 * Return true if the given Format objects are semantically equal. Objects 851 * of different subclasses are considered unequal. 852 * @param other the object to be compared with. 853 * @return true if the given Format objects are semantically equal. 854 * @stable ICU 2.0 855 */ 856 virtual UBool operator==(const Format& other) const; 857 858 859 using DateFormat::format; 860 861 /** 862 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 863 * 1, 1970. Overrides DateFormat pure virtual method. 864 * <P> 865 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 866 * 1996.07.10 AD at 15:08:56 PDT 867 * 868 * @param cal Calendar set to the date and time to be formatted 869 * into a date/time string. 870 * @param appendTo Output parameter to receive result. 871 * Result is appended to existing contents. 872 * @param pos The formatting position. On input: an alignment field, 873 * if desired. On output: the offsets of the alignment field. 874 * @return Reference to 'appendTo' parameter. 875 * @stable ICU 2.1 876 */ 877 virtual UnicodeString& format( Calendar& cal, 878 UnicodeString& appendTo, 879 FieldPosition& pos) const; 880 881 /** 882 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 883 * 1, 1970. Overrides DateFormat pure virtual method. 884 * <P> 885 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 886 * 1996.07.10 AD at 15:08:56 PDT 887 * 888 * @param cal Calendar set to the date and time to be formatted 889 * into a date/time string. 890 * @param appendTo Output parameter to receive result. 891 * Result is appended to existing contents. 892 * @param posIter On return, can be used to iterate over positions 893 * of fields generated by this format call. Field values 894 * are defined in UDateFormatField. 895 * @param status Input/output param set to success/failure code. 896 * @return Reference to 'appendTo' parameter. 897 * @stable ICU 4.4 898 */ 899 virtual UnicodeString& format( Calendar& cal, 900 UnicodeString& appendTo, 901 FieldPositionIterator* posIter, 902 UErrorCode& status) const; 903 904 /** 905 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 906 * 1, 1970. Overrides DateFormat pure virtual method. 907 * <P> 908 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 909 * 1996.07.10 AD at 15:08:56 PDT 910 * 911 * @param obj A Formattable containing the date-time value to be formatted 912 * into a date-time string. If the type of the Formattable 913 * is a numeric type, it is treated as if it were an 914 * instance of Date. 915 * @param appendTo Output parameter to receive result. 916 * Result is appended to existing contents. 917 * @param pos The formatting position. On input: an alignment field, 918 * if desired. On output: the offsets of the alignment field. 919 * @param status Input/output param set to success/failure code. 920 * @return Reference to 'appendTo' parameter. 921 * @stable ICU 2.0 922 */ 923 virtual UnicodeString& format( const Formattable& obj, 924 UnicodeString& appendTo, 925 FieldPosition& pos, 926 UErrorCode& status) const; 927 928 /** 929 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 930 * 1, 1970. Overrides DateFormat pure virtual method. 931 * <P> 932 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 933 * 1996.07.10 AD at 15:08:56 PDT 934 * 935 * @param obj A Formattable containing the date-time value to be formatted 936 * into a date-time string. If the type of the Formattable 937 * is a numeric type, it is treated as if it were an 938 * instance of Date. 939 * @param appendTo Output parameter to receive result. 940 * Result is appended to existing contents. 941 * @param posIter On return, can be used to iterate over positions 942 * of fields generated by this format call. Field values 943 * are defined in UDateFormatField. 944 * @param status Input/output param set to success/failure code. 945 * @return Reference to 'appendTo' parameter. 946 * @stable ICU 4.4 947 */ 948 virtual UnicodeString& format( const Formattable& obj, 949 UnicodeString& appendTo, 950 FieldPositionIterator* posIter, 951 UErrorCode& status) const; 952 953 /** 954 * Redeclared DateFormat method. 955 * @param date the Date value to be formatted. 956 * @param appendTo Output parameter to receive result. 957 * Result is appended to existing contents. 958 * @param fieldPosition The formatting position. On input: an alignment field, 959 * if desired. On output: the offsets of the alignment field. 960 * @return Reference to 'appendTo' parameter. 961 * @stable ICU 2.1 962 */ 963 UnicodeString& format(UDate date, 964 UnicodeString& appendTo, 965 FieldPosition& fieldPosition) const; 966 967 /** 968 * Redeclared DateFormat method. 969 * @param date the Date value to be formatted. 970 * @param appendTo Output parameter to receive result. 971 * Result is appended to existing contents. 972 * @param posIter On return, can be used to iterate over positions 973 * of fields generated by this format call. Field values 974 * are defined in UDateFormatField. 975 * @param status Input/output param set to success/failure code. 976 * @return Reference to 'appendTo' parameter. 977 * @stable ICU 4.4 978 */ 979 UnicodeString& format(UDate date, 980 UnicodeString& appendTo, 981 FieldPositionIterator* posIter, 982 UErrorCode& status) const; 983 984 /** 985 * Redeclared DateFormat method. 986 * @param obj Object to be formatted. 987 * @param appendTo Output parameter to receive result. 988 * Result is appended to existing contents. 989 * @param status Input/output success/failure code. 990 * @return Reference to 'appendTo' parameter. 991 * @stable ICU 2.0 992 */ 993 UnicodeString& format(const Formattable& obj, 994 UnicodeString& appendTo, 995 UErrorCode& status) const; 996 997 /** 998 * Redeclared DateFormat method. 999 * @param date Date value to be formatted. 1000 * @param appendTo Output parameter to receive result. 1001 * Result is appended to existing contents. 1002 * @return Reference to 'appendTo' parameter. 1003 * @stable ICU 2.0 1004 */ 1005 UnicodeString& format(UDate date, UnicodeString& appendTo) const; 1006 1007 /** 1008 * Parse a date/time string beginning at the given parse position. For 1009 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 1010 * that is equivalent to Date(837039928046). 1011 * <P> 1012 * By default, parsing is lenient: If the input is not in the form used by 1013 * this object's format method but can still be parsed as a date, then the 1014 * parse succeeds. Clients may insist on strict adherence to the format by 1015 * calling setLenient(false). 1016 * @see DateFormat::setLenient(boolean) 1017 * 1018 * @param text The date/time string to be parsed 1019 * @param cal A Calendar set on input to the date and time to be used for 1020 * missing values in the date/time string being parsed, and set 1021 * on output to the parsed date/time. When the calendar type is 1022 * different from the internal calendar held by this SimpleDateFormat 1023 * instance, the internal calendar will be cloned to a work 1024 * calendar set to the same milliseconds and time zone as the 1025 * cal parameter, field values will be parsed based on the work 1026 * calendar, then the result (milliseconds and time zone) will 1027 * be set in this calendar. 1028 * @param pos On input, the position at which to start parsing; on 1029 * output, the position at which parsing terminated, or the 1030 * start position if the parse failed. 1031 * @stable ICU 2.1 1032 */ 1033 virtual void parse( const UnicodeString& text, 1034 Calendar& cal, 1035 ParsePosition& pos) const; 1036 1037 /** 1038 * Parse a date/time string starting at the given parse position. For 1039 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 1040 * that is equivalent to Date(837039928046). 1041 * <P> 1042 * By default, parsing is lenient: If the input is not in the form used by 1043 * this object's format method but can still be parsed as a date, then the 1044 * parse succeeds. Clients may insist on strict adherence to the format by 1045 * calling setLenient(false). 1046 * @see DateFormat::setLenient(boolean) 1047 * <P> 1048 * Note that the normal date formats associated with some calendars - such 1049 * as the Chinese lunar calendar - do not specify enough fields to enable 1050 * dates to be parsed unambiguously. In the case of the Chinese lunar 1051 * calendar, while the year within the current 60-year cycle is specified, 1052 * the number of such cycles since the start date of the calendar (in the 1053 * ERA field of the Calendar object) is not normally part of the format, 1054 * and parsing may assume the wrong era. For cases such as this it is 1055 * recommended that clients parse using the method 1056 * parse(const UnicodeString&, Calendar& cal, ParsePosition&) 1057 * with the Calendar passed in set to the current date, or to a date 1058 * within the era/cycle that should be assumed if absent in the format. 1059 * 1060 * @param text The date/time string to be parsed 1061 * @param pos On input, the position at which to start parsing; on 1062 * output, the position at which parsing terminated, or the 1063 * start position if the parse failed. 1064 * @return A valid UDate if the input could be parsed. 1065 * @stable ICU 2.0 1066 */ 1067 UDate parse( const UnicodeString& text, 1068 ParsePosition& pos) const; 1069 1070 1071 /** 1072 * Parse a date/time string. For example, a time text "07/10/96 4:5 PM, PDT" 1073 * will be parsed into a UDate that is equivalent to Date(837039928046). 1074 * Parsing begins at the beginning of the string and proceeds as far as 1075 * possible. Assuming no parse errors were encountered, this function 1076 * doesn't return any information about how much of the string was consumed 1077 * by the parsing. If you need that information, use the version of 1078 * parse() that takes a ParsePosition. 1079 * <P> 1080 * By default, parsing is lenient: If the input is not in the form used by 1081 * this object's format method but can still be parsed as a date, then the 1082 * parse succeeds. Clients may insist on strict adherence to the format by 1083 * calling setLenient(false). 1084 * @see DateFormat::setLenient(boolean) 1085 * <P> 1086 * Note that the normal date formats associated with some calendars - such 1087 * as the Chinese lunar calendar - do not specify enough fields to enable 1088 * dates to be parsed unambiguously. In the case of the Chinese lunar 1089 * calendar, while the year within the current 60-year cycle is specified, 1090 * the number of such cycles since the start date of the calendar (in the 1091 * ERA field of the Calendar object) is not normally part of the format, 1092 * and parsing may assume the wrong era. For cases such as this it is 1093 * recommended that clients parse using the method 1094 * parse(const UnicodeString&, Calendar& cal, ParsePosition&) 1095 * with the Calendar passed in set to the current date, or to a date 1096 * within the era/cycle that should be assumed if absent in the format. 1097 * 1098 * @param text The date/time string to be parsed into a UDate value. 1099 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 1100 * an error value if there was a parse error. 1101 * @return A valid UDate if the input could be parsed. 1102 * @stable ICU 2.0 1103 */ 1104 virtual UDate parse( const UnicodeString& text, 1105 UErrorCode& status) const; 1106 1107 /** 1108 * Set the start UDate used to interpret two-digit year strings. 1109 * When dates are parsed having 2-digit year strings, they are placed within 1110 * a assumed range of 100 years starting on the two digit start date. For 1111 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or 1112 * some other year. SimpleDateFormat chooses a year so that the resultant 1113 * date is on or after the two digit start date and within 100 years of the 1114 * two digit start date. 1115 * <P> 1116 * By default, the two digit start date is set to 80 years before the current 1117 * time at which a SimpleDateFormat object is created. 1118 * @param d start UDate used to interpret two-digit year strings. 1119 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 1120 * an error value if there was a parse error. 1121 * @stable ICU 2.0 1122 */ 1123 virtual void set2DigitYearStart(UDate d, UErrorCode& status); 1124 1125 /** 1126 * Get the start UDate used to interpret two-digit year strings. 1127 * When dates are parsed having 2-digit year strings, they are placed within 1128 * a assumed range of 100 years starting on the two digit start date. For 1129 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or 1130 * some other year. SimpleDateFormat chooses a year so that the resultant 1131 * date is on or after the two digit start date and within 100 years of the 1132 * two digit start date. 1133 * <P> 1134 * By default, the two digit start date is set to 80 years before the current 1135 * time at which a SimpleDateFormat object is created. 1136 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 1137 * an error value if there was a parse error. 1138 * @stable ICU 2.0 1139 */ 1140 UDate get2DigitYearStart(UErrorCode& status) const; 1141 1142 /** 1143 * Return a pattern string describing this date format. 1144 * @param result Output param to receive the pattern. 1145 * @return A reference to 'result'. 1146 * @stable ICU 2.0 1147 */ 1148 virtual UnicodeString& toPattern(UnicodeString& result) const; 1149 1150 /** 1151 * Return a localized pattern string describing this date format. 1152 * In most cases, this will return the same thing as toPattern(), 1153 * but a locale can specify characters to use in pattern descriptions 1154 * in place of the ones described in this class's class documentation. 1155 * (Presumably, letters that would be more mnemonic in that locale's 1156 * language.) This function would produce a pattern using those 1157 * letters. 1158 * 1159 * @param result Receives the localized pattern. 1160 * @param status Output param set to success/failure code on 1161 * exit. If the pattern is invalid, this will be 1162 * set to a failure result. 1163 * @return A reference to 'result'. 1164 * @stable ICU 2.0 1165 */ 1166 virtual UnicodeString& toLocalizedPattern(UnicodeString& result, 1167 UErrorCode& status) const; 1168 1169 /** 1170 * Apply the given unlocalized pattern string to this date format. 1171 * (i.e., after this call, this formatter will format dates according to 1172 * the new pattern) 1173 * 1174 * @param pattern The pattern to be applied. 1175 * @stable ICU 2.0 1176 */ 1177 virtual void applyPattern(const UnicodeString& pattern); 1178 1179 /** 1180 * Apply the given localized pattern string to this date format. 1181 * (see toLocalizedPattern() for more information on localized patterns.) 1182 * 1183 * @param pattern The localized pattern to be applied. 1184 * @param status Output param set to success/failure code on 1185 * exit. If the pattern is invalid, this will be 1186 * set to a failure result. 1187 * @stable ICU 2.0 1188 */ 1189 virtual void applyLocalizedPattern(const UnicodeString& pattern, 1190 UErrorCode& status); 1191 1192 /** 1193 * Gets the date/time formatting symbols (this is an object carrying 1194 * the various strings and other symbols used in formatting: e.g., month 1195 * names and abbreviations, time zone names, AM/PM strings, etc.) 1196 * @return a copy of the date-time formatting data associated 1197 * with this date-time formatter. 1198 * @stable ICU 2.0 1199 */ 1200 virtual const DateFormatSymbols* getDateFormatSymbols(void) const; 1201 1202 /** 1203 * Set the date/time formatting symbols. The caller no longer owns the 1204 * DateFormatSymbols object and should not delete it after making this call. 1205 * @param newFormatSymbols the given date-time formatting symbols to copy. 1206 * @stable ICU 2.0 1207 */ 1208 virtual void adoptDateFormatSymbols(DateFormatSymbols* newFormatSymbols); 1209 1210 /** 1211 * Set the date/time formatting data. 1212 * @param newFormatSymbols the given date-time formatting symbols to copy. 1213 * @stable ICU 2.0 1214 */ 1215 virtual void setDateFormatSymbols(const DateFormatSymbols& newFormatSymbols); 1216 1217 /** 1218 * Return the class ID for this class. This is useful only for comparing to 1219 * a return value from getDynamicClassID(). For example: 1220 * <pre> 1221 * . Base* polymorphic_pointer = createPolymorphicObject(); 1222 * . if (polymorphic_pointer->getDynamicClassID() == 1223 * . erived::getStaticClassID()) ... 1224 * </pre> 1225 * @return The class ID for all objects of this class. 1226 * @stable ICU 2.0 1227 */ 1228 static UClassID U_EXPORT2 getStaticClassID(void); 1229 1230 /** 1231 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 1232 * method is to implement a simple version of RTTI, since not all C++ 1233 * compilers support genuine RTTI. Polymorphic operator==() and clone() 1234 * methods call this method. 1235 * 1236 * @return The class ID for this object. All objects of a 1237 * given class have the same class ID. Objects of 1238 * other classes have different class IDs. 1239 * @stable ICU 2.0 1240 */ 1241 virtual UClassID getDynamicClassID(void) const; 1242 1243 /** 1244 * Set the calendar to be used by this date format. Initially, the default 1245 * calendar for the specified or default locale is used. The caller should 1246 * not delete the Calendar object after it is adopted by this call. 1247 * Adopting a new calendar will change to the default symbols. 1248 * 1249 * @param calendarToAdopt Calendar object to be adopted. 1250 * @stable ICU 2.0 1251 */ 1252 virtual void adoptCalendar(Calendar* calendarToAdopt); 1253 1254 /* Cannot use #ifndef U_HIDE_DRAFT_API for the following draft method since it is virtual */ 1255 /** 1256 * Set a particular UDisplayContext value in the formatter, such as 1257 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. 1258 * @param value The UDisplayContext value to set. 1259 * @param status Input/output status. If at entry this indicates a failure 1260 * status, the function will do nothing; otherwise this will be 1261 * updated with any new status from the function. 1262 * @draft ICU 51 1263 */ 1264 virtual void setContext(UDisplayContext value, UErrorCode& status); 1265 1266 /* Cannot use #ifndef U_HIDE_DRAFT_API for the following draft method since it is virtual */ 1267 /** 1268 * Get the formatter's UDisplayContext value for the specified UDisplayContextType, 1269 * such as UDISPCTX_TYPE_CAPITALIZATION. 1270 * @param type The UDisplayContextType whose value to return 1271 * @param status Input/output status. If at entry this indicates a failure 1272 * status, the function will do nothing; otherwise this will be 1273 * updated with any new status from the function. 1274 * @return The UDisplayContextValue for the specified type. 1275 * @draft ICU 51 1276 */ 1277 virtual UDisplayContext getContext(UDisplayContextType type, UErrorCode& status) const; 1278 1279 /* Cannot use #ifndef U_HIDE_INTERNAL_API for the following methods since they are virtual */ 1280 /** 1281 * Sets the TimeZoneFormat to be used by this date/time formatter. 1282 * The caller should not delete the TimeZoneFormat object after 1283 * it is adopted by this call. 1284 * @param timeZoneFormatToAdopt The TimeZoneFormat object to be adopted. 1285 * @internal ICU 49 technology preview 1286 */ 1287 virtual void adoptTimeZoneFormat(TimeZoneFormat* timeZoneFormatToAdopt); 1288 1289 /** 1290 * Sets the TimeZoneFormat to be used by this date/time formatter. 1291 * @param newTimeZoneFormat The TimeZoneFormat object to copy. 1292 * @internal ICU 49 technology preview 1293 */ 1294 virtual void setTimeZoneFormat(const TimeZoneFormat& newTimeZoneFormat); 1295 1296 /** 1297 * Gets the time zone format object associated with this date/time formatter. 1298 * @return the time zone format associated with this date/time formatter. 1299 * @internal ICU 49 technology preview 1300 */ 1301 virtual const TimeZoneFormat* getTimeZoneFormat(void) const; 1302 1303#ifndef U_HIDE_INTERNAL_API 1304 /** 1305 * This is for ICU internal use only. Please do not use. 1306 * Check whether the 'field' is smaller than all the fields covered in 1307 * pattern, return TRUE if it is. The sequence of calendar field, 1308 * from large to small is: ERA, YEAR, MONTH, DATE, AM_PM, HOUR, MINUTE,... 1309 * @param field the calendar field need to check against 1310 * @return TRUE if the 'field' is smaller than all the fields 1311 * covered in pattern. FALSE otherwise. 1312 * @internal ICU 4.0 1313 */ 1314 UBool isFieldUnitIgnored(UCalendarDateFields field) const; 1315 1316 1317 /** 1318 * This is for ICU internal use only. Please do not use. 1319 * Check whether the 'field' is smaller than all the fields covered in 1320 * pattern, return TRUE if it is. The sequence of calendar field, 1321 * from large to small is: ERA, YEAR, MONTH, DATE, AM_PM, HOUR, MINUTE,... 1322 * @param pattern the pattern to check against 1323 * @param field the calendar field need to check against 1324 * @return TRUE if the 'field' is smaller than all the fields 1325 * covered in pattern. FALSE otherwise. 1326 * @internal ICU 4.0 1327 */ 1328 static UBool isFieldUnitIgnored(const UnicodeString& pattern, 1329 UCalendarDateFields field); 1330 1331 /** 1332 * This is for ICU internal use only. Please do not use. 1333 * Get the locale of this simple date formatter. 1334 * It is used in DateIntervalFormat. 1335 * 1336 * @return locale in this simple date formatter 1337 * @internal ICU 4.0 1338 */ 1339 const Locale& getSmpFmtLocale(void) const; 1340#endif /* U_HIDE_INTERNAL_API */ 1341 1342private: 1343 friend class DateFormat; 1344 1345 void initializeDefaultCentury(void); 1346 1347 SimpleDateFormat(); // default constructor not implemented 1348 1349 /** 1350 * Used by the DateFormat factory methods to construct a SimpleDateFormat. 1351 * @param timeStyle the time style. 1352 * @param dateStyle the date style. 1353 * @param locale the given locale. 1354 * @param status Output param set to success/failure code on 1355 * exit. 1356 */ 1357 SimpleDateFormat(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status); 1358 1359 /** 1360 * Construct a SimpleDateFormat for the given locale. If no resource data 1361 * is available, create an object of last resort, using hard-coded strings. 1362 * This is an internal method, called by DateFormat. It should never fail. 1363 * @param locale the given locale. 1364 * @param status Output param set to success/failure code on 1365 * exit. 1366 */ 1367 SimpleDateFormat(const Locale& locale, UErrorCode& status); // Use default pattern 1368 1369 /** 1370 * Hook called by format(... FieldPosition& ...) and format(...FieldPositionIterator&...) 1371 */ 1372 UnicodeString& _format(Calendar& cal, UnicodeString& appendTo, FieldPositionHandler& handler, UErrorCode& status) const; 1373 1374 /** 1375 * Called by format() to format a single field. 1376 * 1377 * @param appendTo Output parameter to receive result. 1378 * Result is appended to existing contents. 1379 * @param ch The format character we encountered in the pattern. 1380 * @param count Number of characters in the current pattern symbol (e.g., 1381 * "yyyy" in the pattern would result in a call to this function 1382 * with ch equal to 'y' and count equal to 4) 1383 * @param capitalizationContext Capitalization context for this date format. 1384 * @param fieldNum Zero-based numbering of current field within the overall format. 1385 * @param handler Records information about field positions. 1386 * @param cal Calendar to use 1387 * @param status Receives a status code, which will be U_ZERO_ERROR if the operation 1388 * succeeds. 1389 */ 1390 void subFormat(UnicodeString &appendTo, 1391 UChar ch, 1392 int32_t count, 1393 UDisplayContext capitalizationContext, 1394 int32_t fieldNum, 1395 FieldPositionHandler& handler, 1396 Calendar& cal, 1397 UErrorCode& status) const; // in case of illegal argument 1398 1399 /** 1400 * Used by subFormat() to format a numeric value. 1401 * Appends to toAppendTo a string representation of "value" 1402 * having a number of digits between "minDigits" and 1403 * "maxDigits". Uses the DateFormat's NumberFormat. 1404 * 1405 * @param currentNumberFormat 1406 * @param appendTo Output parameter to receive result. 1407 * Formatted number is appended to existing contents. 1408 * @param value Value to format. 1409 * @param minDigits Minimum number of digits the result should have 1410 * @param maxDigits Maximum number of digits the result should have 1411 */ 1412 void zeroPaddingNumber(NumberFormat *currentNumberFormat, 1413 UnicodeString &appendTo, 1414 int32_t value, 1415 int32_t minDigits, 1416 int32_t maxDigits) const; 1417 1418 /** 1419 * Return true if the given format character, occuring count 1420 * times, represents a numeric field. 1421 */ 1422 static UBool isNumeric(UChar formatChar, int32_t count); 1423 1424 /** 1425 * Returns TRUE if the patternOffset is at the start of a numeric field. 1426 */ 1427 static UBool isAtNumericField(const UnicodeString &pattern, int32_t patternOffset); 1428 1429 /** 1430 * Returns TRUE if the patternOffset is right after a non-numeric field. 1431 */ 1432 static UBool isAfterNonNumericField(const UnicodeString &pattern, int32_t patternOffset); 1433 1434 /** 1435 * initializes fCalendar from parameters. Returns fCalendar as a convenience. 1436 * @param adoptZone Zone to be adopted, or NULL for TimeZone::createDefault(). 1437 * @param locale Locale of the calendar 1438 * @param status Error code 1439 * @return the newly constructed fCalendar 1440 */ 1441 Calendar *initializeCalendar(TimeZone* adoptZone, const Locale& locale, UErrorCode& status); 1442 1443 /** 1444 * initializes fSymbols from parameters. 1445 * @param locale Locale of the symbols 1446 * @param calendar Alias to Calendar that will be used. 1447 * @param status Error code 1448 */ 1449 void initializeSymbols(const Locale& locale, Calendar* calendar, UErrorCode& status); 1450 1451 /** 1452 * Called by several of the constructors to load pattern data and formatting symbols 1453 * out of a resource bundle and initialize the locale based on it. 1454 * @param timeStyle The time style, as passed to DateFormat::createDateInstance(). 1455 * @param dateStyle The date style, as passed to DateFormat::createTimeInstance(). 1456 * @param locale The locale to load the patterns from. 1457 * @param status Filled in with an error code if loading the data from the 1458 * resources fails. 1459 */ 1460 void construct(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status); 1461 1462 /** 1463 * Called by construct() and the various constructors to set up the SimpleDateFormat's 1464 * Calendar and NumberFormat objects. 1465 * @param locale The locale for which we want a Calendar and a NumberFormat. 1466 * @param status Filled in with an error code if creating either subobject fails. 1467 */ 1468 void initialize(const Locale& locale, UErrorCode& status); 1469 1470 /** 1471 * Private code-size reduction function used by subParse. 1472 * @param text the time text being parsed. 1473 * @param start where to start parsing. 1474 * @param field the date field being parsed. 1475 * @param stringArray the string array to parsed. 1476 * @param stringArrayCount the size of the array. 1477 * @param monthPattern pointer to leap month pattern, or NULL if none. 1478 * @param cal a Calendar set to the date and time to be formatted 1479 * into a date/time string. 1480 * @return the new start position if matching succeeded; a negative number 1481 * indicating matching failure, otherwise. 1482 */ 1483 int32_t matchString(const UnicodeString& text, int32_t start, UCalendarDateFields field, 1484 const UnicodeString* stringArray, int32_t stringArrayCount, 1485 const UnicodeString* monthPattern, Calendar& cal) const; 1486 1487 /** 1488 * Private code-size reduction function used by subParse. 1489 * @param text the time text being parsed. 1490 * @param start where to start parsing. 1491 * @param field the date field being parsed. 1492 * @param stringArray the string array to parsed. 1493 * @param stringArrayCount the size of the array. 1494 * @param cal a Calendar set to the date and time to be formatted 1495 * into a date/time string. 1496 * @return the new start position if matching succeeded; a negative number 1497 * indicating matching failure, otherwise. 1498 */ 1499 int32_t matchQuarterString(const UnicodeString& text, int32_t start, UCalendarDateFields field, 1500 const UnicodeString* stringArray, int32_t stringArrayCount, Calendar& cal) const; 1501 1502 /** 1503 * Private function used by subParse to match literal pattern text. 1504 * 1505 * @param pattern the pattern string 1506 * @param patternOffset the starting offset into the pattern text. On 1507 * outupt will be set the offset of the first non-literal character in the pattern 1508 * @param text the text being parsed 1509 * @param textOffset the starting offset into the text. On output 1510 * will be set to the offset of the character after the match 1511 * @param lenient <code>TRUE</code> if the parse is lenient, <code>FALSE</code> otherwise. 1512 * 1513 * @return <code>TRUE</code> if the literal text could be matched, <code>FALSE</code> otherwise. 1514 */ 1515 static UBool matchLiterals(const UnicodeString &pattern, int32_t &patternOffset, 1516 const UnicodeString &text, int32_t &textOffset, UBool lenient); 1517 1518 /** 1519 * Private member function that converts the parsed date strings into 1520 * timeFields. Returns -start (for ParsePosition) if failed. 1521 * @param text the time text to be parsed. 1522 * @param start where to start parsing. 1523 * @param ch the pattern character for the date field text to be parsed. 1524 * @param count the count of a pattern character. 1525 * @param obeyCount if true then the count is strictly obeyed. 1526 * @param allowNegative 1527 * @param ambiguousYear If true then the two-digit year == the default start year. 1528 * @param saveHebrewMonth Used to hang onto month until year is known. 1529 * @param cal a Calendar set to the date and time to be formatted 1530 * into a date/time string. 1531 * @param patLoc 1532 * @param numericLeapMonthFormatter If non-null, used to parse numeric leap months. 1533 * @return the new start position if matching succeeded; a negative number 1534 * indicating matching failure, otherwise. 1535 */ 1536 int32_t subParse(const UnicodeString& text, int32_t& start, UChar ch, int32_t count, 1537 UBool obeyCount, UBool allowNegative, UBool ambiguousYear[], int32_t& saveHebrewMonth, Calendar& cal, 1538 int32_t patLoc, MessageFormat * numericLeapMonthFormatter) const; 1539 1540 void parseInt(const UnicodeString& text, 1541 Formattable& number, 1542 ParsePosition& pos, 1543 UBool allowNegative, 1544 NumberFormat *fmt) const; 1545 1546 void parseInt(const UnicodeString& text, 1547 Formattable& number, 1548 int32_t maxDigits, 1549 ParsePosition& pos, 1550 UBool allowNegative, 1551 NumberFormat *fmt) const; 1552 1553 int32_t checkIntSuffix(const UnicodeString& text, int32_t start, 1554 int32_t patLoc, UBool isNegative) const; 1555 1556 /** 1557 * Translate a pattern, mapping each character in the from string to the 1558 * corresponding character in the to string. Return an error if the original 1559 * pattern contains an unmapped character, or if a quote is unmatched. 1560 * Quoted (single quotes only) material is not translated. 1561 * @param originalPattern the original pattern. 1562 * @param translatedPattern Output param to receive the translited pattern. 1563 * @param from the characters to be translited from. 1564 * @param to the characters to be translited to. 1565 * @param status Receives a status code, which will be U_ZERO_ERROR 1566 * if the operation succeeds. 1567 */ 1568 static void translatePattern(const UnicodeString& originalPattern, 1569 UnicodeString& translatedPattern, 1570 const UnicodeString& from, 1571 const UnicodeString& to, 1572 UErrorCode& status); 1573 1574 /** 1575 * Sets the starting date of the 100-year window that dates with 2-digit years 1576 * are considered to fall within. 1577 * @param startDate the start date 1578 * @param status Receives a status code, which will be U_ZERO_ERROR 1579 * if the operation succeeds. 1580 */ 1581 void parseAmbiguousDatesAsAfter(UDate startDate, UErrorCode& status); 1582 1583 /** 1584 * Return the length matched by the given affix, or -1 if none. 1585 * Runs of white space in the affix, match runs of white space in 1586 * the input. 1587 * @param affix pattern string, taken as a literal 1588 * @param input input text 1589 * @param pos offset into input at which to begin matching 1590 * @return length of input that matches, or -1 if match failure 1591 */ 1592 int32_t compareSimpleAffix(const UnicodeString& affix, 1593 const UnicodeString& input, 1594 int32_t pos) const; 1595 1596 /** 1597 * Skip over a run of zero or more Pattern_White_Space characters at 1598 * pos in text. 1599 */ 1600 int32_t skipPatternWhiteSpace(const UnicodeString& text, int32_t pos) const; 1601 1602 /** 1603 * Skip over a run of zero or more isUWhiteSpace() characters at pos 1604 * in text. 1605 */ 1606 int32_t skipUWhiteSpace(const UnicodeString& text, int32_t pos) const; 1607 1608 /** 1609 * Initialize NumberFormat instances used for numbering system overrides. 1610 */ 1611 void initNumberFormatters(const Locale &locale,UErrorCode &status); 1612 1613 /** 1614 * Get the numbering system to be used for a particular field. 1615 */ 1616 NumberFormat * getNumberFormatByIndex(UDateFormatField index) const; 1617 1618 /** 1619 * Parse the given override string and set up structures for number formats 1620 */ 1621 void processOverrideString(const Locale &locale, const UnicodeString &str, int8_t type, UErrorCode &status); 1622 1623 /** 1624 * Used to map pattern characters to Calendar field identifiers. 1625 */ 1626 static const UCalendarDateFields fgPatternIndexToCalendarField[]; 1627 1628 /** 1629 * Map index into pattern character string to DateFormat field number 1630 */ 1631 static const UDateFormatField fgPatternIndexToDateFormatField[]; 1632 1633 /** 1634 * Lazy TimeZoneFormat instantiation, semantically const 1635 */ 1636 TimeZoneFormat *tzFormat() const; 1637 1638 /** 1639 * Used to map Calendar field to field level. 1640 * The larger the level, the smaller the field unit. 1641 * For example, UCAL_ERA level is 0, UCAL_YEAR level is 10, 1642 * UCAL_MONTH level is 20. 1643 */ 1644 static const int32_t fgCalendarFieldToLevel[]; 1645 static const int32_t fgPatternCharToLevel[]; 1646 1647 /** 1648 * The formatting pattern for this formatter. 1649 */ 1650 UnicodeString fPattern; 1651 1652 /** 1653 * The numbering system override for dates. 1654 */ 1655 UnicodeString fDateOverride; 1656 1657 /** 1658 * The numbering system override for times. 1659 */ 1660 UnicodeString fTimeOverride; 1661 1662 1663 /** 1664 * The original locale used (for reloading symbols) 1665 */ 1666 Locale fLocale; 1667 1668 /** 1669 * A pointer to an object containing the strings to use in formatting (e.g., 1670 * month and day names, AM and PM strings, time zone names, etc.) 1671 */ 1672 DateFormatSymbols* fSymbols; // Owned 1673 1674 /** 1675 * The time zone formatter 1676 */ 1677 TimeZoneFormat* fTimeZoneFormat; 1678 1679 /** 1680 * If dates have ambiguous years, we map them into the century starting 1681 * at defaultCenturyStart, which may be any date. If defaultCenturyStart is 1682 * set to SYSTEM_DEFAULT_CENTURY, which it is by default, then the system 1683 * values are used. The instance values defaultCenturyStart and 1684 * defaultCenturyStartYear are only used if explicitly set by the user 1685 * through the API method parseAmbiguousDatesAsAfter(). 1686 */ 1687 UDate fDefaultCenturyStart; 1688 1689 /** 1690 * See documentation for defaultCenturyStart. 1691 */ 1692 /*transient*/ int32_t fDefaultCenturyStartYear; 1693 1694 int32_t tztype; // here to avoid api change 1695 1696 typedef struct NSOverride { 1697 NumberFormat *nf; 1698 int32_t hash; 1699 NSOverride *next; 1700 } NSOverride; 1701 1702 NumberFormat **fNumberFormatters; 1703 1704 NSOverride *fOverrideList; 1705 1706 UBool fHaveDefaultCentury; 1707 1708 UDisplayContext fCapitalizationContext; 1709}; 1710 1711inline UDate 1712SimpleDateFormat::get2DigitYearStart(UErrorCode& /*status*/) const 1713{ 1714 return fDefaultCenturyStart; 1715} 1716 1717inline UnicodeString& 1718SimpleDateFormat::format(const Formattable& obj, 1719 UnicodeString& appendTo, 1720 UErrorCode& status) const { 1721 // Don't use Format:: - use immediate base class only, 1722 // in case immediate base modifies behavior later. 1723 return DateFormat::format(obj, appendTo, status); 1724} 1725 1726inline UnicodeString& 1727SimpleDateFormat::format(const Formattable& obj, 1728 UnicodeString& appendTo, 1729 FieldPosition& pos, 1730 UErrorCode& status) const 1731{ 1732 // Don't use Format:: - use immediate base class only, 1733 // in case immediate base modifies behavior later. 1734 return DateFormat::format(obj, appendTo, pos, status); 1735} 1736 1737inline UnicodeString& 1738SimpleDateFormat::format(const Formattable& obj, 1739 UnicodeString& appendTo, 1740 FieldPositionIterator* posIter, 1741 UErrorCode& status) const 1742{ 1743 // Don't use Format:: - use immediate base class only, 1744 // in case immediate base modifies behavior later. 1745 return DateFormat::format(obj, appendTo, posIter, status); 1746} 1747 1748inline UnicodeString& 1749SimpleDateFormat::format(UDate date, 1750 UnicodeString& appendTo, 1751 FieldPosition& fieldPosition) const { 1752 // Don't use Format:: - use immediate base class only, 1753 // in case immediate base modifies behavior later. 1754 return DateFormat::format(date, appendTo, fieldPosition); 1755} 1756 1757inline UnicodeString& 1758SimpleDateFormat::format(UDate date, 1759 UnicodeString& appendTo, 1760 FieldPositionIterator* posIter, 1761 UErrorCode& status) const { 1762 // Don't use Format:: - use immediate base class only, 1763 // in case immediate base modifies behavior later. 1764 return DateFormat::format(date, appendTo, posIter, status); 1765} 1766 1767inline UnicodeString& 1768SimpleDateFormat::format(UDate date, UnicodeString& appendTo) const { 1769 return DateFormat::format(date, appendTo); 1770} 1771 1772U_NAMESPACE_END 1773 1774#endif /* #if !UCONFIG_NO_FORMATTING */ 1775 1776#endif // _SMPDTFMT 1777//eof 1778