Main Page   Class Hierarchy   Compound List   File List   Header Files   Sources   Compound Members   File Members  

DateFormat Class Reference

DateFormat is an abstract class for a family of classes that convert dates and times from their internal representations to textual form and back again in a language-independent manner. More...

#include <datefmt.h>

Class diagram for DateFormat:

Format SimpleDateFormat

List of all members.


Public Members

enum  EField { kEraField, kYearField, kMonthField, kDateField, kHourOfDay1Field, kHourOfDay0Field, kMinuteField, kSecondField, kMillisecondField, kDayOfWeekField, kDayOfYearField, kDayOfWeekInMonthField, kWeekOfYearField, kWeekOfMonthField, kAmPmField, kHour1Field, kHour0Field, kTimezoneField, kYearWOYField, kDOWLocalField, ERA_FIELD, YEAR_FIELD, MONTH_FIELD, DATE_FIELD, HOUR_OF_DAY1_FIELD, HOUR_OF_DAY0_FIELD, MINUTE_FIELD, SECOND_FIELD, MILLISECOND_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_YEAR_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, WEEK_OF_YEAR_FIELD, WEEK_OF_MONTH_FIELD, AM_PM_FIELD, HOUR1_FIELD, HOUR0_FIELD, TIMEZONE_FIELD }
The following enum values are used in FieldPosition with date/time formatting. More...

enum  EStyle { kFull, kLong, kMedium, kShort, kDefault, kDateOffset, kNone, kDateTime, FULL, LONG, MEDIUM, SHORT, DEFAULT, DATE_OFFSET, NONE, DATE_TIME }
Constants for various style patterns. More...

virtual ~DateFormat ()
Destructor. More...

virtual UBool operator== (const Format&) const
Equality operator. More...

virtual UnicodeStringformat (const Formattable& obj, UnicodeString& toAppendTo, FieldPosition& pos, UErrorCode& status) const
Format an object to produce a string. More...

virtual UnicodeStringformat ( UDate date, UnicodeString& toAppendTo, FieldPosition& fieldPosition) const = 0
Formats a UDate into a date/time string. More...

UnicodeStringformat (UDate date, UnicodeString& result) const
Formats a UDate into a date/time string. More...

UnicodeStringformat (const Formattable& obj, UnicodeString& result, UErrorCode& status) const
Redeclared Format method. More...

virtual UDate parse ( const UnicodeString& text, UErrorCode& status) const
Parse a date/time string. More...

virtual UDate parse ( const UnicodeString& text, ParsePosition& pos) const = 0
Parse a date/time string beginning at the given parse position. More...

