Main Page   Class Hierarchy   Alphabetical List   Data Structures   File List   Data Fields   Globals  

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>

Inheritance diagram for DateFormat:

Format SimpleDateFormat

Public Types

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

enum  EStyle {
  kNone = -1, kFull = 0, kLong = 1, kMedium = 2,
  kShort = 3, kDateOffset = kShort + 1, kDateTime = 8, kDefault = kMedium,
  FULL = kFull, LONG = kLong, MEDIUM = kMedium, SHORT = kShort,
  DEFAULT = kDefault, DATE_OFFSET = kDateOffset, NONE = kNone, DATE_TIME = kDateTime
}
 Constants for various style patterns. More...


Public Methods

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 (Calendar &cal, UnicodeString &toAppendTo, FieldPosition &fieldPosition) const=0
 Formats a date into a date/time string. More...

UnicodeStringformat (UDate date, UnicodeString &toAppendTo, FieldPosition &fieldPosition) const
 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 void parse (const UnicodeString &text, Calendar &cal, ParsePosition &pos) const=0
 Parse a date/time string beginning at the given parse position. More...

UDate parse (const UnicodeString &text, ParsePosition &pos) const
 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 Methods

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 Locale * getAvailableLocales (int32_t &count)
 Gets the set of locales for which DateFormats are installed. More...


Protected Methods

 DateFormat ()
 Default constructor. More...

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

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


Protected Attributes

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();
      UDate myDate = Calendar::getNow();
      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 << df->format( myDateArr[i], myString ) << endl;
      }
To get specific fields of a date, you can use UFieldPosition to get specific fields.
 
      DateFormat* dfmt = DateFormat::createDateInstance();
      FieldPosition pos(DateFormat::YEAR_FIELD);
      UnicodeString myString;
      myString = dfmt->format( myDate, myString );
      cout << myString << endl;
      cout << pos.getBeginIndex() << "," << pos. getEndIndex() << endl;
To format a date for a different Locale, specify it in the call to createDateInstance().
 
       DateFormat* df =
           DateFormat::createDateInstance( DateFormat::SHORT, Locale::getFrance());
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


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:
ERA_FIELD  These constants are provided for backwards compatibility only, and are deprecated.

Please use the C++ style constants defined above.

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:
FULL  These constants are provided for backwards compatibility only, and are deprecated.

Please use the C++ style constants defined above.


Constructor & Destructor Documentation

virtual DateFormat::~DateFormat   [virtual]
 

Destructor.

@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


Member Function Documentation

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::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::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

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

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

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

Redeclared Format method.

@stable

Reimplemented from Format.

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'. @stable

Reimplemented in SimpleDateFormat.

UnicodeString& DateFormat::format UDate    date,
UnicodeString   toAppendTo,
FieldPosition   fieldPosition
const
 

Formats a UDate into a date/time string.

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'. @stable

Reimplemented in SimpleDateFormat.

virtual UnicodeString& DateFormat::format Calendar   cal,
UnicodeString   toAppendTo,
FieldPosition   fieldPosition
const [pure virtual]
 

Formats a date 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:
cal  a Calendar set to the date and time 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 ICU 2.1

Implemented 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()) @stable

Implements Format.

Reimplemented in SimpleDateFormat.

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

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 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 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 UBool DateFormat::isLenient void    const [virtual]
 

Returns true if the formatter is set for lenient parsing.

@stable

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

Default assignment operator.

@stable

virtual UBool DateFormat::operator== const Format   const [virtual]
 

Equality operator.

Returns true if the two formats have the same behavior. @stable

Implements Format.

Reimplemented in SimpleDateFormat.

UDate DateFormat::parse const UnicodeString   text,
ParsePosition   pos
const
 

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. @stable

Reimplemented in SimpleDateFormat.

virtual void DateFormat::parse const UnicodeString   text,
Calendar   cal,
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 ICU 2.1

Implemented in SimpleDateFormat.

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. @stable

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. @stable

Implements Format.

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 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 void DateFormat::setNumberFormat const NumberFormat   newNumberFormat [virtual]
 

Allows you to set the number formatter.

Parameters:
formatToAdopt  NumberFormat object to be adopted. @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


Field 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.

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.


The documentation for this class was generated from the following file:
Generated on Mon Mar 4 23:13:12 2002 for ICU 2.0 by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002