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