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