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
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 << df->format( myDateArr[i], myString ) << 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.
- SHORT is completely numeric, such as 12/13/52 or 3:30pm
- MEDIUM is longer, such as Jan 12, 1952
- LONG is longer, such as January 12, 1952 or 3:30:32pm
- FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST.
You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to
- Progressively parse through pieces of a string.
- Align any particular field, or find out where it is for selection on the screen.
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'.
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).
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.
virtual bool_t operator==(const Format&) const
virtual UnicodeString& format(const Formattable& obj, UnicodeString& toAppendTo, FieldPosition& pos, UErrorCode& status) const
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.
virtual UnicodeString& format( UDate date, UnicodeString& toAppendTo, FieldPosition& fieldPosition) const
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)
UnicodeString& format(UDate date, UnicodeString& result) const
result - Output param which will receive the formatted date.
UnicodeString& format(const Formattable& obj, UnicodeString& result, UErrorCode& status) const
virtual UDate parse( const UnicodeString& text, UErrorCode& status) const
status - Output param to be set to success/failure code. If
'text' cannot be parsed, it will be set to a failure
code.
@result The parsed UDate value, if successful. virtual UDate parse( const UnicodeString& text, ParsePosition& pos) const
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.
virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const
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.
static DateFormat* createInstance(void)
static DateFormat* createTimeInstance(EStyle style = kDefault, const Locale& aLocale = Locale::getDefault())
aLocale - The given locale.
static DateFormat* createDateInstance(EStyle style = kDefault, const Locale& aLocale = Locale::getDefault())
aLocale - The given locale.
static DateFormat* createDateTimeInstance(EStyle dateStyle = kDefault, EStyle timeStyle = kDefault, const Locale& aLocale = Locale::getDefault())
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.
static const Locale* getAvailableLocales(int32_t& count)
virtual bool_t isLenient(void) const
virtual void setLenient(bool_t lenient)
virtual const Calendar* getCalendar(void) const
virtual void adoptCalendar(Calendar* calendarToAdopt)
virtual void setCalendar(const Calendar& newCalendar)
virtual const NumberFormat* getNumberFormat(void) const
virtual void adoptNumberFormat(NumberFormat* formatToAdopt)
virtual void setNumberFormat(const NumberFormat& newNumberFormat)
virtual const TimeZone& getTimeZone(void) const
virtual void adoptTimeZone(TimeZone* zoneToAdopt)
virtual void setTimeZone(const TimeZone& zone)
DateFormat()
DateFormat(const DateFormat&)
DateFormat& operator=(const DateFormat&)
Calendar* fCalendar
NumberFormat* fNumberFormat
alphabetic index hierarchy of classes
this page has been generated automatically by doc++
(c)opyright by Malte Zöckler, Roland Wunderling
contact: doc++@zib.de