1 /*
2 * Copyright (C) 1997-2006, International Business Machines Corporation and others. All Rights Reserved.
3 *******************************************************************************
4 *
5 * File SMPDTFMT.H
6 *
7 * Modification History:
8 *
9 * Date Name Description
10 * 02/19/97 aliu Converted from java.
11 * 07/09/97 helena Make ParsePosition into a class.
12 * 07/21/98 stephen Added GMT_PLUS, GMT_MINUS
13 * Changed setTwoDigitStartDate to set2DigitYearStart
14 * Changed getTwoDigitStartDate to get2DigitYearStart
15 * Removed subParseLong
16 * Removed getZoneIndex (added in DateFormatSymbols)
17 * 06/14/99 stephen Removed fgTimeZoneDataSuffix
18 * 10/14/99 aliu Updated class doc to describe 2-digit year parsing
19 * {j28 4182066}.
20 *******************************************************************************
21 */
22
23 #ifndef SMPDTFMT_H
24 #define SMPDTFMT_H
25
26 #include "unicode/utypes.h"
27
28 /**
29 * \file
30 * \brief C++ API: Format and parse dates in a language-independent manner.
31 */
32
33 #if !UCONFIG_NO_FORMATTING
34
35 #include "unicode/datefmt.h"
36
37 U_NAMESPACE_BEGIN
38
39 class DateFormatSymbols;
40 class DateFormat;
41 class MessageFormat;
42
43 /**
44 *
45 * SimpleDateFormat is a concrete class for formatting and parsing dates in a
46 * language-independent manner. It allows for formatting (millis -> text),
47 * parsing (text -> millis), and normalization. Formats/Parses a date or time,
48 * which is the standard milliseconds since 24:00 GMT, Jan 1, 1970.
49 * <P>
50 * Clients are encouraged to create a date-time formatter using DateFormat::getInstance(),
51 * getDateInstance(), getDateInstance(), or getDateTimeInstance() rather than
52 * explicitly constructing an instance of SimpleDateFormat. This way, the client
53 * is guaranteed to get an appropriate formatting pattern for whatever locale the
54 * program is running in. However, if the client needs something more unusual than
55 * the default patterns in the locales, he can construct a SimpleDateFormat directly
56 * and give it an appropriate pattern (or use one of the factory methods on DateFormat
57 * and modify the pattern after the fact with toPattern() and applyPattern().
58 * <P>
59 * Date/Time format syntax:
60 * <P>
61 * The date/time format is specified by means of a string time pattern. In this
62 * pattern, all ASCII letters are reserved as pattern letters, which are defined
63 * as the following:
64 * <pre>
65 * \code
66 * Symbol Meaning Presentation Example
67 * ------ ------- ------------ -------
68 * G era designator (Text) AD
69 * y year (Number) 1996
70 * Y year (week of year) (Number) 1997
71 * u extended year (Number) 4601
72 * M month in year (Text & Number) July & 07
73 * d day in month (Number) 10
74 * h hour in am/pm (1~12) (Number) 12
75 * H hour in day (0~23) (Number) 0
76 * m minute in hour (Number) 30
77 * s second in minute (Number) 55
78 * S fractional second (Number) 978
79 * E day of week (Text) Tuesday
80 * e day of week (local 1~7) (Number) 2
81 * D day in year (Number) 189
82 * F day of week in month (Number) 2 (2nd Wed in July)
83 * w week in year (Number) 27
84 * W week in month (Number) 2
85 * a am/pm marker (Text) PM
86 * k hour in day (1~24) (Number) 24
87 * K hour in am/pm (0~11) (Number) 0
88 * z time zone (Time) Pacific Standard Time
89 * Z time zone (RFC 822) (Number) -0800
90 * v time zone (generic) (Text) Pacific Time
91 * g Julian day (Number) 2451334
92 * A milliseconds in day (Number) 69540000
93 * ' escape for text (Delimiter) 'Date='
94 * '' single quote (Literal) 'o''clock'
95 * \endcode
96 * </pre>
97 * The count of pattern letters determine the format.
98 * <P>
99 * (Text): 4 or more, use full form, <4, use short or abbreviated form if it
100 * exists. (e.g., "EEEE" produces "Monday", "EEE" produces "Mon")
101 * <P>
102 * (Number): the minimum number of digits. Shorter numbers are zero-padded to
103 * this amount (e.g. if "m" produces "6", "mm" produces "06"). Year is handled
104 * specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits.
105 * (e.g., if "yyyy" produces "1997", "yy" produces "97".)
106 * Unlike other fields, fractional seconds are padded on the right with zero.
107 * <P>
108 * (Text & Number): 3 or over, use text, otherwise use number. (e.g., "M" produces "1",
109 * "MM" produces "01", "MMM" produces "Jan", and "MMMM" produces "January".)
110 * <P>
111 * Any characters in the pattern that are not in the ranges of ['a'..'z'] and
112 * ['A'..'Z'] will be treated as quoted text. For instance, characters
113 * like ':', '.', ' ', '#' and '@' will appear in the resulting time text
114 * even they are not embraced within single quotes.
115 * <P>
116 * A pattern containing any invalid pattern letter will result in a failing
117 * UErrorCode result during formatting or parsing.
118 * <P>
119 * Examples using the US locale:
120 * <pre>
121 * \code
122 * Format Pattern Result
123 * -------------- -------
124 * "yyyy.MM.dd G 'at' HH:mm:ss vvvv" ->> 1996.07.10 AD at 15:08:56 Pacific Time
125 * "EEE, MMM d, ''yy" ->> Wed, July 10, '96
126 * "h:mm a" ->> 12:08 PM
127 * "hh 'o''clock' a, zzzz" ->> 12 o'clock PM, Pacific Daylight Time
128 * "K:mm a, vvv" ->> 0:00 PM, PT
129 * "yyyyy.MMMMM.dd GGG hh:mm aaa" ->> 1996.July.10 AD 12:08 PM
130 * \endcode
131 * </pre>
132 * Code Sample:
133 * <pre>
134 * \code
135 * UErrorCode success = U_ZERO_ERROR;
136 * SimpleTimeZone* pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST");
137 * pdt->setStartRule( Calendar::APRIL, 1, Calendar::SUNDAY, 2*60*60*1000);
138 * pdt->setEndRule( Calendar::OCTOBER, -1, Calendar::SUNDAY, 2*60*60*1000);
139 *
140 * // Format the current time.
141 * SimpleDateFormat* formatter
142 * = new SimpleDateFormat ("yyyy.MM.dd G 'at' hh:mm:ss a zzz", success );
143 * GregorianCalendar cal(success);
144 * UDate currentTime_1 = cal.getTime(success);
145 * FieldPosition fp(0);
146 * UnicodeString dateString;
147 * formatter->format( currentTime_1, dateString, fp );
148 * cout << "result: " << dateString << endl;
149 *
150 * // Parse the previous string back into a Date.
151 * ParsePosition pp(0);
152 * UDate currentTime_2 = formatter->parse(dateString, pp );
153 * \endcode
154 * </pre>
155 * In the above example, the time value "currentTime_2" obtained from parsing
156 * will be equal to currentTime_1. However, they may not be equal if the am/pm
157 * marker 'a' is left out from the format pattern while the "hour in am/pm"
158 * pattern symbol is used. This information loss can happen when formatting the
159 * time in PM.
160 *
161 * <p>
162 * When parsing a date string using the abbreviated year pattern ("y" or "yy"),
163 * SimpleDateFormat must interpret the abbreviated year
164 * relative to some century. It does this by adjusting dates to be
165 * within 80 years before and 20 years after the time the SimpleDateFormat
166 * instance is created. For example, using a pattern of "MM/dd/yy" and a
167 * SimpleDateFormat instance created on Jan 1, 1997, the string
168 * "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64"
169 * would be interpreted as May 4, 1964.
170 * During parsing, only strings consisting of exactly two digits, as defined by
171 * <code>Unicode::isDigit()</code>, will be parsed into the default century.
172 * Any other numeric string, such as a one digit string, a three or more digit
173 * string, or a two digit string that isn't all digits (for example, "-1"), is
174 * interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the
175 * same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC.
176 *
177 * <p>
178 * If the year pattern has more than two 'y' characters, the year is
179 * interpreted literally, regardless of the number of digits. So using the
180 * pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.
181 *
182 * <p>
183 * When numeric fields abut one another directly, with no intervening delimiter
184 * characters, they constitute a run of abutting numeric fields. Such runs are
185 * parsed specially. For example, the format "HHmmss" parses the input text
186 * "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to
187 * parse "1234". In other words, the leftmost field of the run is flexible,
188 * while the others keep a fixed width. If the parse fails anywhere in the run,
189 * then the leftmost field is shortened by one character, and the entire run is
190 * parsed again. This is repeated until either the parse succeeds or the
191 * leftmost field is one character in length. If the parse still fails at that
192 * point, the parse of the run fails.
193 *
194 * <P>
195 * For time zones that have no names, SimpleDateFormat uses strings GMT+hours:minutes or
196 * GMT-hours:minutes.
197 * <P>
198 * The calendar defines what is the first day of the week, the first week of the
199 * year, whether hours are zero based or not (0 vs 12 or 24), and the timezone.
200 * There is one common number format to handle all the numbers; the digit count
201 * is handled programmatically according to the pattern.
202 *
203 * <p><em>User subclasses are not supported.</em> While clients may write
204 * subclasses, such code will not necessarily work and will not be
205 * guaranteed to work stably from release to release.
206 */
207 class U_I18N_API SimpleDateFormat: public DateFormat {
208 public:
209 /**
210 * Construct a SimpleDateFormat using the default pattern for the default
211 * locale.
212 * <P>
213 * [Note:] Not all locales support SimpleDateFormat; for full generality,
214 * use the factory methods in the DateFormat class.
215 * @param status Output param set to success/failure code.
216 * @stable ICU 2.0
217 */
218 SimpleDateFormat(UErrorCode& status);
219
220 /**
221 * Construct a SimpleDateFormat using the given pattern and the default locale.
222 * The locale is used to obtain the symbols used in formatting (e.g., the
223 * names of the months), but not to provide the pattern.
224 * <P>
225 * [Note:] Not all locales support SimpleDateFormat; for full generality,
226 * use the factory methods in the DateFormat class.
227 * @param pattern the pattern for the format.
228 * @param status Output param set to success/failure code.
229 * @stable ICU 2.0
230 */
231 SimpleDateFormat(const UnicodeString& pattern,
232 UErrorCode& status);
233
234 /**
235 * Construct a SimpleDateFormat using the given pattern and locale.
236 * The locale is used to obtain the symbols used in formatting (e.g., the
237 * names of the months), but not to provide the pattern.
238 * <P>
239 * [Note:] Not all locales support SimpleDateFormat; for full generality,
240 * use the factory methods in the DateFormat class.
241 * @param pattern the pattern for the format.
242 * @param locale the given locale.
243 * @param status Output param set to success/failure code.
244 * @stable ICU 2.0
245 */
246 SimpleDateFormat(const UnicodeString& pattern,
247 const Locale& locale,
248 UErrorCode& status);
249
250 /**
251 * Construct a SimpleDateFormat using the given pattern and locale-specific
252 * symbol data. The formatter takes ownership of the DateFormatSymbols object;
253 * the caller is no longer responsible for deleting it.
254 * @param pattern the given pattern for the format.
255 * @param formatDataToAdopt the symbols to be adopted.
256 * @param status Output param set to success/faulure code.
257 * @stable ICU 2.0
258 */
259 SimpleDateFormat(const UnicodeString& pattern,
260 DateFormatSymbols* formatDataToAdopt,
261 UErrorCode& status);
262
263 /**
264 * Construct a SimpleDateFormat using the given pattern and locale-specific
265 * symbol data. The DateFormatSymbols object is NOT adopted; the caller
266 * remains responsible for deleting it.
267 * @param pattern the given pattern for the format.
268 * @param formatData the formatting symbols to be use.
269 * @param status Output param set to success/faulure code.
270 * @stable ICU 2.0
271 */
272 SimpleDateFormat(const UnicodeString& pattern,
273 const DateFormatSymbols& formatData,
274 UErrorCode& status);
275
276 /**
277 * Copy constructor.
278 * @stable ICU 2.0
279 */
280 SimpleDateFormat(const SimpleDateFormat&);
281
282 /**
283 * Assignment operator.
284 * @stable ICU 2.0
285 */
286 SimpleDateFormat& operator=(const SimpleDateFormat&);
287
288 /**
289 * Destructor.
290 * @stable ICU 2.0
291 */
292 virtual ~SimpleDateFormat();
293
294 /**
295 * Clone this Format object polymorphically. The caller owns the result and
296 * should delete it when done.
297 * @return A copy of the object.
298 * @stable ICU 2.0
299 */
300 virtual Format* clone(void) const;
301
302 /**
303 * Return true if the given Format objects are semantically equal. Objects
304 * of different subclasses are considered unequal.
305 * @param other the object to be compared with.
306 * @return true if the given Format objects are semantically equal.
307 * @stable ICU 2.0
308 */
309 virtual UBool operator==(const Format& other) const;
310
311 /**
312 * Format a date or time, which is the standard millis since 24:00 GMT, Jan
313 * 1, 1970. Overrides DateFormat pure virtual method.
314 * <P>
315 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->>
316 * 1996.07.10 AD at 15:08:56 PDT
317 *
318 * @param cal Calendar set to the date and time to be formatted
319 * into a date/time string.
320 * @param appendTo Output parameter to receive result.
321 * Result is appended to existing contents.
322 * @param pos The formatting position. On input: an alignment field,
323 * if desired. On output: the offsets of the alignment field.
324 * @return Reference to 'appendTo' parameter.
325 * @stable ICU 2.1
326 */
327 virtual UnicodeString& format( Calendar& cal,
328 UnicodeString& appendTo,
329 FieldPosition& pos) const;
330
331 /**
332 * Format a date or time, which is the standard millis since 24:00 GMT, Jan
333 * 1, 1970. Overrides DateFormat pure virtual method.
334 * <P>
335 * Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->>
336 * 1996.07.10 AD at 15:08:56 PDT
337 *
338 * @param obj A Formattable containing the date-time value to be formatted
339 * into a date-time string. If the type of the Formattable
340 * is a numeric type, it is treated as if it were an
341 * instance of Date.
342 * @param appendTo Output parameter to receive result.
343 * Result is appended to existing contents.
344 * @param pos The formatting position. On input: an alignment field,
345 * if desired. On output: the offsets of the alignment field.
346 * @param status Output param set to success/faulure code.
347 * @return Reference to 'appendTo' parameter.
348 * @stable ICU 2.0
349 */
350 virtual UnicodeString& format( const Formattable& obj,
351 UnicodeString& appendTo,
352 FieldPosition& pos,
353 UErrorCode& status) const;
354
355 /**
356 * Redeclared DateFormat method.
357 * @param date the Date value to be formatted.
358 * @param appendTo Output parameter to receive result.
359 * Result is appended to existing contents.
360 * @param fieldPosition The formatting position. On input: an alignment field,
361 * if desired. On output: the offsets of the alignment field.
362 * @return Reference to 'appendTo' parameter.
363 * @stable ICU 2.1
364 */
365 UnicodeString& format(UDate date,
366 UnicodeString& appendTo,
367 FieldPosition& fieldPosition) const;
368
369 /**
370 * Redeclared DateFormat method.
371 * @param obj Object to be formatted.
372 * @param appendTo Output parameter to receive result.
373 * Result is appended to existing contents.
374 * @param status Input/output success/failure code.
375 * @return Reference to 'appendTo' parameter.
376 * @stable ICU 2.0
377 */
378 UnicodeString& format(const Formattable& obj,
379 UnicodeString& appendTo,
380 UErrorCode& status) const;
381
382 /**
383 * Redeclared DateFormat method.
384 * @param date Date value to be formatted.
385 * @param appendTo Output parameter to receive result.
386 * Result is appended to existing contents.
387 * @return Reference to 'appendTo' parameter.
388 * @stable ICU 2.0
389 */
390 UnicodeString& format(UDate date, UnicodeString& appendTo) const;
391
392 /**
393 * Parse a date/time string beginning at the given parse position. For
394 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date
395 * that is equivalent to Date(837039928046).
396 * <P>
397 * By default, parsing is lenient: If the input is not in the form used by
398 * this object's format method but can still be parsed as a date, then the
399 * parse succeeds. Clients may insist on strict adherence to the format by
400 * calling setLenient(false).
401 *
402 * @param text The date/time string to be parsed
403 * @param cal a Calendar set to the date and time to be formatted
404 * into a date/time string.
405 * @param pos On input, the position at which to start parsing; on
406 * output, the position at which parsing terminated, or the
407 * start position if the parse failed.
408 * @return A valid UDate if the input could be parsed.
409 * @stable ICU 2.1
410 */
411 virtual void parse( const UnicodeString& text,
412 Calendar& cal,
413 ParsePosition& pos) const;
414
415 /**
416 * Parse a date/time string starting at the given parse position. For
417 * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date
418 * that is equivalent to Date(837039928046).
419 * <P>
420 * By default, parsing is lenient: If the input is not in the form used by
421 * this object's format method but can still be parsed as a date, then the
422 * parse succeeds. Clients may insist on strict adherence to the format by
423 * calling setLenient(false).
424 *
425 * @see DateFormat::setLenient(boolean)
426 *
427 * @param text The date/time string to be parsed
428 * @param pos On input, the position at which to start parsing; on
429 * output, the position at which parsing terminated, or the
430 * start position if the parse failed.
431 * @return A valid UDate if the input could be parsed.
432 * @stable ICU 2.0
433 */
434 UDate parse( const UnicodeString& text,
435 ParsePosition& pos) const;
436
437
438 /**
439 * Parse a date/time string. For example, a time text "07/10/96 4:5 PM, PDT"
440 * will be parsed into a UDate that is equivalent to Date(837039928046).
441 * Parsing begins at the beginning of the string and proceeds as far as
442 * possible. Assuming no parse errors were encountered, this function
443 * doesn't return any information about how much of the string was consumed
444 * by the parsing. If you need that information, use the version of
445 * parse() that takes a ParsePosition.
446 *
447 * @param text The date/time string to be parsed
448 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with
449 * an error value if there was a parse error.
450 * @return A valid UDate if the input could be parsed.
451 * @stable ICU 2.0
452 */
453 virtual UDate parse( const UnicodeString& text,
454 UErrorCode& status) const;
455
456 /**
457 * Set the start UDate used to interpret two-digit year strings.
458 * When dates are parsed having 2-digit year strings, they are placed within
459 * a assumed range of 100 years starting on the two digit start date. For
460 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or
461 * some other year. SimpleDateFormat chooses a year so that the resultant
462 * date is on or after the two digit start date and within 100 years of the
463 * two digit start date.
464 * <P>
465 * By default, the two digit start date is set to 80 years before the current
466 * time at which a SimpleDateFormat object is created.
467 * @param d start UDate used to interpret two-digit year strings.
468 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with
469 * an error value if there was a parse error.
470 * @stable ICU 2.0
471 */
472 virtual void set2DigitYearStart(UDate d, UErrorCode& status);
473
474 /**
475 * Get the start UDate used to interpret two-digit year strings.
476 * When dates are parsed having 2-digit year strings, they are placed within
477 * a assumed range of 100 years starting on the two digit start date. For
478 * example, the string "24-Jan-17" may be in the year 1817, 1917, 2017, or
479 * some other year. SimpleDateFormat chooses a year so that the resultant
480 * date is on or after the two digit start date and within 100 years of the
481 * two digit start date.
482 * <P>
483 * By default, the two digit start date is set to 80 years before the current
484 * time at which a SimpleDateFormat object is created.
485 * @param status Filled in with U_ZERO_ERROR if the parse was successful, and with
486 * an error value if there was a parse error.
487 * @stable ICU 2.0
488 */
489 UDate get2DigitYearStart(UErrorCode& status) const;
490
491 /**
492 * Return a pattern string describing this date format.
493 * @param result Output param to receive the pattern.
494 * @return A reference to 'result'.
495 * @stable ICU 2.0
496 */
497 virtual UnicodeString& toPattern(UnicodeString& result) const;
498
499 /**
500 * Return a localized pattern string describing this date format.
501 * In most cases, this will return the same thing as toPattern(),
502 * but a locale can specify characters to use in pattern descriptions
503 * in place of the ones described in this class's class documentation.
504 * (Presumably, letters that would be more mnemonic in that locale's
505 * language.) This function would produce a pattern using those
506 * letters.
507 *
508 * @param result Receives the localized pattern.
509 * @param status Output param set to success/failure code on
510 * exit. If the pattern is invalid, this will be
511 * set to a failure result.
512 * @return A reference to 'result'.
513 * @stable ICU 2.0
514 */
515 virtual UnicodeString& toLocalizedPattern(UnicodeString& result,
516 UErrorCode& status) const;
517
518 /**
519 * Apply the given unlocalized pattern string to this date format.
520 * (i.e., after this call, this formatter will format dates according to
521 * the new pattern)
522 *
523 * @param pattern The pattern to be applied.
524 * @stable ICU 2.0
525 */
526 virtual void applyPattern(const UnicodeString& pattern);
527
528 /**
529 * Apply the given localized pattern string to this date format.
530 * (see toLocalizedPattern() for more information on localized patterns.)
531 *
532 * @param pattern The localized pattern to be applied.
533 * @param status Output param set to success/failure code on
534 * exit. If the pattern is invalid, this will be
535 * set to a failure result.
536 * @stable ICU 2.0
537 */
538 virtual void applyLocalizedPattern(const UnicodeString& pattern,
539 UErrorCode& status);
540
541 /**
542 * Gets the date/time formatting symbols (this is an object carrying
543 * the various strings and other symbols used in formatting: e.g., month
544 * names and abbreviations, time zone names, AM/PM strings, etc.)
545 * @return a copy of the date-time formatting data associated
546 * with this date-time formatter.
547 * @stable ICU 2.0
548 */
549 virtual const DateFormatSymbols* getDateFormatSymbols(void) const;
550
551 /**
552 * Set the date/time formatting symbols. The caller no longer owns the
553 * DateFormatSymbols object and should not delete it after making this call.
554 * @param newFormatSymbols the given date-time formatting symbols to copy.
555 * @stable ICU 2.0
556 */
557 virtual void adoptDateFormatSymbols(DateFormatSymbols* newFormatSymbols);
558
559 /**
560 * Set the date/time formatting data.
561 * @param newFormatSymbols the given date-time formatting symbols to copy.
562 * @stable ICU 2.0
563 */
564 virtual void setDateFormatSymbols(const DateFormatSymbols& newFormatSymbols);
565
566 /**
567 * Return the class ID for this class. This is useful only for comparing to
568 * a return value from getDynamicClassID(). For example:
569 * <pre>
570 * . Base* polymorphic_pointer = createPolymorphicObject();
571 * . if (polymorphic_pointer->getDynamicClassID() ==
572 * . erived::getStaticClassID()) ...
573 * </pre>
574 * @return The class ID for all objects of this class.
575 * @stable ICU 2.0
576 */
577 static UClassID U_EXPORT2 getStaticClassID(void);
578
579 /**
580 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
581 * method is to implement a simple version of RTTI, since not all C++
582 * compilers support genuine RTTI. Polymorphic operator==() and clone()
583 * methods call this method.
584 *
585 * @return The class ID for this object. All objects of a
586 * given class have the same class ID. Objects of
587 * other classes have different class IDs.
588 * @stable ICU 2.0
589 */
590 virtual UClassID getDynamicClassID(void) const;
591
592 /**
593 * Set the calendar to be used by this date format. Initially, the default
594 * calendar for the specified or default locale is used. The caller should
595 * not delete the Calendar object after it is adopted by this call.
596 * Adopting a new calendar will change to the default symbols.
597 *
598 * @param calendarToAdopt Calendar object to be adopted.
599 * @stable ICU 2.0
600 */
601 virtual void adoptCalendar(Calendar* calendarToAdopt);
602
603 private:
604 friend class DateFormat;
605
606 void initializeDefaultCentury(void);
607
608 SimpleDateFormat(); // default constructor not implemented
609
610 /**
611 * Used by the DateFormat factory methods to construct a SimpleDateFormat.
612 * @param timeStyle the time style.
613 * @param dateStyle the date style.
614 * @param locale the given locale.
615 * @param status Output param set to success/failure code on
616 * exit.
617 */
618 SimpleDateFormat(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status);
619
620 /**
621 * Construct a SimpleDateFormat for the given locale. If no resource data
622 * is available, create an object of last resort, using hard-coded strings.
623 * This is an internal method, called by DateFormat. It should never fail.
624 * @param locale the given locale.
625 * @param status Output param set to success/failure code on
626 * exit.
627 */
628 SimpleDateFormat(const Locale& locale, UErrorCode& status); // Use default pattern
629
630 /**
631 * Called by format() to format a single field.
632 *
633 * @param appendTo Output parameter to receive result.
634 * Result is appended to existing contents.
635 * @param ch The format character we encountered in the pattern.
636 * @param count Number of characters in the current pattern symbol (e.g.,
637 * "yyyy" in the pattern would result in a call to this function
638 * with ch equal to 'y' and count equal to 4)
639 * @param pos The FieldPosition being filled in by the format() call. If
640 * this function is formatting the field specfied by pos, it
641 * will fill in pos with the beginning and ending offsets of the
642 * field.
643 * @param status Receives a status code, which will be U_ZERO_ERROR if the operation
644 * succeeds.
645 */
646 void subFormat( UnicodeString &appendTo,
647 UChar ch,
648 int32_t count,
649 FieldPosition& pos,
650 Calendar& cal,
651 UErrorCode& status) const; // in case of illegal argument
652
653 /**
654 * Used by subFormat() to format a numeric value.
655 * Appends to toAppendTo a string representation of "value"
656 * having a number of digits between "minDigits" and
657 * "maxDigits". Uses the DateFormat's NumberFormat.
658 *
659 * @param appendTo Output parameter to receive result.
660 * Formatted number is appended to existing contents.
661 * @param value Value to format.
662 * @param minDigits Minimum number of digits the result should have
663 * @param maxDigits Maximum number of digits the result should have
664 */
665 void zeroPaddingNumber( UnicodeString &appendTo,
666 int32_t value,
667 int32_t minDigits,
668 int32_t maxDigits) const;
669
670 /**
671 * Return true if the given format character, occuring count
672 * times, represents a numeric field.
673 */
674 static UBool isNumeric(UChar formatChar, int32_t count);
675
676 /**
677 * initializes fCalendar from parameters. Returns fCalendar as a convenience.
678 * @param adoptZone Zone to be adopted, or NULL for TimeZone::createDefault().
679 * @param locale Locale of the calendar
680 * @param status Error code
681 * @return the newly constructed fCalendar
682 */
683 Calendar *initializeCalendar(TimeZone* adoptZone, const Locale& locale, UErrorCode& status);
684
685 /**
686 * initializes fSymbols from parameters.
687 * @param locale Locale of the symbols
688 * @param calendar Alias to Calendar that will be used.
689 * @param status Error code
690 */
691 void initializeSymbols(const Locale& locale, Calendar* calendar, UErrorCode& status);
692
693 /**
694 * Called by several of the constructors to load pattern data and formatting symbols
695 * out of a resource bundle and initialize the locale based on it.
696 * @param timeStyle The time style, as passed to DateFormat::createDateInstance().
697 * @param dateStyle The date style, as passed to DateFormat::createTimeInstance().
698 * @param locale The locale to load the patterns from.
699 * @param status Filled in with an error code if loading the data from the
700 * resources fails.
701 */
702 void construct(EStyle timeStyle, EStyle dateStyle, const Locale& locale, UErrorCode& status);
703
704 /**
705 * Called by construct() and the various constructors to set up the SimpleDateFormat's
706 * Calendar and NumberFormat objects.
707 * @param locale The locale for which we want a Calendar and a NumberFormat.
708 * @param statuc Filled in with an error code if creating either subobject fails.
709 */
710 void initialize(const Locale& locale, UErrorCode& status);
711
712 /**
713 * Private code-size reduction function used by subParse.
714 * @param text the time text being parsed.
715 * @param start where to start parsing.
716 * @param field the date field being parsed.
717 * @param stringArray the string array to parsed.
718 * @param stringArrayCount the size of the array.
719 * @param cal a Calendar set to the date and time to be formatted
720 * into a date/time string.
721 * @return the new start position if matching succeeded; a negative number
722 * indicating matching failure, otherwise.
723 */
724 int32_t matchString(const UnicodeString& text, int32_t start, UCalendarDateFields field,
725 const UnicodeString* stringArray, int32_t stringArrayCount, Calendar& cal) const;
726
727 /**
728 * Private code-size reduction function used by subParse.
729 * @param text the time text being parsed.
730 * @param start where to start parsing.
731 * @param field the date field being parsed.
732 * @param stringArray the string array to parsed.
733 * @param stringArrayCount the size of the array.
734 * @param cal a Calendar set to the date and time to be formatted
735 * into a date/time string.
736 * @return the new start position if matching succeeded; a negative number
737 * indicating matching failure, otherwise.
738 */
739 int32_t matchQuarterString(const UnicodeString& text, int32_t start, UCalendarDateFields field,
740 const UnicodeString* stringArray, int32_t stringArrayCount, Calendar& cal) const;
741
742 /**
743 * Private member function that converts the parsed date strings into
744 * timeFields. Returns -start (for ParsePosition) if failed.
745 * @param text the time text to be parsed.
746 * @param start where to start parsing.
747 * @param ch the pattern character for the date field text to be parsed.
748 * @param count the count of a pattern character.
749 * @param obeyCount if true then the count is strictly obeyed.
750 * @param ambiguousYear If true then the two-digit year == the default start year.
751 * @param cal a Calendar set to the date and time to be formatted
752 * into a date/time string.
753 * @return the new start position if matching succeeded; a negative number
754 * indicating matching failure, otherwise.
755 */
756 int32_t subParse(const UnicodeString& text, int32_t& start, UChar ch, int32_t count,
757 UBool obeyCount, UBool allowNegative, UBool ambiguousYear[], Calendar& cal) const;
758
759 void parseInt(const UnicodeString& text,
760 Formattable& number,
761 ParsePosition& pos,
762 UBool allowNegative) const;
763
764 void parseInt(const UnicodeString& text,
765 Formattable& number,
766 int32_t maxDigits,
767 ParsePosition& pos,
768 UBool allowNegative) const;
769
770 /**
771 * Translate a pattern, mapping each character in the from string to the
772 * corresponding character in the to string. Return an error if the original
773 * pattern contains an unmapped character, or if a quote is unmatched.
774 * Quoted (single quotes only) material is not translated.
775 * @param originalPattern the original pattern.
776 * @param translatedPattern Output param to receive the translited pattern.
777 * @param from the characters to be translited from.
778 * @param to the characters to be translited to.
779 * @param status Receives a status code, which will be U_ZERO_ERROR
780 * if the operation succeeds.
781 */
782 static void translatePattern(const UnicodeString& originalPattern,
783 UnicodeString& translatedPattern,
784 const UnicodeString& from,
785 const UnicodeString& to,
786 UErrorCode& status);
787
788 /**
789 * Sets the starting date of the 100-year window that dates with 2-digit years
790 * are considered to fall within.
791 * @param startDate the start date
792 * @param status Receives a status code, which will be U_ZERO_ERROR
793 * if the operation succeeds.
794 */
795 void parseAmbiguousDatesAsAfter(UDate startDate, UErrorCode& status);
796
797 /**
798 * Private methods for formatting/parsing GMT string
799 */
800 void appendGMT(UnicodeString &appendTo, Calendar& cal, UErrorCode& status) const;
801 void formatGMTDefault(UnicodeString &appendTo, int32_t offset) const;
802 int32_t parseGMT(const UnicodeString &text, ParsePosition &pos) const;
803 int32_t parseGMTDefault(const UnicodeString &text, ParsePosition &pos) const;
804 UBool isDefaultGMTFormat() const;
805
806 void formatRFC822TZ(UnicodeString &appendTo, int32_t offset) const;
807
808 /**
809 * Initialize MessageFormat instances used for GMT formatting/parsing
810 */
811 void initGMTFormatters(UErrorCode &status);
812
813 /**
814 * Used to map pattern characters to Calendar field identifiers.
815 */
816 static const UCalendarDateFields fgPatternIndexToCalendarField[];
817
818 /**
819 * Map index into pattern character string to DateFormat field number
820 */
821 static const UDateFormatField fgPatternIndexToDateFormatField[];
822
823 /**
824 * The formatting pattern for this formatter.
825 */
826 UnicodeString fPattern;
827
828 /**
829 * The original locale used (for reloading symbols)
830 */
831 Locale fLocale;
832
833 /**
834 * A pointer to an object containing the strings to use in formatting (e.g.,
835 * month and day names, AM and PM strings, time zone names, etc.)
836 */
837 DateFormatSymbols* fSymbols; // Owned
838
839 /**
840 * If dates have ambiguous years, we map them into the century starting
841 * at defaultCenturyStart, which may be any date. If defaultCenturyStart is
842 * set to SYSTEM_DEFAULT_CENTURY, which it is by default, then the system
843 * values are used. The instance values defaultCenturyStart and
844 * defaultCenturyStartYear are only used if explicitly set by the user
845 * through the API method parseAmbiguousDatesAsAfter().
846 */
847 UDate fDefaultCenturyStart;
848
849 /**
850 * See documentation for defaultCenturyStart.
851 */
852 /*transient*/ int32_t fDefaultCenturyStartYear;
853
854 enum ParsedTZType {
855 TZTYPE_UNK,
856 TZTYPE_STD,
857 TZTYPE_DST
858 };
859
860 ParsedTZType tztype; // here to avoid api change
861
862 /*
863 * MessageFormat instances used for localized GMT format
864 */
865 MessageFormat **fGMTFormatters;
866
867 UBool fHaveDefaultCentury;
868 };
869
870 inline UDate
get2DigitYearStart(UErrorCode &)871 SimpleDateFormat::get2DigitYearStart(UErrorCode& /*status*/) const
872 {
873 return fDefaultCenturyStart;
874 }
875
876 inline UnicodeString&
format(const Formattable & obj,UnicodeString & appendTo,UErrorCode & status)877 SimpleDateFormat::format(const Formattable& obj,
878 UnicodeString& appendTo,
879 UErrorCode& status) const {
880 // Don't use Format:: - use immediate base class only,
881 // in case immediate base modifies behavior later.
882 return DateFormat::format(obj, appendTo, status);
883 }
884
885 inline UnicodeString&
format(UDate date,UnicodeString & appendTo,FieldPosition & fieldPosition)886 SimpleDateFormat::format(UDate date,
887 UnicodeString& appendTo,
888 FieldPosition& fieldPosition) const {
889 // Don't use Format:: - use immediate base class only,
890 // in case immediate base modifies behavior later.
891 return DateFormat::format(date, appendTo, fieldPosition);
892 }
893
894 inline UnicodeString&
format(UDate date,UnicodeString & appendTo)895 SimpleDateFormat::format(UDate date, UnicodeString& appendTo) const {
896 return DateFormat::format(date, appendTo);
897 }
898
899 U_NAMESPACE_END
900
901 #endif /* #if !UCONFIG_NO_FORMATTING */
902
903 #endif // _SMPDTFMT
904 //eof
905