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