EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-01-18 10:13:08
0001 // © 2016 and later: Unicode, Inc. and others. 0002 // License & terms of use: http://www.unicode.org/copyright.html 0003 /* 0004 * Copyright (C) 1997-2016, International Business Machines Corporation and 0005 * others. All Rights Reserved. 0006 ******************************************************************************* 0007 * 0008 * File SMPDTFMT.H 0009 * 0010 * Modification History: 0011 * 0012 * Date Name Description 0013 * 02/19/97 aliu Converted from java. 0014 * 07/09/97 helena Make ParsePosition into a class. 0015 * 07/21/98 stephen Added GMT_PLUS, GMT_MINUS 0016 * Changed setTwoDigitStartDate to set2DigitYearStart 0017 * Changed getTwoDigitStartDate to get2DigitYearStart 0018 * Removed subParseLong 0019 * Removed getZoneIndex (added in DateFormatSymbols) 0020 * 06/14/99 stephen Removed fgTimeZoneDataSuffix 0021 * 10/14/99 aliu Updated class doc to describe 2-digit year parsing 0022 * {j28 4182066}. 0023 ******************************************************************************* 0024 */ 0025 0026 #ifndef SMPDTFMT_H 0027 #define SMPDTFMT_H 0028 0029 #include "unicode/utypes.h" 0030 0031 #if U_SHOW_CPLUSPLUS_API 0032 0033 /** 0034 * \file 0035 * \brief C++ API: Format and parse dates in a language-independent manner. 0036 */ 0037 0038 #if !UCONFIG_NO_FORMATTING 0039 0040 #include "unicode/datefmt.h" 0041 #include "unicode/udisplaycontext.h" 0042 #include "unicode/tzfmt.h" /* for UTimeZoneFormatTimeType */ 0043 #include "unicode/brkiter.h" 0044 0045 U_NAMESPACE_BEGIN 0046 0047 class DateFormatSymbols; 0048 class DateFormat; 0049 class MessageFormat; 0050 class FieldPositionHandler; 0051 class TimeZoneFormat; 0052 class SharedNumberFormat; 0053 class SimpleDateFormatMutableNFs; 0054 class DateIntervalFormat; 0055 0056 namespace number { 0057 class LocalizedNumberFormatter; 0058 class SimpleNumberFormatter; 0059 } 0060 0061 /** 0062 * 0063 * SimpleDateFormat is a concrete class for formatting and parsing dates in a 0064 * language-independent manner. It allows for formatting (millis -> text), 0065 * parsing (text -> millis), and normalization. Formats/Parses a date or time, 0066 * which is the standard milliseconds since 24:00 GMT, Jan 1, 1970. 0067 * <P> 0068 * Clients are encouraged to create a date-time formatter using DateFormat::getInstance(), 0069 * getDateInstance(), getDateInstance(), or getDateTimeInstance() rather than 0070 * explicitly constructing an instance of SimpleDateFormat. This way, the client 0071 * is guaranteed to get an appropriate formatting pattern for whatever locale the 0072 * program is running in. However, if the client needs something more unusual than 0073 * the default patterns in the locales, he can construct a SimpleDateFormat directly 0074 * and give it an appropriate pattern (or use one of the factory methods on DateFormat 0075 * and modify the pattern after the fact with toPattern() and applyPattern(). 0076 * 0077 * <p><strong>Date and Time Patterns:</strong></p> 0078 * 0079 * <p>Date and time formats are specified by <em>date and time pattern</em> strings. 0080 * Within date and time pattern strings, all unquoted ASCII letters [A-Za-z] are reserved 0081 * as pattern letters representing calendar fields. <code>SimpleDateFormat</code> supports 0082 * the date and time formatting algorithm and pattern letters defined by 0083 * <a href="http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table">UTS#35 0084 * Unicode Locale Data Markup Language (LDML)</a> and further documented for ICU in the 0085 * <a href="https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table">ICU 0086 * User Guide</a>. The following pattern letters are currently available (note that the actual 0087 * values depend on CLDR and may change from the examples shown here):</p> 0088 * 0089 * <table border="1"> 0090 * <tr> 0091 * <th>Field</th> 0092 * <th style="text-align: center">Sym.</th> 0093 * <th style="text-align: center">No.</th> 0094 * <th>Example</th> 0095 * <th>Description</th> 0096 * </tr> 0097 * <tr> 0098 * <th rowspan="3">era</th> 0099 * <td style="text-align: center" rowspan="3">G</td> 0100 * <td style="text-align: center">1..3</td> 0101 * <td>AD</td> 0102 * <td rowspan="3">Era - Replaced with the Era string for the current date. One to three letters for the 0103 * abbreviated form, four letters for the long (wide) form, five for the narrow form.</td> 0104 * </tr> 0105 * <tr> 0106 * <td style="text-align: center">4</td> 0107 * <td>Anno Domini</td> 0108 * </tr> 0109 * <tr> 0110 * <td style="text-align: center">5</td> 0111 * <td>A</td> 0112 * </tr> 0113 * <tr> 0114 * <th rowspan="6">year</th> 0115 * <td style="text-align: center">y</td> 0116 * <td style="text-align: center">1..n</td> 0117 * <td>1996</td> 0118 * <td>Year. Normally the length specifies the padding, but for two letters it also specifies the maximum 0119 * length. Example:<div align="center"> 0120 * <center> 0121 * <table border="1" cellpadding="2" cellspacing="0"> 0122 * <tr> 0123 * <th>Year</th> 0124 * <th style="text-align: right">y</th> 0125 * <th style="text-align: right">yy</th> 0126 * <th style="text-align: right">yyy</th> 0127 * <th style="text-align: right">yyyy</th> 0128 * <th style="text-align: right">yyyyy</th> 0129 * </tr> 0130 * <tr> 0131 * <td>AD 1</td> 0132 * <td style="text-align: right">1</td> 0133 * <td style="text-align: right">01</td> 0134 * <td style="text-align: right">001</td> 0135 * <td style="text-align: right">0001</td> 0136 * <td style="text-align: right">00001</td> 0137 * </tr> 0138 * <tr> 0139 * <td>AD 12</td> 0140 * <td style="text-align: right">12</td> 0141 * <td style="text-align: right">12</td> 0142 * <td style="text-align: right">012</td> 0143 * <td style="text-align: right">0012</td> 0144 * <td style="text-align: right">00012</td> 0145 * </tr> 0146 * <tr> 0147 * <td>AD 123</td> 0148 * <td style="text-align: right">123</td> 0149 * <td style="text-align: right">23</td> 0150 * <td style="text-align: right">123</td> 0151 * <td style="text-align: right">0123</td> 0152 * <td style="text-align: right">00123</td> 0153 * </tr> 0154 * <tr> 0155 * <td>AD 1234</td> 0156 * <td style="text-align: right">1234</td> 0157 * <td style="text-align: right">34</td> 0158 * <td style="text-align: right">1234</td> 0159 * <td style="text-align: right">1234</td> 0160 * <td style="text-align: right">01234</td> 0161 * </tr> 0162 * <tr> 0163 * <td>AD 12345</td> 0164 * <td style="text-align: right">12345</td> 0165 * <td style="text-align: right">45</td> 0166 * <td style="text-align: right">12345</td> 0167 * <td style="text-align: right">12345</td> 0168 * <td style="text-align: right">12345</td> 0169 * </tr> 0170 * </table> 0171 * </center></div> 0172 * </td> 0173 * </tr> 0174 * <tr> 0175 * <td style="text-align: center">Y</td> 0176 * <td style="text-align: center">1..n</td> 0177 * <td>1997</td> 0178 * <td>Year (in "Week of Year" based calendars). Normally the length specifies the padding, 0179 * but for two letters it also specifies the maximum length. This year designation is used in ISO 0180 * year-week calendar as defined by ISO 8601, but can be used in non-Gregorian based calendar systems 0181 * where week date processing is desired. May not always be the same value as calendar year.</td> 0182 * </tr> 0183 * <tr> 0184 * <td style="text-align: center">u</td> 0185 * <td style="text-align: center">1..n</td> 0186 * <td>4601</td> 0187 * <td>Extended year. This is a single number designating the year of this calendar system, encompassing 0188 * all supra-year fields. For example, for the Julian calendar system, year numbers are positive, with an 0189 * era of BCE or CE. An extended year value for the Julian calendar system assigns positive values to CE 0190 * years and negative values to BCE years, with 1 BCE being year 0.</td> 0191 * </tr> 0192 * <tr> 0193 * <td style="text-align: center" rowspan="3">U</td> 0194 * <td style="text-align: center">1..3</td> 0195 * <td>甲子</td> 0196 * <td rowspan="3">Cyclic year name. Calendars such as the Chinese lunar calendar (and related calendars) 0197 * and the Hindu calendars use 60-year cycles of year names. Use one through three letters for the abbreviated 0198 * name, four for the full (wide) name, or five for the narrow name (currently the data only provides abbreviated names, 0199 * which will be used for all requested name widths). If the calendar does not provide cyclic year name data, 0200 * or if the year value to be formatted is out of the range of years for which cyclic name data is provided, 0201 * then numeric formatting is used (behaves like 'y').</td> 0202 * </tr> 0203 * <tr> 0204 * <td style="text-align: center">4</td> 0205 * <td>(currently also 甲子)</td> 0206 * </tr> 0207 * <tr> 0208 * <td style="text-align: center">5</td> 0209 * <td>(currently also 甲子)</td> 0210 * </tr> 0211 * <tr> 0212 * <th rowspan="6">quarter</th> 0213 * <td rowspan="3" style="text-align: center">Q</td> 0214 * <td style="text-align: center">1..2</td> 0215 * <td>02</td> 0216 * <td rowspan="3">Quarter - Use one or two for the numerical quarter, three for the abbreviation, or four for the 0217 * full (wide) name (five for the narrow name is not yet supported).</td> 0218 * </tr> 0219 * <tr> 0220 * <td style="text-align: center">3</td> 0221 * <td>Q2</td> 0222 * </tr> 0223 * <tr> 0224 * <td style="text-align: center">4</td> 0225 * <td>2nd quarter</td> 0226 * </tr> 0227 * <tr> 0228 * <td rowspan="3" style="text-align: center">q</td> 0229 * <td style="text-align: center">1..2</td> 0230 * <td>02</td> 0231 * <td rowspan="3"><b>Stand-Alone</b> Quarter - Use one or two for the numerical quarter, three for the abbreviation, 0232 * or four for the full name (five for the narrow name is not yet supported).</td> 0233 * </tr> 0234 * <tr> 0235 * <td style="text-align: center">3</td> 0236 * <td>Q2</td> 0237 * </tr> 0238 * <tr> 0239 * <td style="text-align: center">4</td> 0240 * <td>2nd quarter</td> 0241 * </tr> 0242 * <tr> 0243 * <th rowspan="8">month</th> 0244 * <td rowspan="4" style="text-align: center">M</td> 0245 * <td style="text-align: center">1..2</td> 0246 * <td>09</td> 0247 * <td rowspan="4">Month - Use one or two for the numerical month, three for the abbreviation, four for 0248 * the full (wide) name, or five for the narrow name. With two ("MM"), the month number is zero-padded 0249 * if necessary (e.g. "08")</td> 0250 * </tr> 0251 * <tr> 0252 * <td style="text-align: center">3</td> 0253 * <td>Sep</td> 0254 * </tr> 0255 * <tr> 0256 * <td style="text-align: center">4</td> 0257 * <td>September</td> 0258 * </tr> 0259 * <tr> 0260 * <td style="text-align: center">5</td> 0261 * <td>S</td> 0262 * </tr> 0263 * <tr> 0264 * <td rowspan="4" style="text-align: center">L</td> 0265 * <td style="text-align: center">1..2</td> 0266 * <td>09</td> 0267 * <td rowspan="4"><b>Stand-Alone</b> Month - Use one or two for the numerical month, three for the abbreviation, 0268 * four for the full (wide) name, or 5 for the narrow name. With two ("LL"), the month number is zero-padded if 0269 * necessary (e.g. "08")</td> 0270 * </tr> 0271 * <tr> 0272 * <td style="text-align: center">3</td> 0273 * <td>Sep</td> 0274 * </tr> 0275 * <tr> 0276 * <td style="text-align: center">4</td> 0277 * <td>September</td> 0278 * </tr> 0279 * <tr> 0280 * <td style="text-align: center">5</td> 0281 * <td>S</td> 0282 * </tr> 0283 * <tr> 0284 * <th rowspan="2">week</th> 0285 * <td style="text-align: center">w</td> 0286 * <td style="text-align: center">1..2</td> 0287 * <td>27</td> 0288 * <td>Week of Year. Use "w" to show the minimum number of digits, or "ww" to always show two digits 0289 * (zero-padding if necessary, e.g. "08").</td> 0290 * </tr> 0291 * <tr> 0292 * <td style="text-align: center">W</td> 0293 * <td style="text-align: center">1</td> 0294 * <td>3</td> 0295 * <td>Week of Month</td> 0296 * </tr> 0297 * <tr> 0298 * <th rowspan="4">day</th> 0299 * <td style="text-align: center">d</td> 0300 * <td style="text-align: center">1..2</td> 0301 * <td>1</td> 0302 * <td>Date - Day of the month. Use "d" to show the minimum number of digits, or "dd" to always show 0303 * two digits (zero-padding if necessary, e.g. "08").</td> 0304 * </tr> 0305 * <tr> 0306 * <td style="text-align: center">D</td> 0307 * <td style="text-align: center">1..3</td> 0308 * <td>345</td> 0309 * <td>Day of year</td> 0310 * </tr> 0311 * <tr> 0312 * <td style="text-align: center">F</td> 0313 * <td style="text-align: center">1</td> 0314 * <td>2</td> 0315 * <td>Day of Week in Month. The example is for the 2nd Wed in July</td> 0316 * </tr> 0317 * <tr> 0318 * <td style="text-align: center">g</td> 0319 * <td style="text-align: center">1..n</td> 0320 * <td>2451334</td> 0321 * <td>Modified Julian day. This is different from the conventional Julian day number in two regards. 0322 * First, it demarcates days at local zone midnight, rather than noon GMT. Second, it is a local number; 0323 * that is, it depends on the local time zone. It can be thought of as a single number that encompasses 0324 * all the date-related fields.</td> 0325 * </tr> 0326 * <tr> 0327 * <th rowspan="14">week<br> 0328 * day</th> 0329 * <td rowspan="4" style="text-align: center">E</td> 0330 * <td style="text-align: center">1..3</td> 0331 * <td>Tue</td> 0332 * <td rowspan="4">Day of week - Use one through three letters for the short day, four for the full (wide) name, 0333 * five for the narrow name, or six for the short name.</td> 0334 * </tr> 0335 * <tr> 0336 * <td style="text-align: center">4</td> 0337 * <td>Tuesday</td> 0338 * </tr> 0339 * <tr> 0340 * <td style="text-align: center">5</td> 0341 * <td>T</td> 0342 * </tr> 0343 * <tr> 0344 * <td style="text-align: center">6</td> 0345 * <td>Tu</td> 0346 * </tr> 0347 * <tr> 0348 * <td rowspan="5" style="text-align: center">e</td> 0349 * <td style="text-align: center">1..2</td> 0350 * <td>2</td> 0351 * <td rowspan="5">Local day of week. Same as E except adds a numeric value that will depend on the local 0352 * starting day of the week, using one or two letters. For this example, Monday is the first day of the week.</td> 0353 * </tr> 0354 * <tr> 0355 * <td style="text-align: center">3</td> 0356 * <td>Tue</td> 0357 * </tr> 0358 * <tr> 0359 * <td style="text-align: center">4</td> 0360 * <td>Tuesday</td> 0361 * </tr> 0362 * <tr> 0363 * <td style="text-align: center">5</td> 0364 * <td>T</td> 0365 * </tr> 0366 * <tr> 0367 * <td style="text-align: center">6</td> 0368 * <td>Tu</td> 0369 * </tr> 0370 * <tr> 0371 * <td rowspan="5" style="text-align: center">c</td> 0372 * <td style="text-align: center">1</td> 0373 * <td>2</td> 0374 * <td rowspan="5"><b>Stand-Alone</b> local day of week - Use one letter for the local numeric value (same 0375 * as 'e'), three for the short day, four for the full (wide) name, five for the narrow name, or six for 0376 * the short name.</td> 0377 * </tr> 0378 * <tr> 0379 * <td style="text-align: center">3</td> 0380 * <td>Tue</td> 0381 * </tr> 0382 * <tr> 0383 * <td style="text-align: center">4</td> 0384 * <td>Tuesday</td> 0385 * </tr> 0386 * <tr> 0387 * <td style="text-align: center">5</td> 0388 * <td>T</td> 0389 * </tr> 0390 * <tr> 0391 * <td style="text-align: center">6</td> 0392 * <td>Tu</td> 0393 * </tr> 0394 * <tr> 0395 * <th>period</th> 0396 * <td style="text-align: center">a</td> 0397 * <td style="text-align: center">1</td> 0398 * <td>AM</td> 0399 * <td>AM or PM</td> 0400 * </tr> 0401 * <tr> 0402 * <th rowspan="4">hour</th> 0403 * <td style="text-align: center">h</td> 0404 * <td style="text-align: center">1..2</td> 0405 * <td>11</td> 0406 * <td>Hour [1-12]. When used in skeleton data or in a skeleton passed in an API for flexible data pattern 0407 * generation, it should match the 12-hour-cycle format preferred by the locale (h or K); it should not match 0408 * a 24-hour-cycle format (H or k). Use hh for zero padding.</td> 0409 * </tr> 0410 * <tr> 0411 * <td style="text-align: center">H</td> 0412 * <td style="text-align: center">1..2</td> 0413 * <td>13</td> 0414 * <td>Hour [0-23]. When used in skeleton data or in a skeleton passed in an API for flexible data pattern 0415 * generation, it should match the 24-hour-cycle format preferred by the locale (H or k); it should not match a 0416 * 12-hour-cycle format (h or K). Use HH for zero padding.</td> 0417 * </tr> 0418 * <tr> 0419 * <td style="text-align: center">K</td> 0420 * <td style="text-align: center">1..2</td> 0421 * <td>0</td> 0422 * <td>Hour [0-11]. When used in a skeleton, only matches K or h, see above. Use KK for zero padding.</td> 0423 * </tr> 0424 * <tr> 0425 * <td style="text-align: center">k</td> 0426 * <td style="text-align: center">1..2</td> 0427 * <td>24</td> 0428 * <td>Hour [1-24]. When used in a skeleton, only matches k or H, see above. Use kk for zero padding.</td> 0429 * </tr> 0430 * <tr> 0431 * <th>minute</th> 0432 * <td style="text-align: center">m</td> 0433 * <td style="text-align: center">1..2</td> 0434 * <td>59</td> 0435 * <td>Minute. Use "m" to show the minimum number of digits, or "mm" to always show two digits 0436 * (zero-padding if necessary, e.g. "08").</td> 0437 * </tr> 0438 * <tr> 0439 * <th rowspan="3">second</th> 0440 * <td style="text-align: center">s</td> 0441 * <td style="text-align: center">1..2</td> 0442 * <td>12</td> 0443 * <td>Second. Use "s" to show the minimum number of digits, or "ss" to always show two digits 0444 * (zero-padding if necessary, e.g. "08").</td> 0445 * </tr> 0446 * <tr> 0447 * <td style="text-align: center">S</td> 0448 * <td style="text-align: center">1..n</td> 0449 * <td>3450</td> 0450 * <td>Fractional Second - truncates (like other time fields) to the count of letters when formatting. 0451 * Appends zeros if more than 3 letters specified. Truncates at three significant digits when parsing. 0452 * (example shows display using pattern SSSS for seconds value 12.34567)</td> 0453 * </tr> 0454 * <tr> 0455 * <td style="text-align: center">A</td> 0456 * <td style="text-align: center">1..n</td> 0457 * <td>69540000</td> 0458 * <td>Milliseconds in day. This field behaves <i>exactly</i> like a composite of all time-related fields, 0459 * not including the zone fields. As such, it also reflects discontinuities of those fields on DST transition 0460 * days. On a day of DST onset, it will jump forward. On a day of DST cessation, it will jump backward. This 0461 * reflects the fact that is must be combined with the offset field to obtain a unique local time value.</td> 0462 * </tr> 0463 * <tr> 0464 * <th rowspan="23">zone</th> 0465 * <td rowspan="2" style="text-align: center">z</td> 0466 * <td style="text-align: center">1..3</td> 0467 * <td>PDT</td> 0468 * <td>The <i>short specific non-location format</i>. 0469 * Where that is unavailable, falls back to the <i>short localized GMT format</i> ("O").</td> 0470 * </tr> 0471 * <tr> 0472 * <td style="text-align: center">4</td> 0473 * <td>Pacific Daylight Time</td> 0474 * <td>The <i>long specific non-location format</i>. 0475 * Where that is unavailable, falls back to the <i>long localized GMT format</i> ("OOOO").</td> 0476 * </tr> 0477 * <tr> 0478 * <td rowspan="3" style="text-align: center">Z</td> 0479 * <td style="text-align: center">1..3</td> 0480 * <td>-0800</td> 0481 * <td>The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 0482 * The format is equivalent to RFC 822 zone format (when optional seconds field is absent). 0483 * This is equivalent to the "xxxx" specifier.</td> 0484 * </tr> 0485 * <tr> 0486 * <td style="text-align: center">4</td> 0487 * <td>GMT-8:00</td> 0488 * <td>The <i>long localized GMT format</i>. 0489 * This is equivalent to the "OOOO" specifier.</td> 0490 * </tr> 0491 * <tr> 0492 * <td style="text-align: center">5</td> 0493 * <td>-08:00<br> 0494 * -07:52:58</td> 0495 * <td>The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 0496 * The ISO8601 UTC indicator "Z" is used when local time offset is 0. 0497 * This is equivalent to the "XXXXX" specifier.</td> 0498 * </tr> 0499 * <tr> 0500 * <td rowspan="2" style="text-align: center">O</td> 0501 * <td style="text-align: center">1</td> 0502 * <td>GMT-8</td> 0503 * <td>The <i>short localized GMT format</i>.</td> 0504 * </tr> 0505 * <tr> 0506 * <td style="text-align: center">4</td> 0507 * <td>GMT-08:00</td> 0508 * <td>The <i>long localized GMT format</i>.</td> 0509 * </tr> 0510 * <tr> 0511 * <td rowspan="2" style="text-align: center">v</td> 0512 * <td style="text-align: center">1</td> 0513 * <td>PT</td> 0514 * <td>The <i>short generic non-location format</i>. 0515 * Where that is unavailable, falls back to the <i>generic location format</i> ("VVVV"), 0516 * then the <i>short localized GMT format</i> as the final fallback.</td> 0517 * </tr> 0518 * <tr> 0519 * <td style="text-align: center">4</td> 0520 * <td>Pacific Time</td> 0521 * <td>The <i>long generic non-location format</i>. 0522 * Where that is unavailable, falls back to <i>generic location format</i> ("VVVV"). 0523 * </tr> 0524 * <tr> 0525 * <td rowspan="4" style="text-align: center">V</td> 0526 * <td style="text-align: center">1</td> 0527 * <td>uslax</td> 0528 * <td>The short time zone ID. 0529 * Where that is unavailable, the special short time zone ID <i>unk</i> (Unknown Zone) is used.<br> 0530 * <i><b>Note</b>: This specifier was originally used for a variant of the short specific non-location format, 0531 * but it was deprecated in the later version of the LDML specification. In CLDR 23/ICU 51, the definition of 0532 * the specifier was changed to designate a short time zone ID.</i></td> 0533 * </tr> 0534 * <tr> 0535 * <td style="text-align: center">2</td> 0536 * <td>America/Los_Angeles</td> 0537 * <td>The long time zone ID.</td> 0538 * </tr> 0539 * <tr> 0540 * <td style="text-align: center">3</td> 0541 * <td>Los Angeles</td> 0542 * <td>The exemplar city (location) for the time zone. 0543 * Where that is unavailable, the localized exemplar city name for the special zone <i>Etc/Unknown</i> is used 0544 * as the fallback (for example, "Unknown City"). </td> 0545 * </tr> 0546 * <tr> 0547 * <td style="text-align: center">4</td> 0548 * <td>Los Angeles Time</td> 0549 * <td>The <i>generic location format</i>. 0550 * Where that is unavailable, falls back to the <i>long localized GMT format</i> ("OOOO"; 0551 * Note: Fallback is only necessary with a GMT-style Time Zone ID, like Etc/GMT-830.)<br> 0552 * This is especially useful when presenting possible timezone choices for user selection, 0553 * since the naming is more uniform than the "v" format.</td> 0554 * </tr> 0555 * <tr> 0556 * <td rowspan="5" style="text-align: center">X</td> 0557 * <td style="text-align: center">1</td> 0558 * <td>-08<br> 0559 * +0530<br> 0560 * Z</td> 0561 * <td>The <i>ISO8601 basic format</i> with hours field and optional minutes field. 0562 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 0563 * </tr> 0564 * <tr> 0565 * <td style="text-align: center">2</td> 0566 * <td>-0800<br> 0567 * Z</td> 0568 * <td>The <i>ISO8601 basic format</i> with hours and minutes fields. 0569 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 0570 * </tr> 0571 * <tr> 0572 * <td style="text-align: center">3</td> 0573 * <td>-08:00<br> 0574 * Z</td> 0575 * <td>The <i>ISO8601 extended format</i> with hours and minutes fields. 0576 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 0577 * </tr> 0578 * <tr> 0579 * <td style="text-align: center">4</td> 0580 * <td>-0800<br> 0581 * -075258<br> 0582 * Z</td> 0583 * <td>The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 0584 * (Note: The seconds field is not supported by the ISO8601 specification.) 0585 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 0586 * </tr> 0587 * <tr> 0588 * <td style="text-align: center">5</td> 0589 * <td>-08:00<br> 0590 * -07:52:58<br> 0591 * Z</td> 0592 * <td>The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 0593 * (Note: The seconds field is not supported by the ISO8601 specification.) 0594 * The ISO8601 UTC indicator "Z" is used when local time offset is 0.</td> 0595 * </tr> 0596 * <tr> 0597 * <td rowspan="5" style="text-align: center">x</td> 0598 * <td style="text-align: center">1</td> 0599 * <td>-08<br> 0600 * +0530</td> 0601 * <td>The <i>ISO8601 basic format</i> with hours field and optional minutes field.</td> 0602 * </tr> 0603 * <tr> 0604 * <td style="text-align: center">2</td> 0605 * <td>-0800</td> 0606 * <td>The <i>ISO8601 basic format</i> with hours and minutes fields.</td> 0607 * </tr> 0608 * <tr> 0609 * <td style="text-align: center">3</td> 0610 * <td>-08:00</td> 0611 * <td>The <i>ISO8601 extended format</i> with hours and minutes fields.</td> 0612 * </tr> 0613 * <tr> 0614 * <td style="text-align: center">4</td> 0615 * <td>-0800<br> 0616 * -075258</td> 0617 * <td>The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 0618 * (Note: The seconds field is not supported by the ISO8601 specification.)</td> 0619 * </tr> 0620 * <tr> 0621 * <td style="text-align: center">5</td> 0622 * <td>-08:00<br> 0623 * -07:52:58</td> 0624 * <td>The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 0625 * (Note: The seconds field is not supported by the ISO8601 specification.)</td> 0626 * </tr> 0627 * </table> 0628 * 0629 * <P> 0630 * Any characters in the pattern that are not in the ranges of ['a'..'z'] and 0631 * ['A'..'Z'] will be treated as quoted text. For instance, characters 0632 * like ':', '.', ' ', '#' and '@' will appear in the resulting time text 0633 * even they are not embraced within single quotes. 0634 * <P> 0635 * A pattern containing any invalid pattern letter will result in a failing 0636 * UErrorCode result during formatting or parsing. 0637 * <P> 0638 * Examples using the US locale: 0639 * <pre> 0640 * \code 0641 * Format Pattern Result 0642 * -------------- ------- 0643 * "yyyy.MM.dd G 'at' HH:mm:ss vvvv" ->> 1996.07.10 AD at 15:08:56 Pacific Time 0644 * "EEE, MMM d, ''yy" ->> Wed, July 10, '96 0645 * "h:mm a" ->> 12:08 PM 0646 * "hh 'o''clock' a, zzzz" ->> 12 o'clock PM, Pacific Daylight Time 0647 * "K:mm a, vvv" ->> 0:00 PM, PT 0648 * "yyyyy.MMMMM.dd GGG hh:mm aaa" ->> 1996.July.10 AD 12:08 PM 0649 * \endcode 0650 * </pre> 0651 * Code Sample: 0652 * <pre> 0653 * \code 0654 * UErrorCode success = U_ZERO_ERROR; 0655 * SimpleTimeZone* pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST"); 0656 * pdt->setStartRule( Calendar::APRIL, 1, Calendar::SUNDAY, 2*60*60*1000); 0657 * pdt->setEndRule( Calendar::OCTOBER, -1, Calendar::SUNDAY, 2*60*60*1000); 0658 * 0659 * // Format the current time. 0660 * SimpleDateFormat* formatter 0661 * = new SimpleDateFormat ("yyyy.MM.dd G 'at' hh:mm:ss a zzz", success ); 0662 * GregorianCalendar cal(success); 0663 * UDate currentTime_1 = cal.getTime(success); 0664 * FieldPosition fp(FieldPosition::DONT_CARE); 0665 * UnicodeString dateString; 0666 * formatter->format( currentTime_1, dateString, fp ); 0667 * cout << "result: " << dateString << endl; 0668 * 0669 * // Parse the previous string back into a Date. 0670 * ParsePosition pp(0); 0671 * UDate currentTime_2 = formatter->parse(dateString, pp ); 0672 * \endcode 0673 * </pre> 0674 * In the above example, the time value "currentTime_2" obtained from parsing 0675 * will be equal to currentTime_1. However, they may not be equal if the am/pm 0676 * marker 'a' is left out from the format pattern while the "hour in am/pm" 0677 * pattern symbol is used. This information loss can happen when formatting the 0678 * time in PM. 0679 * 0680 * <p> 0681 * When parsing a date string using the abbreviated year pattern ("y" or "yy"), 0682 * SimpleDateFormat must interpret the abbreviated year 0683 * relative to some century. It does this by adjusting dates to be 0684 * within 80 years before and 20 years after the time the SimpleDateFormat 0685 * instance is created. For example, using a pattern of "MM/dd/yy" and a 0686 * SimpleDateFormat instance created on Jan 1, 1997, the string 0687 * "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" 0688 * would be interpreted as May 4, 1964. 0689 * During parsing, only strings consisting of exactly two digits, as defined by 0690 * <code>Unicode::isDigit()</code>, will be parsed into the default century. 0691 * Any other numeric string, such as a one digit string, a three or more digit 0692 * string, or a two digit string that isn't all digits (for example, "-1"), is 0693 * interpreted literally. So "01/02/3" or "01/02/003" are parsed (for the 0694 * Gregorian calendar), using the same pattern, as Jan 2, 3 AD. Likewise (but 0695 * only in lenient parse mode, the default) "01/02/-3" is parsed as Jan 2, 4 BC. 0696 * 0697 * <p> 0698 * If the year pattern has more than two 'y' characters, the year is 0699 * interpreted literally, regardless of the number of digits. So using the 0700 * pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D. 0701 * 0702 * <p> 0703 * When numeric fields abut one another directly, with no intervening delimiter 0704 * characters, they constitute a run of abutting numeric fields. Such runs are 0705 * parsed specially. For example, the format "HHmmss" parses the input text 0706 * "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to 0707 * parse "1234". In other words, the leftmost field of the run is flexible, 0708 * while the others keep a fixed width. If the parse fails anywhere in the run, 0709 * then the leftmost field is shortened by one character, and the entire run is 0710 * parsed again. This is repeated until either the parse succeeds or the 0711 * leftmost field is one character in length. If the parse still fails at that 0712 * point, the parse of the run fails. 0713 * 0714 * <P> 0715 * For time zones that have no names, SimpleDateFormat uses strings GMT+hours:minutes or 0716 * GMT-hours:minutes. 0717 * <P> 0718 * The calendar defines what is the first day of the week, the first week of the 0719 * year, whether hours are zero based or not (0 vs 12 or 24), and the timezone. 0720 * There is one common number format to handle all the numbers; the digit count 0721 * is handled programmatically according to the pattern. 0722 * 0723 * <p><em>User subclasses are not supported.</em> While clients may write 0724 * subclasses, such code will not necessarily work and will not be 0725 * guaranteed to work stably from release to release. 0726 */ 0727 class U_I18N_API SimpleDateFormat: public DateFormat { 0728 public: 0729 /** 0730 * Construct a SimpleDateFormat using the default pattern for the default 0731 * locale. 0732 * <P> 0733 * [Note:] Not all locales support SimpleDateFormat; for full generality, 0734 * use the factory methods in the DateFormat class. 0735 * @param status Output param set to success/failure code. 0736 * @stable ICU 2.0 0737 */ 0738 SimpleDateFormat(UErrorCode& status); 0739 0740 /** 0741 * Construct a SimpleDateFormat using the given pattern and the default locale. 0742 * The locale is used to obtain the symbols used in formatting (e.g., the 0743 * names of the months), but not to provide the pattern. 0744 * <P> 0745 * [Note:] Not all locales support SimpleDateFormat; for full generality, 0746 * use the factory methods in the DateFormat class. 0747 * @param pattern the pattern for the format. 0748 * @param status Output param set to success/failure code. 0749 * @stable ICU 2.0 0750 */ 0751 SimpleDateFormat(const UnicodeString& pattern, 0752 UErrorCode& status); 0753 0754 /** 0755 * Construct a SimpleDateFormat using the given pattern, numbering system override, and the default locale. 0756 * The locale is used to obtain the symbols used in formatting (e.g., the 0757 * names of the months), but not to provide the pattern. 0758 * <P> 0759 * A numbering system override is a string containing either the name of a known numbering system, 0760 * or a set of field and numbering system pairs that specify which fields are to be formatted with 0761 * the alternate numbering system. For example, to specify that all numeric fields in the specified 0762 * date or time pattern are to be rendered using Thai digits, simply specify the numbering system override 0763 * as "thai". To specify that just the year portion of the date be formatted using Hebrew numbering, 0764 * use the override string "y=hebrew". Numbering system overrides can be combined using a semi-colon 0765 * character in the override string, such as "d=decimal;M=arabic;y=hebrew", etc. 0766 * 0767 * <P> 0768 * [Note:] Not all locales support SimpleDateFormat; for full generality, 0769 * use the factory methods in the DateFormat class. 0770 * @param pattern the pattern for the format. 0771 * @param override the override string. 0772 * @param status Output param set to success/failure code. 0773 * @stable ICU 4.2 0774 */ 0775 SimpleDateFormat(const UnicodeString& pattern, 0776 const UnicodeString& override, 0777 UErrorCode& status); 0778 0779 /** 0780 * Construct a SimpleDateFormat using the given pattern and locale. 0781 * The locale is used to obtain the symbols used in formatting (e.g., the 0782 * names of the months), but not to provide the pattern. 0783 * <P> 0784 * [Note:] Not all locales support SimpleDateFormat; for full generality, 0785 * use the factory methods in the DateFormat class. 0786 * @param pattern the pattern for the format. 0787 * @param locale the given locale. 0788 * @param status Output param set to success/failure code. 0789 * @stable ICU 2.0 0790 */ 0791 SimpleDateFormat(const UnicodeString& pattern, 0792 const Locale& locale, 0793 UErrorCode& status); 0794 0795 /** 0796 * Construct a SimpleDateFormat using the given pattern, numbering system override, and locale. 0797 * The locale is used to obtain the symbols used in formatting (e.g., the 0798 * names of the months), but not to provide the pattern. 0799 * <P> 0800 * A numbering system override is a string containing either the name of a known numbering system, 0801 * or a set of field and numbering system pairs that specify which fields are to be formatted with 0802 * the alternate numbering system. For example, to specify that all numeric fields in the specified 0803 * date or time pattern are to be rendered using Thai digits, simply specify the numbering system override 0804 * as "thai". To specify that just the year portion of the date be formatted using Hebrew numbering, 0805 * use the override string "y=hebrew". Numbering system overrides can be combined using a semi-colon 0806 * character in the override string, such as "d=decimal;M=arabic;y=hebrew", etc. 0807 * <P> 0808 * [Note:] Not all locales support SimpleDateFormat; for full generality, 0809 * use the factory methods in the DateFormat class. 0810 * @param pattern the pattern for the format. 0811 * @param override the numbering system override. 0812 * @param locale the given locale. 0813 * @param status Output param set to success/failure code. 0814 * @stable ICU 4.2 0815 */ 0816 SimpleDateFormat(const UnicodeString& pattern, 0817 const UnicodeString& override, 0818 const Locale& locale, 0819 UErrorCode& status); 0820 0821 /** 0822 * Construct a SimpleDateFormat using the given pattern and locale-specific 0823 * symbol data. The formatter takes ownership of the DateFormatSymbols object; 0824 * the caller is no longer responsible for deleting it. 0825 * @param pattern the given pattern for the format. 0826 * @param formatDataToAdopt the symbols to be adopted. 0827 * @param status Output param set to success/faulure code. 0828 * @stable ICU 2.0 0829 */ 0830 SimpleDateFormat(const UnicodeString& pattern, 0831 DateFormatSymbols* formatDataToAdopt, 0832 UErrorCode& status); 0833 0834 /** 0835 * Construct a SimpleDateFormat using the given pattern and locale-specific 0836 * symbol data. The DateFormatSymbols object is NOT adopted; the caller 0837 * remains responsible for deleting it. 0838 * @param pattern the given pattern for the format. 0839 * @param formatData the formatting symbols to be use. 0840 * @param status Output param set to success/faulure code. 0841 * @stable ICU 2.0 0842 */ 0843 SimpleDateFormat(const UnicodeString& pattern, 0844 const DateFormatSymbols& formatData, 0845 UErrorCode& status); 0846 0847 /** 0848 * Copy constructor. 0849 * @stable ICU 2.0 0850 */ 0851 SimpleDateFormat(const SimpleDateFormat&); 0852 0853 /** 0854 * Assignment operator. 0855 * @stable ICU 2.0 0856 */ 0857 SimpleDateFormat& operator=(const SimpleDateFormat&); 0858 0859 /** 0860 * Destructor. 0861 * @stable ICU 2.0 0862 */ 0863 virtual ~SimpleDateFormat(); 0864 0865 /** 0866 * Clone this Format object polymorphically. The caller owns the result and 0867 * should delete it when done. 0868 * @return A copy of the object. 0869 * @stable ICU 2.0 0870 */ 0871 virtual SimpleDateFormat* clone() const override; 0872 0873 /** 0874 * Return true if the given Format objects are semantically equal. Objects 0875 * of different subclasses are considered unequal. 0876 * @param other the object to be compared with. 0877 * @return true if the given Format objects are semantically equal. 0878 * @stable ICU 2.0 0879 */ 0880 virtual bool operator==(const Format& other) const override; 0881 0882 0883 using DateFormat::format; 0884 0885 /** 0886 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 0887 * 1, 1970. Overrides DateFormat pure virtual method. 0888 * <P> 0889 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 0890 * 1996.07.10 AD at 15:08:56 PDT 0891 * 0892 * @param cal Calendar set to the date and time to be formatted 0893 * into a date/time string. 0894 * @param appendTo Output parameter to receive result. 0895 * Result is appended to existing contents. 0896 * @param pos The formatting position. On input: an alignment field, 0897 * if desired. On output: the offsets of the alignment field. 0898 * @return Reference to 'appendTo' parameter. 0899 * @stable ICU 2.1 0900 */ 0901 virtual UnicodeString& format( Calendar& cal, 0902 UnicodeString& appendTo, 0903 FieldPosition& pos) const override; 0904 0905 /** 0906 * Format a date or time, which is the standard millis since 24:00 GMT, Jan 0907 * 1, 1970. Overrides DateFormat pure virtual method. 0908 * <P> 0909 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 0910 * 1996.07.10 AD at 15:08:56 PDT 0911 * 0912 * @param cal Calendar set to the date and time to be formatted 0913 * into a date/time string. 0914 * @param appendTo Output parameter to receive result. 0915 * Result is appended to existing contents. 0916 * @param posIter On return, can be used to iterate over positions 0917 * of fields generated by this format call. Field values 0918 * are defined in UDateFormatField. 0919 * @param status Input/output param set to success/failure code. 0920 * @return Reference to 'appendTo' parameter. 0921 * @stable ICU 4.4 0922 */ 0923 virtual UnicodeString& format( Calendar& cal, 0924 UnicodeString& appendTo, 0925 FieldPositionIterator* posIter, 0926 UErrorCode& status) const override; 0927 0928 using DateFormat::parse; 0929 0930 /** 0931 * Parse a date/time string beginning at the given parse position. For 0932 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date 0933 * that is equivalent to Date(837039928046). 0934 * <P> 0935 * By default, parsing is lenient: If the input is not in the form used by 0936 * this object's format method but can still be parsed as a date, then the 0937 * parse succeeds. Clients may insist on strict adherence to the format by 0938 * calling setLenient(false). 0939 * @see DateFormat::setLenient(boolean) 0940 * 0941 * @param text The date/time string to be parsed 0942 * @param cal A Calendar set on input to the date and time to be used for 0943 * missing values in the date/time string being parsed, and set 0944 * on output to the parsed date/time. When the calendar type is 0945 * different from the internal calendar held by this SimpleDateFormat 0946 * instance, the internal calendar will be cloned to a work 0947 * calendar set to the same milliseconds and time zone as the 0948 * cal parameter, field values will be parsed based on the work 0949 * calendar, then the result (milliseconds and time zone) will 0950 * be set in this calendar. 0951 * @param pos On input, the position at which to start parsing; on 0952 * output, the position at which parsing terminated, or the 0953 * start position if the parse failed. 0954 * @stable ICU 2.1 0955 */ 0956 virtual void parse( const UnicodeString& text, 0957 Calendar& cal, 0958 ParsePosition& pos) const override; 0959 0960 0961 /** 0962 * Set the start UDate used to interpret two-digit year strings. 0963 * When dates are parsed having 2-digit year strings, they are placed within 0964 * a assumed range of 100 years starting on the two digit start date. For 0965 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or 0966 * some other year. SimpleDateFormat chooses a year so that the resultant 0967 * date is on or after the two digit start date and within 100 years of the 0968 * two digit start date. 0969 * <P> 0970 * By default, the two digit start date is set to 80 years before the current 0971 * time at which a SimpleDateFormat object is created. 0972 * @param d start UDate used to interpret two-digit year strings. 0973 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 0974 * an error value if there was a parse error. 0975 * @stable ICU 2.0 0976 */ 0977 virtual void set2DigitYearStart(UDate d, UErrorCode& status); 0978 0979 /** 0980 * Get the start UDate used to interpret two-digit year strings. 0981 * When dates are parsed having 2-digit year strings, they are placed within 0982 * a assumed range of 100 years starting on the two digit start date. For 0983 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or 0984 * some other year. SimpleDateFormat chooses a year so that the resultant 0985 * date is on or after the two digit start date and within 100 years of the 0986 * two digit start date. 0987 * <P> 0988 * By default, the two digit start date is set to 80 years before the current 0989 * time at which a SimpleDateFormat object is created. 0990 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with 0991 * an error value if there was a parse error. 0992 * @stable ICU 2.0 0993 */ 0994 UDate get2DigitYearStart(UErrorCode& status) const; 0995 0996 /** 0997 * Return a pattern string describing this date format. 0998 * @param result Output param to receive the pattern. 0999 * @return A reference to 'result'. 1000 * @stable ICU 2.0 1001 */ 1002 virtual UnicodeString& toPattern(UnicodeString& result) const; 1003 1004 /** 1005 * Return a localized pattern string describing this date format. 1006 * In most cases, this will return the same thing as toPattern(), 1007 * but a locale can specify characters to use in pattern descriptions 1008 * in place of the ones described in this class's class documentation. 1009 * (Presumably, letters that would be more mnemonic in that locale's 1010 * language.) This function would produce a pattern using those 1011 * letters. 1012 * <p> 1013 * <b>Note:</b> This implementation depends on DateFormatSymbols::getLocalPatternChars() 1014 * to get localized format pattern characters. ICU does not include 1015 * localized pattern character data, therefore, unless user sets localized 1016 * pattern characters manually, this method returns the same result as 1017 * toPattern(). 1018 * 1019 * @param result Receives the localized pattern. 1020 * @param status Output param set to success/failure code on 1021 * exit. If the pattern is invalid, this will be 1022 * set to a failure result. 1023 * @return A reference to 'result'. 1024 * @stable ICU 2.0 1025 */ 1026 virtual UnicodeString& toLocalizedPattern(UnicodeString& result, 1027 UErrorCode& status) const; 1028 1029 /** 1030 * Apply the given unlocalized pattern string to this date format. 1031 * (i.e., after this call, this formatter will format dates according to 1032 * the new pattern) 1033 * 1034 * @param pattern The pattern to be applied. 1035 * @stable ICU 2.0 1036 */ 1037 virtual void applyPattern(const UnicodeString& pattern); 1038 1039 /** 1040 * Apply the given localized pattern string to this date format. 1041 * (see toLocalizedPattern() for more information on localized patterns.) 1042 * 1043 * @param pattern The localized pattern to be applied. 1044 * @param status Output param set to success/failure code on 1045 * exit. If the pattern is invalid, this will be 1046 * set to a failure result. 1047 * @stable ICU 2.0 1048 */ 1049 virtual void applyLocalizedPattern(const UnicodeString& pattern, 1050 UErrorCode& status); 1051 1052 /** 1053 * Gets the date/time formatting symbols (this is an object carrying 1054 * the various strings and other symbols used in formatting: e.g., month 1055 * names and abbreviations, time zone names, AM/PM strings, etc.) 1056 * @return a copy of the date-time formatting data associated 1057 * with this date-time formatter. 1058 * @stable ICU 2.0 1059 */ 1060 virtual const DateFormatSymbols* getDateFormatSymbols(void) const; 1061 1062 /** 1063 * Set the date/time formatting symbols. The caller no longer owns the 1064 * DateFormatSymbols object and should not delete it after making this call. 1065 * @param newFormatSymbols the given date-time formatting symbols to copy. 1066 * @stable ICU 2.0 1067 */ 1068 virtual void adoptDateFormatSymbols(DateFormatSymbols* newFormatSymbols); 1069 1070 /** 1071 * Set the date/time formatting data. 1072 * @param newFormatSymbols the given date-time formatting symbols to copy. 1073 * @stable ICU 2.0 1074 */ 1075 virtual void setDateFormatSymbols(const DateFormatSymbols& newFormatSymbols); 1076 1077 /** 1078 * Return the class ID for this class. This is useful only for comparing to 1079 * a return value from getDynamicClassID(). For example: 1080 * <pre> 1081 * . Base* polymorphic_pointer = createPolymorphicObject(); 1082 * . if (polymorphic_pointer->getDynamicClassID() == 1083 * . erived::getStaticClassID()) ... 1084 * </pre> 1085 * @return The class ID for all objects of this class. 1086 * @stable ICU 2.0 1087 */ 1088 static UClassID U_EXPORT2 getStaticClassID(void); 1089 1090 /** 1091 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 1092 * method is to implement a simple version of RTTI, since not all C++ 1093 * compilers support genuine RTTI. Polymorphic operator==() and clone() 1094 * methods call this method. 1095 * 1096 * @return The class ID for this object. All objects of a 1097 * given class have the same class ID. Objects of 1098 * other classes have different class IDs. 1099 * @stable ICU 2.0 1100 */ 1101 virtual UClassID getDynamicClassID(void) const override; 1102 1103 /** 1104 * Set the calendar to be used by this date format. Initially, the default 1105 * calendar for the specified or default locale is used. The caller should 1106 * not delete the Calendar object after it is adopted by this call. 1107 * Adopting a new calendar will change to the default symbols. 1108 * 1109 * @param calendarToAdopt Calendar object to be adopted. 1110 * @stable ICU 2.0 1111 */ 1112 virtual void adoptCalendar(Calendar* calendarToAdopt) override; 1113 1114 /* Cannot use #ifndef U_HIDE_INTERNAL_API for the following methods since they are virtual */ 1115 /** 1116 * Sets the TimeZoneFormat to be used by this date/time formatter. 1117 * The caller should not delete the TimeZoneFormat object after 1118 * it is adopted by this call. 1119 * @param timeZoneFormatToAdopt The TimeZoneFormat object to be adopted. 1120 * @internal ICU 49 technology preview 1121 */ 1122 virtual void adoptTimeZoneFormat(TimeZoneFormat* timeZoneFormatToAdopt); 1123 1124 /** 1125 * Sets the TimeZoneFormat to be used by this date/time formatter. 1126 * @param newTimeZoneFormat The TimeZoneFormat object to copy. 1127 * @internal ICU 49 technology preview 1128 */ 1129 virtual void setTimeZoneFormat(const TimeZoneFormat& newTimeZoneFormat); 1130 1131 /** 1132 * Gets the time zone format object associated with this date/time formatter. 1133 * @return the time zone format associated with this date/time formatter. 1134 * @internal ICU 49 technology preview 1135 */ 1136 virtual const TimeZoneFormat* getTimeZoneFormat(void) const; 1137 1138 /** 1139 * Set a particular UDisplayContext value in the formatter, such as 1140 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. Note: For getContext, see 1141 * DateFormat. 1142 * @param value The UDisplayContext value to set. 1143 * @param status Input/output status. If at entry this indicates a failure 1144 * status, the function will do nothing; otherwise this will be 1145 * updated with any new status from the function. 1146 * @stable ICU 53 1147 */ 1148 virtual void setContext(UDisplayContext value, UErrorCode& status) override; 1149 1150 /** 1151 * Overrides base class method and 1152 * This method clears per field NumberFormat instances 1153 * previously set by {@see adoptNumberFormat(const UnicodeString&, NumberFormat*, UErrorCode)} 1154 * @param formatToAdopt the NumbeferFormat used 1155 * @stable ICU 54 1156 */ 1157 void adoptNumberFormat(NumberFormat *formatToAdopt) override; 1158 1159 /** 1160 * Allow the user to set the NumberFormat for several fields 1161 * It can be a single field like: "y"(year) or "M"(month) 1162 * It can be several field combined together: "yM"(year and month) 1163 * Note: 1164 * 1 symbol field is enough for multiple symbol field (so "y" will override "yy", "yyy") 1165 * If the field is not numeric, then override has no effect (like "MMM" will use abbreviation, not numerical field) 1166 * Per field NumberFormat can also be cleared in {@see DateFormat::setNumberFormat(const NumberFormat& newNumberFormat)} 1167 * 1168 * @param fields the fields to override(like y) 1169 * @param formatToAdopt the NumbeferFormat used 1170 * @param status Receives a status code, which will be U_ZERO_ERROR 1171 * if the operation succeeds. 1172 * @stable ICU 54 1173 */ 1174 void adoptNumberFormat(const UnicodeString& fields, NumberFormat *formatToAdopt, UErrorCode &status); 1175 1176 /** 1177 * Get the numbering system to be used for a particular field. 1178 * @param field The UDateFormatField to get 1179 * @stable ICU 54 1180 */ 1181 const NumberFormat * getNumberFormatForField(char16_t field) const; 1182 1183 #ifndef U_HIDE_INTERNAL_API 1184 /** 1185 * This is for ICU internal use only. Please do not use. 1186 * Check whether the 'field' is smaller than all the fields covered in 1187 * pattern, return true if it is. The sequence of calendar field, 1188 * from large to small is: ERA, YEAR, MONTH, DATE, AM_PM, HOUR, MINUTE,... 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 UBool isFieldUnitIgnored(UCalendarDateFields field) const; 1195 1196 1197 /** 1198 * This is for ICU internal use only. Please do not use. 1199 * Check whether the 'field' is smaller than all the fields covered in 1200 * pattern, return true if it is. The sequence of calendar field, 1201 * from large to small is: ERA, YEAR, MONTH, DATE, AM_PM, HOUR, MINUTE,... 1202 * @param pattern the pattern to check against 1203 * @param field the calendar field need to check against 1204 * @return true if the 'field' is smaller than all the fields 1205 * covered in pattern. false otherwise. 1206 * @internal ICU 4.0 1207 */ 1208 static UBool isFieldUnitIgnored(const UnicodeString& pattern, 1209 UCalendarDateFields field); 1210 1211 /** 1212 * This is for ICU internal use only. Please do not use. 1213 * Get the locale of this simple date formatter. 1214 * It is used in DateIntervalFormat. 1215 * 1216 * @return locale in this simple date formatter 1217 * @internal ICU 4.0 1218 */ 1219 const Locale& getSmpFmtLocale(void) const; 1220 #endif /* U_HIDE_INTERNAL_API */ 1221 1222 private: 1223 friend class DateFormat; 1224 friend class DateIntervalFormat; 1225 1226 void initializeDefaultCentury(void); 1227 1228 void initializeBooleanAttributes(void); 1229 1230 SimpleDateFormat() = delete; // default constructor not implemented 1231 1232 /** 1233 * Used by the DateFormat factory methods to construct a SimpleDateFormat. 1234 * @param timeStyle the time style. 1235 * @param dateStyle the date style. 1236 * @param locale the given locale. 1237 * @param status Output param set to success/failure code on 1238 * exit. 1239 */ 1240 SimpleDateFormat(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status); 1241 1242 /** 1243 * Construct a SimpleDateFormat for the given locale. If no resource data 1244 * is available, create an object of last resort, using hard-coded strings. 1245 * This is an internal method, called by DateFormat. It should never fail. 1246 * @param locale the given locale. 1247 * @param status Output param set to success/failure code on 1248 * exit. 1249 */ 1250 SimpleDateFormat(const Locale& locale, UErrorCode& status); // Use default pattern 1251 1252 /** 1253 * Hook called by format(... FieldPosition& ...) and format(...FieldPositionIterator&...) 1254 */ 1255 UnicodeString& _format(Calendar& cal, UnicodeString& appendTo, FieldPositionHandler& handler, UErrorCode& status) const; 1256 1257 /** 1258 * Called by format() to format a single field. 1259 * 1260 * @param appendTo Output parameter to receive result. 1261 * Result is appended to existing contents. 1262 * @param ch The format character we encountered in the pattern. 1263 * @param count Number of characters in the current pattern symbol (e.g., 1264 * "yyyy" in the pattern would result in a call to this function 1265 * with ch equal to 'y' and count equal to 4) 1266 * @param capitalizationContext Capitalization context for this date format. 1267 * @param fieldNum Zero-based numbering of current field within the overall format. 1268 * @param handler Records information about field positions. 1269 * @param cal Calendar to use 1270 * @param status Receives a status code, which will be U_ZERO_ERROR if the operation 1271 * succeeds. 1272 */ 1273 void subFormat(UnicodeString &appendTo, 1274 char16_t ch, 1275 int32_t count, 1276 UDisplayContext capitalizationContext, 1277 int32_t fieldNum, 1278 char16_t fieldToOutput, 1279 FieldPositionHandler& handler, 1280 Calendar& cal, 1281 UErrorCode& status) const; // in case of illegal argument 1282 1283 /** 1284 * Used by subFormat() to format a numeric value. 1285 * Appends to toAppendTo a string representation of "value" 1286 * having a number of digits between "minDigits" and 1287 * "maxDigits". Uses the DateFormat's NumberFormat. 1288 * 1289 * @param currentNumberFormat 1290 * @param appendTo Output parameter to receive result. 1291 * Formatted number is appended to existing contents. 1292 * @param value Value to format. 1293 * @param minDigits Minimum number of digits the result should have 1294 * @param maxDigits Maximum number of digits the result should have 1295 */ 1296 void zeroPaddingNumber(const NumberFormat *currentNumberFormat, 1297 UnicodeString &appendTo, 1298 int32_t value, 1299 int32_t minDigits, 1300 int32_t maxDigits) const; 1301 1302 /** 1303 * Return true if the given format character, occurring count 1304 * times, represents a numeric field. 1305 */ 1306 static UBool isNumeric(char16_t formatChar, int32_t count); 1307 1308 /** 1309 * Returns true if the patternOffset is at the start of a numeric field. 1310 */ 1311 static UBool isAtNumericField(const UnicodeString &pattern, int32_t patternOffset); 1312 1313 /** 1314 * Returns true if the patternOffset is right after a non-numeric field. 1315 */ 1316 static UBool isAfterNonNumericField(const UnicodeString &pattern, int32_t patternOffset); 1317 1318 /** 1319 * initializes fCalendar from parameters. Returns fCalendar as a convenience. 1320 * @param adoptZone Zone to be adopted, or nullptr for TimeZone::createDefault(). 1321 * @param locale Locale of the calendar 1322 * @param status Error code 1323 * @return the newly constructed fCalendar 1324 */ 1325 Calendar *initializeCalendar(TimeZone* adoptZone, const Locale& locale, UErrorCode& status); 1326 1327 /** 1328 * Called by several of the constructors to load pattern data and formatting symbols 1329 * out of a resource bundle and initialize the locale based on it. 1330 * @param timeStyle The time style, as passed to DateFormat::createDateInstance(). 1331 * @param dateStyle The date style, as passed to DateFormat::createTimeInstance(). 1332 * @param locale The locale to load the patterns from. 1333 * @param status Filled in with an error code if loading the data from the 1334 * resources fails. 1335 */ 1336 void construct(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status); 1337 1338 /** 1339 * Called by construct() and the various constructors to set up the SimpleDateFormat's 1340 * Calendar and NumberFormat objects. 1341 * @param locale The locale for which we want a Calendar and a NumberFormat. 1342 * @param status Filled in with an error code if creating either subobject fails. 1343 */ 1344 void initialize(const Locale& locale, UErrorCode& status); 1345 1346 /** 1347 * Private code-size reduction function used by subParse. 1348 * @param text the time text being parsed. 1349 * @param start where to start parsing. 1350 * @param field the date field being parsed. 1351 * @param stringArray the string array to parsed. 1352 * @param stringArrayCount the size of the array. 1353 * @param monthPattern pointer to leap month pattern, or nullptr if none. 1354 * @param cal a Calendar set to the date and time to be formatted 1355 * into a date/time string. 1356 * @return the new start position if matching succeeded; a negative number 1357 * indicating matching failure, otherwise. 1358 */ 1359 int32_t matchString(const UnicodeString& text, int32_t start, UCalendarDateFields field, 1360 const UnicodeString* stringArray, int32_t stringArrayCount, 1361 const UnicodeString* monthPattern, Calendar& cal) const; 1362 1363 /** 1364 * Private code-size reduction function used by subParse. Only for UCAL_MONTH 1365 * @param text the time text being parsed. 1366 * @param start where to start parsing. 1367 * @param wideStringArray the wide string array to parsed. 1368 * @param shortStringArray the short string array to parsed. 1369 * @param stringArrayCount the size of the string arrays. 1370 * @param cal a Calendar set to the date and time to be formatted 1371 * into a date/time string. 1372 * @return the new start position if matching succeeded; a negative number 1373 * indicating matching failure, otherwise. 1374 */ 1375 int32_t matchAlphaMonthStrings(const UnicodeString& text, int32_t start, 1376 const UnicodeString* wideStringArray, const UnicodeString* shortStringArray, 1377 int32_t stringArrayCount, Calendar& cal) const; 1378 1379 /** 1380 * Private code-size reduction function used by subParse. 1381 * @param text the time text being parsed. 1382 * @param start where to start parsing. 1383 * @param field the date field being parsed. 1384 * @param stringArray the string array to parsed. 1385 * @param stringArrayCount the size of the array. 1386 * @param cal a Calendar set to the date and time to be formatted 1387 * into a date/time string. 1388 * @return the new start position if matching succeeded; a negative number 1389 * indicating matching failure, otherwise. 1390 */ 1391 int32_t matchQuarterString(const UnicodeString& text, int32_t start, UCalendarDateFields field, 1392 const UnicodeString* stringArray, int32_t stringArrayCount, Calendar& cal) const; 1393 1394 /** 1395 * Used by subParse() to match localized day period strings. 1396 */ 1397 int32_t matchDayPeriodStrings(const UnicodeString& text, int32_t start, 1398 const UnicodeString* stringArray, int32_t stringArrayCount, 1399 int32_t &dayPeriod) const; 1400 1401 /** 1402 * Private function used by subParse to match literal pattern text. 1403 * 1404 * @param pattern the pattern string 1405 * @param patternOffset the starting offset into the pattern text. On 1406 * output will be set the offset of the first non-literal character in the pattern 1407 * @param text the text being parsed 1408 * @param textOffset the starting offset into the text. On output 1409 * will be set to the offset of the character after the match 1410 * @param whitespaceLenient <code>true</code> if whitespace parse is lenient, <code>false</code> otherwise. 1411 * @param partialMatchLenient <code>true</code> if partial match parse is lenient, <code>false</code> otherwise. 1412 * @param oldLeniency <code>true</code> if old leniency control is lenient, <code>false</code> otherwise. 1413 * 1414 * @return <code>true</code> if the literal text could be matched, <code>false</code> otherwise. 1415 */ 1416 static UBool matchLiterals(const UnicodeString &pattern, int32_t &patternOffset, 1417 const UnicodeString &text, int32_t &textOffset, 1418 UBool whitespaceLenient, UBool partialMatchLenient, UBool oldLeniency); 1419 1420 /** 1421 * Private member function that converts the parsed date strings into 1422 * timeFields. Returns -start (for ParsePosition) if failed. 1423 * @param text the time text to be parsed. 1424 * @param start where to start parsing. 1425 * @param ch the pattern character for the date field text to be parsed. 1426 * @param count the count of a pattern character. 1427 * @param obeyCount if true then the count is strictly obeyed. 1428 * @param allowNegative 1429 * @param ambiguousYear If true then the two-digit year == the default start year. 1430 * @param saveHebrewMonth Used to hang onto month until year is known. 1431 * @param cal a Calendar set to the date and time to be formatted 1432 * into a date/time string. 1433 * @param patLoc 1434 * @param numericLeapMonthFormatter If non-null, used to parse numeric leap months. 1435 * @param tzTimeType the type of parsed time zone - standard, daylight or unknown (output). 1436 * This parameter can be nullptr if caller does not need the information. 1437 * @return the new start position if matching succeeded; a negative number 1438 * indicating matching failure, otherwise. 1439 */ 1440 int32_t subParse(const UnicodeString& text, int32_t& start, char16_t ch, int32_t count, 1441 UBool obeyCount, UBool allowNegative, UBool ambiguousYear[], int32_t& saveHebrewMonth, Calendar& cal, 1442 int32_t patLoc, MessageFormat * numericLeapMonthFormatter, UTimeZoneFormatTimeType *tzTimeType, 1443 int32_t *dayPeriod=nullptr) const; 1444 1445 void parseInt(const UnicodeString& text, 1446 Formattable& number, 1447 ParsePosition& pos, 1448 UBool allowNegative, 1449 const NumberFormat *fmt) const; 1450 1451 void parseInt(const UnicodeString& text, 1452 Formattable& number, 1453 int32_t maxDigits, 1454 ParsePosition& pos, 1455 UBool allowNegative, 1456 const NumberFormat *fmt) const; 1457 1458 int32_t checkIntSuffix(const UnicodeString& text, int32_t start, 1459 int32_t patLoc, UBool isNegative) const; 1460 1461 /** 1462 * Counts number of digit code points in the specified text. 1463 * 1464 * @param text input text 1465 * @param start start index, inclusive 1466 * @param end end index, exclusive 1467 * @return number of digits found in the text in the specified range. 1468 */ 1469 int32_t countDigits(const UnicodeString& text, int32_t start, int32_t end) const; 1470 1471 /** 1472 * Translate a pattern, mapping each character in the from string to the 1473 * corresponding character in the to string. Return an error if the original 1474 * pattern contains an unmapped character, or if a quote is unmatched. 1475 * Quoted (single quotes only) material is not translated. 1476 * @param originalPattern the original pattern. 1477 * @param translatedPattern Output param to receive the translited pattern. 1478 * @param from the characters to be translited from. 1479 * @param to the characters to be translited to. 1480 * @param status Receives a status code, which will be U_ZERO_ERROR 1481 * if the operation succeeds. 1482 */ 1483 static void translatePattern(const UnicodeString& originalPattern, 1484 UnicodeString& translatedPattern, 1485 const UnicodeString& from, 1486 const UnicodeString& to, 1487 UErrorCode& status); 1488 1489 /** 1490 * Sets the starting date of the 100-year window that dates with 2-digit years 1491 * are considered to fall within. 1492 * @param startDate the start date 1493 * @param status Receives a status code, which will be U_ZERO_ERROR 1494 * if the operation succeeds. 1495 */ 1496 void parseAmbiguousDatesAsAfter(UDate startDate, UErrorCode& status); 1497 1498 /** 1499 * Return the length matched by the given affix, or -1 if none. 1500 * Runs of white space in the affix, match runs of white space in 1501 * the input. 1502 * @param affix pattern string, taken as a literal 1503 * @param input input text 1504 * @param pos offset into input at which to begin matching 1505 * @return length of input that matches, or -1 if match failure 1506 */ 1507 int32_t compareSimpleAffix(const UnicodeString& affix, 1508 const UnicodeString& input, 1509 int32_t pos) const; 1510 1511 /** 1512 * Skip over a run of zero or more Pattern_White_Space characters at 1513 * pos in text. 1514 */ 1515 int32_t skipPatternWhiteSpace(const UnicodeString& text, int32_t pos) const; 1516 1517 /** 1518 * Skip over a run of zero or more isUWhiteSpace() characters at pos 1519 * in text. 1520 */ 1521 int32_t skipUWhiteSpace(const UnicodeString& text, int32_t pos) const; 1522 1523 /** 1524 * Initialize SimpleNumberFormat instance 1525 */ 1526 void initSimpleNumberFormatter(UErrorCode &status); 1527 1528 /** 1529 * Initialize NumberFormat instances used for numbering system overrides. 1530 */ 1531 void initNumberFormatters(const Locale &locale,UErrorCode &status); 1532 1533 /** 1534 * Parse the given override string and set up structures for number formats 1535 */ 1536 void processOverrideString(const Locale &locale, const UnicodeString &str, int8_t type, UErrorCode &status); 1537 1538 /** 1539 * Used to map pattern characters to Calendar field identifiers. 1540 */ 1541 static const UCalendarDateFields fgPatternIndexToCalendarField[]; 1542 1543 /** 1544 * Map index into pattern character string to DateFormat field number 1545 */ 1546 static const UDateFormatField fgPatternIndexToDateFormatField[]; 1547 1548 /** 1549 * Lazy TimeZoneFormat instantiation, semantically const 1550 */ 1551 TimeZoneFormat *tzFormat(UErrorCode &status) const; 1552 1553 const NumberFormat* getNumberFormatByIndex(UDateFormatField index) const; 1554 1555 /** 1556 * Used to map Calendar field to field level. 1557 * The larger the level, the smaller the field unit. 1558 * For example, UCAL_ERA level is 0, UCAL_YEAR level is 10, 1559 * UCAL_MONTH level is 20. 1560 */ 1561 static const int32_t fgCalendarFieldToLevel[]; 1562 1563 /** 1564 * Map calendar field letter into calendar field level. 1565 */ 1566 static int32_t getLevelFromChar(char16_t ch); 1567 1568 /** 1569 * Tell if a character can be used to define a field in a format string. 1570 */ 1571 static UBool isSyntaxChar(char16_t ch); 1572 1573 /** 1574 * The formatting pattern for this formatter. 1575 */ 1576 UnicodeString fPattern; 1577 1578 /** 1579 * The numbering system override for dates. 1580 */ 1581 UnicodeString fDateOverride; 1582 1583 /** 1584 * The numbering system override for times. 1585 */ 1586 UnicodeString fTimeOverride; 1587 1588 1589 /** 1590 * The original locale used (for reloading symbols) 1591 */ 1592 Locale fLocale; 1593 1594 /** 1595 * A pointer to an object containing the strings to use in formatting (e.g., 1596 * month and day names, AM and PM strings, time zone names, etc.) 1597 */ 1598 DateFormatSymbols* fSymbols = nullptr; // Owned 1599 1600 /** 1601 * The time zone formatter 1602 */ 1603 TimeZoneFormat* fTimeZoneFormat = nullptr; 1604 1605 /** 1606 * If dates have ambiguous years, we map them into the century starting 1607 * at defaultCenturyStart, which may be any date. If defaultCenturyStart is 1608 * set to SYSTEM_DEFAULT_CENTURY, which it is by default, then the system 1609 * values are used. The instance values defaultCenturyStart and 1610 * defaultCenturyStartYear are only used if explicitly set by the user 1611 * through the API method parseAmbiguousDatesAsAfter(). 1612 */ 1613 UDate fDefaultCenturyStart; 1614 1615 UBool fHasMinute; 1616 UBool fHasSecond; 1617 UBool fHasHanYearChar; // pattern contains the Han year character \u5E74 1618 1619 /** 1620 * Sets fHasMinutes and fHasSeconds. 1621 */ 1622 void parsePattern(); 1623 1624 /** 1625 * See documentation for defaultCenturyStart. 1626 */ 1627 /*transient*/ int32_t fDefaultCenturyStartYear; 1628 1629 struct NSOverride : public UMemory { 1630 const SharedNumberFormat *snf; 1631 int32_t hash; 1632 NSOverride *next; 1633 void free(); 1634 NSOverride() : snf(nullptr), hash(0), next(nullptr) { 1635 } 1636 ~NSOverride(); 1637 }; 1638 1639 /** 1640 * The number format in use for each date field. nullptr means fall back 1641 * to fNumberFormat in DateFormat. 1642 */ 1643 const SharedNumberFormat **fSharedNumberFormatters = nullptr; 1644 1645 /** 1646 * Number formatter pre-allocated for fast performance 1647 * 1648 * This references the decimal symbols from fNumberFormatter if it is an instance 1649 * of DecimalFormat (and is otherwise null). This should always be cleaned up before 1650 * destroying fNumberFormatter. 1651 */ 1652 const number::SimpleNumberFormatter* fSimpleNumberFormatter = nullptr; 1653 1654 UBool fHaveDefaultCentury; 1655 1656 const BreakIterator* fCapitalizationBrkIter = nullptr; 1657 }; 1658 1659 inline UDate 1660 SimpleDateFormat::get2DigitYearStart(UErrorCode& /*status*/) const 1661 { 1662 return fDefaultCenturyStart; 1663 } 1664 1665 U_NAMESPACE_END 1666 1667 #endif /* #if !UCONFIG_NO_FORMATTING */ 1668 1669 #endif /* U_SHOW_CPLUSPLUS_API */ 1670 1671 #endif // _SMPDTFMT 1672 //eof
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|