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 = 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.
UnicodeConverterCPP(const char* name, UErrorCode& err)
UErrorCode - Error status (I/O) IILLEGAL_ARGUMENT_ERROR will be returned if the string is empty.
If the internal program does not work correctly, for example, if there's no such codepage,
INTERNAL_PROGRAM_ERROR will be returned.
UnicodeConverterCPP(const UnicodeString& name, UErrorCode& err)
err - error status (I/O) IILLEGAL_ARGUMENT_ERROR will be returned if the string is empty. If the internal
program does not work correctly, for example, if there's no such codepage, INTERNAL_PROGRAM_ERROR will be
returned.
UnicodeConverterCPP(int32_t codepageNumber, UCNV_PLATFORM platform, UErrorCode& err)
void fromUnicodeString(char* target, int32_t& targetSize, const UnicodeString& source, UErrorCode& err) const
target - the target string in codepage encoding
targetSize - Input the number of bytes available in the "target" buffer, Output the number of bytes copied to it
err - the error status code. MEMORY_ALLOCATION_ERROR will be returned if the
the internal process buffer cannot be allocated for transcoding. ILLEGAL_ARGUMENT_ERROR
is returned if the converter is null or the source or target string is empty. void toUnicodeString(UnicodeString& target, const char* source, int32_t sourceSize, UErrorCode& err) const
target - the target string in Unicode encoding
targetSize - : I/O parameter, Input size buffer, Output # of bytes copied to it
err - the error status code MEMORY_ALLOCATION_ERROR will be returned if the
the internal process buffer cannot be allocated for transcoding. ILLEGAL_ARGUMENT_ERROR
is returned if the converter is null or the source or target string is empty. void fromUnicode(char*& target, const char* targetLimit, const UChar*& source, const UChar* sourceLimit, int32_t * offsets, bool_t flush, UErrorCode& err)
targetLimit - the pointer to the end of the target array
source - the source Unicode character array
sourceLimit - the pointer to the end of the source array
flush - TRUE if the buffer is the last buffer and the conversion will finish
in this call, FALSE otherwise. (future feature pending)
UErrorCode - the error status. ILLEGAL_ARGUMENT_ERROR will be returned if the
converter is null. void toUnicode(UChar*& target, const UChar* targetLimit, const char*& source, const char* sourceLimit, int32_t * offsets, bool_t flush, UErrorCode& err)
targetLimit - the pointer to the end of the target array
source - the source codepage character array
sourceLimit - the pointer to the end of the source array
flush - TRUE if the buffer is the last buffer and the conversion will finish
in this call, FALSE otherwise. (future feature pending)
err - the error code status ILLEGAL_ARGUMENT_ERROR will be returned if the
converter is null, targetLimit < target, sourceLimit < source int8_t getMinBytesPerChar(void) const
UCNV_TYPE getType(void) const
void getStarters(bool_t starters[256], UErrorCode& err) const
err - : an array of size 256 to be filled in
void getSubstitutionChars(char* subChars, int8_t& len, UErrorCode& err) const
len - the number of bytes of the substitution character array
err - the error status code. ILLEGAL_ARGUMENT_ERROR will be returned if
the converter is null. If the substitution character array is too small, an
INDEX_OUTOFBOUNDS_ERROR will be returned. void setSubstitutionChars(const char* subChars, int8_t len, UErrorCode& err)
len - the number of bytes of the substitution character array and upon return will contain the
number of bytes copied to that buffer
err - the error status code. ILLEGAL_ARGUMENT_ERROR if the converter is
null. or if the number of bytes provided are not in the codepage's range (e.g length 1 for ucs-2) void resetState(void)
const char* getName( UErrorCode& err) const
err - the error status code. INDEX_OUTOFBOUNDS_ERROR in the converterNameLen is too
small to contain the name. int32_t getCodepage(UErrorCode& err) const
UCNV_ToUCallBack getMissingCharAction(void) const
UCNV_FromUCallBack getMissingUnicodeAction(void) const
void setMissingCharAction(UCNV_ToUCallBack action, UErrorCode& err)
void setMissingUnicodeAction(UCNV_FromUCallBack action, UErrorCode& err)
err - the error status code void getDisplayName(const Locale& displayLocale, UnicodeString& displayName) const
displayString - a UnicodeString that is going to be filled in. UCNV_PLATFORM getCodepagePlatform(UErrorCode& err) const
static const char* const* getAvailableNames(int32_t& num, UErrorCode& err)
err - the error code status
static int32_t flushCache(void)
enum EField
ERA_FIELD
enum EStyle
FULL
virtual ~DateFormat()
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.
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