Logo Search packages:      
Sourcecode: icu version File versions

SimpleDateFormat Class Reference

#include <smpdtfmt.h>

Inheritance diagram for SimpleDateFormat:

DateFormat Format UObject UMemory

List of all members.

Detailed Description

SimpleDateFormat is a concrete class for formatting and parsing dates in a language-independent manner. It allows for formatting (millis -> text), parsing (text -> millis), and normalization. Formats/Parses a date or time, which is the standard milliseconds since 24:00 GMT, Jan 1, 1970.

Clients are encouraged to create a date-time formatter using DateFormat::getInstance(), getDateInstance(), getDateInstance(), or getDateTimeInstance() rather than explicitly constructing an instance of SimpleDateFormat. This way, the client is guaranteed to get an appropriate formatting pattern for whatever locale the program is running in. However, if the client needs something more unusual than the default patterns in the locales, he can construct a SimpleDateFormat directly and give it an appropriate pattern (or use one of the factory methods on DateFormat and modify the pattern after the fact with toPattern() and applyPattern().

Date/Time format syntax:

The date/time format is specified by means of a string time pattern. In this pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

 Symbol   Meaning                 Presentation        Example
 ------   -------                 ------------        -------
 G        era designator          (Text)              AD
 y        year                    (Number)            1996
 Y        year (week of year)     (Number)            1997
 u        extended year           (Number)            4601
 Q        Quarter                 (Text & Number)     Q2 & 02
 M        month in year           (Text & Number)     July & 07
 d        day in month            (Number)            10
 h        hour in am/pm (1~12)    (Number)            12
 H        hour in day (0~23)      (Number)            0
 m        minute in hour          (Number)            30
 s        second in minute        (Number)            55
 S        fractional second       (Number)            978
 E        day of week             (Text)              Tuesday
 e        day of week (local 1~7) (Text & Number)     Tues & 2
 D        day in year             (Number)            189
 F        day of week in month    (Number)            2 (2nd Wed in July)
 w        week in year            (Number)            27
 W        week in month           (Number)            2
 a        am/pm marker            (Text)              PM
 k        hour in day (1~24)      (Number)            24
 K        hour in am/pm (0~11)    (Number)            0
 z        time zone               (Time)              Pacific Standard Time
 Z        time zone (RFC 822)     (Number)            -0800
 v        time zone (generic)     (Text)              Pacific Time
 V        time zone (abreviation) (Text)              PT
 VVVV     time zone (location)    (Text)              United States (Los Angeles)
 g        Julian day              (Number)            2451334
 A        milliseconds in day     (Number)            69540000
 q        stand alone quarter     (Text & Number)     Q2 & 02
 L        stand alone month       (Text & Number)     July & 07
 c        stand alone day of week (Text & Number)     Tuesday & 2
 '        escape for text         (Delimiter)         'Date='
 ''       single quote            (Literal)           'o''clock'
The count of pattern letters determine the format.

(Text): 4 or more, use full form, <4, use short or abbreviated form if it exists. (e.g., "EEEE" produces "Monday", "EEE" produces "Mon")

(Number): the minimum number of digits. Shorter numbers are zero-padded to this amount (e.g. if "m" produces "6", "mm" produces "06"). Year is handled specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits. (e.g., if "yyyy" produces "1997", "yy" produces "97".) Unlike other fields, fractional seconds are padded on the right with zero.

(Text & Number): 3 or over, use text, otherwise use number. (e.g., "M" produces "1", "MM" produces "01", "MMM" produces "Jan", and "MMMM" produces "January".)

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not embraced within single quotes.

A pattern containing any invalid pattern letter will result in a failing UErrorCode result during formatting or parsing.

Examples using the US locale:

    Format Pattern                         Result
    --------------                         -------
    "yyyy.MM.dd G 'at' HH:mm:ss vvvv" ->>  1996.07.10 AD at 15:08:56 Pacific Time
    "EEE, MMM d, ''yy"                ->>  Wed, July 10, '96
    "h:mm a"                          ->>  12:08 PM
    "hh 'o''clock' a, zzzz"           ->>  12 o'clock PM, Pacific Daylight Time
    "K:mm a, vvv"                     ->>  0:00 PM, PT
    "yyyyy.MMMMM.dd GGG hh:mm aaa"    ->>  1996.July.10 AD 12:08 PM
Code Sample:
     UErrorCode success = U_ZERO_ERROR;
     SimpleTimeZone* pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST");
     pdt->setStartRule( Calendar::APRIL, 1, Calendar::SUNDAY, 2*60*60*1000);
     pdt->setEndRule( Calendar::OCTOBER, -1, Calendar::SUNDAY, 2*60*60*1000);

     // Format the current time.
     SimpleDateFormat* formatter
         = new SimpleDateFormat ("yyyy.MM.dd G 'at' hh:mm:ss a zzz", success );
     GregorianCalendar cal(success);
     UDate currentTime_1 = cal.getTime(success);
     FieldPosition fp(0);
     UnicodeString dateString;
     formatter->format( currentTime_1, dateString, fp );
     cout << "result: " << dateString << endl;

     // Parse the previous string back into a Date.
     ParsePosition pp(0);
     UDate currentTime_2 = formatter->parse(dateString, pp );
In the above example, the time value "currentTime_2" obtained from parsing will be equal to currentTime_1. However, they may not be equal if the am/pm marker 'a' is left out from the format pattern while the "hour in am/pm" pattern symbol is used. This information loss can happen when formatting the time in PM.

When parsing a date string using the abbreviated year pattern ("y" or "yy"), SimpleDateFormat must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 80 years before and 20 years after the time the SimpleDateFormat instance is created. For example, using a pattern of "MM/dd/yy" and a SimpleDateFormat instance created on Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only strings consisting of exactly two digits, as defined by Unicode::isDigit(), will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits (for example, "-1"), is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC.

If the year pattern has more than two 'y' characters, the year is interpreted literally, regardless of the number of digits. So using the pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.

When numeric fields abut one another directly, with no intervening delimiter characters, they constitute a run of abutting numeric fields. Such runs are parsed specially. For example, the format "HHmmss" parses the input text "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to parse "1234". In other words, the leftmost field of the run is flexible, while the others keep a fixed width. If the parse fails anywhere in the run, then the leftmost field is shortened by one character, and the entire run is parsed again. This is repeated until either the parse succeeds or the leftmost field is one character in length. If the parse still fails at that point, the parse of the run fails.

For time zones that have no names, SimpleDateFormat uses strings GMT+hours:minutes or GMT-hours:minutes.

The calendar defines what is the first day of the week, the first week of the year, whether hours are zero based or not (0 vs 12 or 24), and the timezone. There is one common number format to handle all the numbers; the digit count is handled programmatically according to the pattern.

User subclasses are not supported. While clients may write subclasses, such code will not necessarily work and will not be guaranteed to work stably from release to release.

Definition at line 213 of file smpdtfmt.h.

Public Types

enum  EField {
  kEraField = UDAT_ERA_FIELD, kYearField = UDAT_YEAR_FIELD, kMonthField = UDAT_MONTH_FIELD, kDateField = UDAT_DATE_FIELD,
  kHourOfDay1Field = UDAT_HOUR_OF_DAY1_FIELD, kHourOfDay0Field = UDAT_HOUR_OF_DAY0_FIELD, kMinuteField = UDAT_MINUTE_FIELD, kSecondField = UDAT_SECOND_FIELD,
enum  EStyle {
  kNone = -1, kFull = 0, kLong = 1, kMedium = 2,
  kShort = 3, kDateOffset = kShort + 1, kDateTime = 8, kDateTimeOffset = kDateTime + 1,
  kRelative = (1 << 7), kFullRelative = (kFull | kRelative), kLongRelative = kLong | kRelative, kMediumRelative = kMedium | kRelative,
  kShortRelative = kShort | kRelative, kDefault = kMedium, FULL = kFull, LONG = kLong,
  MEDIUM = kMedium, SHORT = kShort, DEFAULT = kDefault, DATE_OFFSET = kDateOffset,
  NONE = kNone, DATE_TIME = kDateTime

Public Member Functions

virtual void adoptCalendar (Calendar *calendarToAdopt)
virtual void adoptDateFormatSymbols (DateFormatSymbols *newFormatSymbols)
virtual void adoptNumberFormat (NumberFormat *formatToAdopt)
virtual void adoptTimeZone (TimeZone *zoneToAdopt)
virtual void applyLocalizedPattern (const UnicodeString &pattern, UErrorCode &status)
virtual void applyPattern (const UnicodeString &pattern)
virtual Formatclone (void) const
UnicodeStringformat (UDate date, UnicodeString &appendTo) const
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
UnicodeStringformat (UDate date, UnicodeString &appendTo, FieldPosition &fieldPosition) const
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
virtual UnicodeStringformat (Calendar &cal, UnicodeString &appendTo, FieldPosition &pos) const
UDate get2DigitYearStart (UErrorCode &status) const
virtual const CalendargetCalendar (void) const
virtual const DateFormatSymbolsgetDateFormatSymbols (void) const
virtual UClassID getDynamicClassID (void) const
Locale getLocale (ULocDataLocaleType type, UErrorCode &status) const
const char * getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
virtual const NumberFormatgetNumberFormat (void) const
const LocalegetSmpFmtLocale (void) const
virtual const TimeZonegetTimeZone (void) const
UBool isFieldUnitIgnored (UCalendarDateFields field) const
virtual UBool isLenient (void) const
UBool operator!= (const Format &other) const
SimpleDateFormatoperator= (const SimpleDateFormat &)
virtual UBool operator== (const Format &other) const
virtual UDate parse (const UnicodeString &text, UErrorCode &status) const
UDate parse (const UnicodeString &text, ParsePosition &pos) const
virtual void parse (const UnicodeString &text, Calendar &cal, ParsePosition &pos) const
void parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
virtual void parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const
virtual void set2DigitYearStart (UDate d, UErrorCode &status)
virtual void setCalendar (const Calendar &newCalendar)
virtual void setDateFormatSymbols (const DateFormatSymbols &newFormatSymbols)
virtual void setLenient (UBool lenient)
virtual void setNumberFormat (const NumberFormat &newNumberFormat)
virtual void setTimeZone (const TimeZone &zone)
 SimpleDateFormat (const SimpleDateFormat &)
 SimpleDateFormat (const UnicodeString &pattern, const DateFormatSymbols &formatData, UErrorCode &status)
 SimpleDateFormat (const UnicodeString &pattern, DateFormatSymbols *formatDataToAdopt, UErrorCode &status)
 SimpleDateFormat (const UnicodeString &pattern, const UnicodeString &override, const Locale &locale, UErrorCode &status)
 SimpleDateFormat (const UnicodeString &pattern, const Locale &locale, UErrorCode &status)
 SimpleDateFormat (const UnicodeString &pattern, const UnicodeString &override, UErrorCode &status)
 SimpleDateFormat (const UnicodeString &pattern, UErrorCode &status)
 SimpleDateFormat (UErrorCode &status)
virtual UnicodeStringtoLocalizedPattern (UnicodeString &result, UErrorCode &status) const
virtual UnicodeStringtoPattern (UnicodeString &result) const
virtual ~SimpleDateFormat ()

Static Public Member Functions

static DateFormat *U_EXPORT2 createDateInstance (EStyle style=kDefault, const Locale &aLocale=Locale::getDefault())
static DateFormat *U_EXPORT2 createDateTimeInstance (EStyle dateStyle=kDefault, EStyle timeStyle=kDefault, const Locale &aLocale=Locale::getDefault())
static DateFormat *U_EXPORT2 createInstance (void)
static DateFormat *U_EXPORT2 createTimeInstance (EStyle style=kDefault, const Locale &aLocale=Locale::getDefault())
static const Locale *U_EXPORT2 getAvailableLocales (int32_t &count)
static UClassID U_EXPORT2 getStaticClassID (void)
static UBool isFieldUnitIgnored (const UnicodeString &pattern, UCalendarDateFields field)
static void U_EXPORT2 operator delete (void *, void *) U_NO_THROW
static void U_EXPORT2 operator delete (void *p) U_NO_THROW
static void U_EXPORT2 operator delete[] (void *p) U_NO_THROW
static void *U_EXPORT2 operator new (size_t, void *ptr) U_NO_THROW
static void *U_EXPORT2 operator new (size_t size) U_NO_THROW
static void *U_EXPORT2 operator new[] (size_t size) U_NO_THROW

Protected Member Functions

void setLocaleIDs (const char *valid, const char *actual)

Static Protected Member Functions

static void syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)

Protected Attributes


Private Types

enum  {
  kGMTNegativeHMS = 0, kGMTNegativeHM, kGMTPositiveHMS, kGMTPositiveHM,
enum  { kGMTNegativeHMSMinLenIdx = 0, kGMTPositiveHMSMinLenIdx, kNumGMTFormatMinLengths }
typedef struct

Private Member Functions

void appendGMT (NumberFormat *currentNumberFormat, UnicodeString &appendTo, Calendar &cal, UErrorCode &status) const
int32_t checkIntSuffix (const UnicodeString &text, int32_t start, int32_t patLoc, UBool isNegative) const
int32_t compareSimpleAffix (const UnicodeString &affix, const UnicodeString &input, int32_t pos) const
void construct (EStyle timeStyle, EStyle dateStyle, const Locale &locale, UErrorCode &status)
void formatGMTDefault (NumberFormat *currentNumberFormat, UnicodeString &appendTo, int32_t offset) const
void formatRFC822TZ (UnicodeString &appendTo, int32_t offset) const
NumberFormatgetNumberFormat (UDateFormatField index) const
void initGMTFormatters (UErrorCode &status)
void initialize (const Locale &locale, UErrorCode &status)
CalendarinitializeCalendar (TimeZone *adoptZone, const Locale &locale, UErrorCode &status)
void initializeDefaultCentury (void)
void initializeSymbols (const Locale &locale, Calendar *calendar, UErrorCode &status)
void initNumberFormatters (const Locale &locale, UErrorCode &status)
UBool isDefaultGMTFormat () const
int32_t matchQuarterString (const UnicodeString &text, int32_t start, UCalendarDateFields field, const UnicodeString *stringArray, int32_t stringArrayCount, Calendar &cal) const
int32_t matchString (const UnicodeString &text, int32_t start, UCalendarDateFields field, const UnicodeString *stringArray, int32_t stringArrayCount, Calendar &cal) const
void parseAmbiguousDatesAsAfter (UDate startDate, UErrorCode &status)
int32_t parseGMT (const UnicodeString &text, ParsePosition &pos) const
int32_t parseGMTDefault (const UnicodeString &text, ParsePosition &pos) const
void parseInt (const UnicodeString &text, Formattable &number, int32_t maxDigits, ParsePosition &pos, UBool allowNegative, NumberFormat *fmt) const
void parseInt (const UnicodeString &text, Formattable &number, ParsePosition &pos, UBool allowNegative, NumberFormat *fmt) const
void processOverrideString (const Locale &locale, const UnicodeString &str, int8_t type, UErrorCode &status)
 SimpleDateFormat (const Locale &locale, UErrorCode &status)
 SimpleDateFormat (EStyle timeStyle, EStyle dateStyle, const Locale &locale, UErrorCode &status)
int32_t skipRuleWhiteSpace (const UnicodeString &text, int32_t pos) const
int32_t skipUWhiteSpace (const UnicodeString &text, int32_t pos) const
void subFormat (UnicodeString &appendTo, UChar ch, int32_t count, FieldPosition &pos, Calendar &cal, UErrorCode &status) const
int32_t subParse (const UnicodeString &text, int32_t &start, UChar ch, int32_t count, UBool obeyCount, UBool allowNegative, UBool ambiguousYear[], Calendar &cal, int32_t patLoc) const
void zeroPaddingNumber (NumberFormat *currentNumberFormat, UnicodeString &appendTo, int32_t value, int32_t minDigits, int32_t maxDigits) const

Static Private Member Functions

static UBool isNumeric (UChar formatChar, int32_t count)
static void translatePattern (const UnicodeString &originalPattern, UnicodeString &translatedPattern, const UnicodeString &from, const UnicodeString &to, UErrorCode &status)

Private Attributes

UnicodeString fDateOverride
UDate fDefaultCenturyStart
int32_t fDefaultCenturyStartYear
int32_t fGMTFormatHmsMinLen [kNumGMTFormatMinLengths]
MessageFormat ** fGMTFormatters
UBool fHaveDefaultCentury
Locale fLocale
NumberFormat ** fNumberFormatters
NSOverride * fOverrideList
UnicodeString fPattern
UnicodeString fTimeOverride
ParsedTZType tztype

Static Private Attributes

static const int32_t fgCalendarFieldToLevel []
static const int32_t fgPatternCharToLevel []
static const UCalendarDateFields fgPatternIndexToCalendarField []
static const UDateFormatField fgPatternIndexToDateFormatField []


class DateFormat


struct  NSOverride

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index