virtual void parseObject (const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const
Parse a string to produce an object. More...

virtual UBool isLenient (void) const
Returns true if the formatter is set for lenient parsing. More...

virtual void setLenient (UBool lenient)
Specify whether or not date/time parsing is to be lenient. More...

virtual const CalendargetCalendar (void) const
Gets the calendar associated with this date/time formatter. More...

virtual void adoptCalendar (Calendar* calendarToAdopt)
Set the calendar to be used by this date format. More...

virtual void setCalendar (const Calendar& newCalendar)
Set the calendar to be used by this date format. More...

virtual const NumberFormatgetNumberFormat (void) const
Gets the number formatter which this date/time formatter uses to format and parse the numeric portions of the pattern. More...

virtual void adoptNumberFormat (NumberFormat* formatToAdopt)
Allows you to set the number formatter. More...

virtual void setNumberFormat (const NumberFormat& newNumberFormat)
Allows you to set the number formatter. More...

virtual const TimeZonegetTimeZone (void) const
Returns a reference to the TimeZone used by this DateFormat's calendar. More...

virtual void adoptTimeZone (TimeZone* zoneToAdopt)
Sets the time zone for the calendar of this DateFormat object. More...

virtual void setTimeZone (const TimeZone& zone)
Sets the time zone for the calendar of this DateFormat object. More...


Static Public Members

DateFormat* createInstance (void)
Create a default date/time formatter that uses the SHORT style for both the date and the time. More...

DateFormat* createTimeInstance (EStyle style = kDefault, const Locale& aLocale = Locale::getDefault())
Creates a time formatter with the given formatting style for the given locale. More...

DateFormat* createDateInstance (EStyle style = kDefault, const Locale& aLocale = Locale::getDefault())
Creates a date formatter with the given formatting style for the given const locale. More...

DateFormat* createDateTimeInstance (EStyle dateStyle = kDefault, EStyle timeStyle = kDefault, const Locale& aLocale = Locale::getDefault())
Creates a date/time formatter with the given formatting styles for the given locale. More...

const LocalegetAvailableLocales (int32_t& count)
Gets the set of locales for which DateFormats are installed. More...


Protected Members

 DateFormat ()
Default constructor. More...

 DateFormat (const DateFormat&)
Copy constructor. More...

DateFormat& operator= (const DateFormat&)
Default assignment operator. More...

CalendarfCalendar
The calendar that DateFormat uses to produce the time field values needed to implement date/time formatting. More...

NumberFormatfNumberFormat
The number formatter that DateFormat uses to format numbers in dates and times. More...


Detailed Description

DateFormat is an abstract class for a family of classes that convert dates and times from their internal representations to textual form and back again in a language-independent manner.

Converting from the internal representation (milliseconds since midnight, January 1, 1970) to text is known as "formatting," and converting from text to millis is known as "parsing." We currently define only one concrete subclass of DateFormat: SimpleDateFormat, which can handle pretty much all normal date formatting and parsing actions.

DateFormat helps you to format and parse dates for any locale. Your code can be completely independent of the locale conventions for months, days of the week, or even the calendar format: lunar vs. solar.

To format a date for the current Locale, use one of the static factory methods:

 .    DateFormat* dfmt = DateFormat::createDateInstance();
 .    UnicodeString myString;
 .    myString = dfmt->format( myDate, myString );
 
If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.
 .    DateFormat* df = DateFormat::createDateInstance();
 .    UnicodeString myString;
 .    UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
 .    for (int32_t i = 0; i < 3; ++i) {
 .        myString.remove();
 .        cout &lt;&lt; df->format( myDateArr[i], myString ) &lt;&lt; endl;
 .    }
 
To format a date for a different Locale, specify it in the call to getDateInstance().
 .       DateFormat* df =
 .          DateFormat::createDateInstance( DateFormat::SHORT, Locale::FRANCE);
 
You can use a DateFormat to parse also.
 .       UErrorCode status = U_ZERO_ERROR;
 .       UDate myDate = df->parse(myString, status);
 
Use createDateInstance() to produce the normal date format for that country. There are other static factory methods available. Use createTimeInstance() to produce the normal time format for that country. Use createDateTimeInstance() to produce a DateFormat that formats both date and time. You can pass in different options to these factory methods to control the length of the result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the locale, but generally: You can also set the time zone on the format if you wish. If you want even more control over the format or parsing, (or want to give your users more control), you can try casting the DateFormat you get from the factory methods to a SimpleDateFormat. This will work for the majority of countries; just remember to chck getDynamicClassID() before carrying out the cast.

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to

Definition at line 100 of file datefmt.h.


Member Enumeration Documentation

enum DateFormat::EField

The following enum values are used in FieldPosition with date/time formatting.

They are also used to index into DateFormatSymbols::fgPatternChars, which is the list of standard internal-representation pattern characters, and the resource bundle localPatternChars data. For this reason, this enum should be treated with care; don't change the order or contents of it unless you really know what you are doing. You'll probably have to change the code in DateFormatSymbols, SimpleDateFormat, and all the locale resource bundle data files.

Enumeration values:
kEraField  
kYearField  
kMonthField  
kDateField  
kHourOfDay1Field  
kHourOfDay0Field  
kMinuteField  
kSecondField  
kMillisecondField  
kDayOfWeekField  
kDayOfYearField  
kDayOfWeekInMonthField  
kWeekOfYearField  
kWeekOfMonthField  
kAmPmField  
kHour1Field  
kHour0Field  
kTimezoneField  
kYearWOYField  
kDOWLocalField  
ERA_FIELD   These constants are provided for backwards compatibility only, and are deprecated.

Please use the C++ style constants defined above.

YEAR_FIELD  
MONTH_FIELD  
DATE_FIELD  
HOUR_OF_DAY1_FIELD  
HOUR_OF_DAY0_FIELD  
MINUTE_FIELD  
SECOND_FIELD  
MILLISECOND_FIELD  
DAY_OF_WEEK_FIELD  
DAY_OF_YEAR_FIELD  
DAY_OF_WEEK_IN_MONTH_FIELD  
WEEK_OF_YEAR_FIELD  
WEEK_OF_MONTH_FIELD  
AM_PM_FIELD  
HOUR1_FIELD  
HOUR0_FIELD  
TIMEZONE_FIELD  

Definition at line 112 of file datefmt.h.

enum DateFormat::EStyle

Constants for various style patterns.

These reflect the order of items in the DateTimePatterns resource. There are 4 time patterns, 4 date patterns, and then the date-time pattern. Each block of 4 values in the resource occurs in the order full, long, medium, short.

Enumeration values:
kFull  
kLong  
kMedium  
kShort  
kDefault  
kDateOffset  
kNone  
kDateTime  
FULL   These constants are provided for backwards compatibility only, and are deprecated.

Please use the C++ style constants defined above.

LONG  
MEDIUM  
SHORT  
DEFAULT  
DATE_OFFSET  
NONE  
DATE_TIME  

Definition at line 176 of file datefmt.h.


Member Function Documentation

virtual DateFormat::~DateFormat () [virtual]

Destructor.

Stable:

virtual UBool DateFormat::operator== (const Format & other) const [virtual]

Equality operator.

Returns true if the two formats have the same behavior.

Stable:

Reimplemented from Format.

Reimplemented in SimpleDateFormat.

virtual UnicodeString & DateFormat::format (const Formattable & obj, UnicodeString & toAppendTo, FieldPosition & pos, UErrorCode & status) const [virtual]

Format an object to produce a string.

This method handles Formattable objects with a UDate type. If a the Formattable object type is not a Date, then it returns a failing UErrorCode.

Parameters:
obj   The object to format. Must be a Date.
toAppendTo   The result of the formatting operation is appended to this string.
pos   On input: an alignment field, if desired. On output: the offsets of the alignment field.
status   Output param filled with success/failure status.
Returns:
The value passed in as toAppendTo (this allows chaining, as with UnicodeString::append())
Draft:

Reimplemented from Format.

Reimplemented in SimpleDateFormat.

virtual UnicodeString & DateFormat::format (UDate date, UnicodeString & toAppendTo, FieldPosition & pos) const [pure virtual]

Formats a UDate into a date/time string.

This is an abstract method which concrete subclasses must implement.

On input, the FieldPosition parameter may have its "field" member filled with an enum value specifying a field. On output, the FieldPosition will be filled in with the text offsets for that field.

For example, given a time text "1996.07.10 AD at 15:08:56 PDT", if the given fieldPosition.field is DateFormat::kYearField, the offsets fieldPosition.beginIndex and statfieldPositionus.getEndIndex will be set to 0 and 4, respectively.

Notice that if the same time field appears more than once in a pattern, the status will be set for the first occurence of that time field. For instance, formatting a UDate to the time string "1 PM PDT (Pacific Daylight Time)" using the pattern "h a z (zzzz)" and the alignment field DateFormat::TIMEZONE_FIELD, the offsets fieldPosition.beginIndex and fieldPosition.getEndIndex will be set to 5 and 8, respectively, for the first occurence of the timezone pattern character 'z'.

Parameters:
date   a UDate to be formatted into a date/time string.
toAppendTo   the result of the formatting operation is appended to the end of this string.
fieldPosition   On input: an alignment field, if desired (see examples above) On output: the offsets of the alignment field (see examples above)
Returns:
A reference to 'toAppendTo'.
Draft:

Reimplemented in SimpleDateFormat.

UnicodeString & DateFormat::format (UDate date, UnicodeString & result) const

Formats a UDate into a date/time string.

If there is a problem, you won't know, using this method. Use the overloaded format() method which takes a FieldPosition& to detect formatting problems.

Parameters:
date   The UDate value to be formatted into a string.
result   Output param which will receive the formatted date.
Returns:
A reference to 'result'.
Draft:

Reimplemented in SimpleDateFormat.

UnicodeString & DateFormat::format (const Formattable & obj, UnicodeString & result, UErrorCode & status) const [inline]

Redeclared Format method.

Draft:

Reimplemented from Format.

Reimplemented in SimpleDateFormat.

Definition at line 557 of file datefmt.h.

virtual UDate DateFormat::parse (const UnicodeString & text, UErrorCode & status) const [virtual]

Parse a date/time string.

Parameters:
text   The string to be parsed into a UDate value.
status   Output param to be set to success/failure code. If 'text' cannot be parsed, it will be set to a failure code.
Returns:
The parsed UDate value, if successful.
Draft:

Reimplemented in SimpleDateFormat.

virtual UDate DateFormat::parse (const UnicodeString & text, ParsePosition & pos) const [pure virtual]

Parse a date/time string beginning at the given parse position.

For example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date that is equivalent to Date(837039928046).

By default, parsing is lenient: If the input is not in the form used by this object's format method but can still be parsed as a date, then the parse succeeds. Clients may insist on strict adherence to the format by calling setLenient(false).

See also:
DateFormat::setLenient(boolean)

Parameters:
text   The date/time string to be parsed
pos   On input, the position at which to start parsing; on output, the position at which parsing terminated, or the start position if the parse failed.
Returns:
A valid UDate if the input could be parsed.
Draft:

Reimplemented in SimpleDateFormat.

virtual void DateFormat::parseObject (const UnicodeString & source, Formattable & result, ParsePosition & parse_pos) const [virtual]

Parse a string to produce an object.

This methods handles parsing of date/time strings into Formattable objects with UDate types.

Before calling, set parse_pos.index to the offset you want to start parsing at in the source. After calling, parse_pos.index is the end of the text you parsed. If error occurs, index is unchanged.

When parsing, leading whitespace is discarded (with a successful parse), while trailing whitespace is left as is.

See Format::parseObject() for more.

Parameters:
source   The string to be parsed into an object.
result   Formattable to be set to the parse result. If parse fails, return contents are undefined.
parse_pos   The position to start parsing at. Upon return this param is set to the position after the last character successfully parsed. If the source is not parsed successfully, this param will remain unchanged.
Returns:
A newly created Formattable* object, or NULL on failure. The caller owns this and should delete it when done.
Draft:

Reimplemented from Format.

virtual UBool DateFormat::isLenient (void) const [virtual]

Returns true if the formatter is set for lenient parsing.

Stable:

virtual void DateFormat::setLenient (UBool lenient) [virtual]

Specify whether or not date/time parsing is to be lenient.

With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match this object's format. With strict parsing, inputs must match this object's format.

See also:
Calendar::setLenient()
Stable:

virtual const Calendar * DateFormat::getCalendar (void) const [virtual]

Gets the calendar associated with this date/time formatter.

Returns:
the calendar associated with this date/time formatter.
Stable:

virtual void DateFormat::adoptCalendar (Calendar * calendarToAdopt) [virtual]

Set the calendar to be used by this date format.

Initially, the default calendar for the specified or default locale is used. The caller should not delete the Calendar object after it is adopted by this call.

Stable:

virtual void DateFormat::setCalendar (const Calendar & newCalendar) [virtual]

Set the calendar to be used by this date format.

Initially, the default calendar for the specified or default locale is used.

Stable:

virtual const NumberFormat * DateFormat::getNumberFormat (void) const [virtual]

Gets the number formatter which this date/time formatter uses to format and parse the numeric portions of the pattern.

Returns:
the number formatter which this date/time formatter uses.
Stable:

virtual void DateFormat::adoptNumberFormat (NumberFormat * formatToAdopt) [virtual]

Allows you to set the number formatter.

The caller should not delete the NumberFormat object after it is adopted by this call.

Parameters:
formatToAdopt   NumberFormat object to be adopted.
Stable:

virtual void DateFormat::setNumberFormat (const NumberFormat & newNumberFormat) [virtual]

Allows you to set the number formatter.

Parameters:
formatToAdopt   NumberFormat object to be adopted.
Stable:

virtual const TimeZone & DateFormat::getTimeZone (void) const [virtual]

Returns a reference to the TimeZone used by this DateFormat's calendar.

Returns:
the time zone associated with the calendar of DateFormat.
Stable:

virtual void DateFormat::adoptTimeZone (TimeZone * zoneToAdopt) [virtual]

Sets the time zone for the calendar of this DateFormat object.

The caller no longer owns the TimeZone object and should not delete it after this call.

Parameters:
zone   the new time zone.
Stable:

virtual void DateFormat::setTimeZone (const TimeZone & zone) [virtual]

Sets the time zone for the calendar of this DateFormat object.

Parameters:
zone   the new time zone.
Stable:

DateFormat * DateFormat::createInstance (void) [static]

Create a default date/time formatter that uses the SHORT style for both the date and the time.

Returns:
A date/time formatter which the caller owns.
Stable:

DateFormat * DateFormat::createTimeInstance (EStyle style = kDefault, const Locale & aLocale = Locale::getDefault()) [static]

Creates a time formatter with the given formatting style for the given locale.

Parameters:
style   The given formatting style. For example, SHORT for "h:mm a" in the US locale.
aLocale   The given locale.
Returns:
A time formatter which the caller owns.
Stable:

DateFormat * DateFormat::createDateInstance (EStyle style = kDefault, const Locale & aLocale = Locale::getDefault()) [static]

Creates a date formatter with the given formatting style for the given const locale.

Parameters:
style   The given formatting style. For example, SHORT for "M/d/yy" in the US locale.
aLocale   The given locale.
Returns:
A date formatter which the caller owns.
Stable:

DateFormat * DateFormat::createDateTimeInstance (EStyle dateStyle = kDefault, EStyle timeStyle = kDefault, const Locale & aLocale = Locale::getDefault()) [static]

Creates a date/time formatter with the given formatting styles for the given locale.

Parameters:
dateStyle   The given formatting style for the date portion of the result. For example, SHORT for "M/d/yy" in the US locale.
timeStyle   The given formatting style for the time portion of the result. For example, SHORT for "h:mm a" in the US locale.
aLocale   The given locale.
Returns:
A date/time formatter which the caller owns.
Stable:

const Locale * DateFormat::getAvailableLocales (int32_t & count) [static]

Gets the set of locales for which DateFormats are installed.

Parameters:
count   Filled in with the number of locales in the list that is returned.
Returns:
the set of locales for which DateFormats are installed. The caller does NOT own this list and must not delete it.
Stable:

DateFormat::DateFormat () [protected]

Default constructor.

Creates a DateFormat with no Calendar or NumberFormat associated with it. This constructor depends on the subclasses to fill in the calendar and numberFormat fields.

Stable:

DateFormat::DateFormat (const DateFormat &) [protected]

Copy constructor.

Stable:

DateFormat & DateFormat::operator= (const DateFormat &) [protected]

Default assignment operator.

Stable:

Member Data Documentation

Calendar* DateFormat::fCalendar [protected]

The calendar that DateFormat uses to produce the time field values needed to implement date/time formatting.

Subclasses should generally initialize this to the default calendar for the locale associated with this DateFormat.

Definition at line 523 of file datefmt.h.

NumberFormat* DateFormat::fNumberFormat [protected]

The number formatter that DateFormat uses to format numbers in dates and times.

Subclasses should generally initialize this to the default number format for the locale associated with this DateFormat.

Definition at line 530 of file datefmt.h.


The documentation for this class was generated from the following file:
Generated at Mon Jun 5 12:53:13 2000 for ICU1.5 by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999