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