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