class DateTimePatternGenerator

Defined at line 58 of file ../../third_party/icu/latest/source/i18n/unicode/dtptngen.h

This class provides flexible generation of date format patterns, like "yy-MM-dd".

The user can build up the generator by adding successive patterns. Once that

is done, a query can be made using a "skeleton", which is a pattern which just

includes the desired fields and lengths. The generator will return the "best fit"

pattern corresponding to that skeleton.

The main method people will use is getBestPattern(String skeleton),

since normally this class is pre-built with data from a particular locale.

However, generators can be built directly from other data as well.

Issue: may be useful to also have a function that returns the list of

fields in a pattern, in order, since we have that internally.

That would be useful for getting the UI order of field elements.

ICU 3.8

Public Methods

DateTimePatternGenerator * createInstance (UErrorCode & status)

Construct a flexible generator according to default locale.

Parameters

status Output param set to success/failure code on exit, which must not indicate a failure before the function call. ICU 3.8

DateTimePatternGenerator * createInstance (const Locale & uLocale, UErrorCode & status)

Construct a flexible generator according to data for a given locale.

Parameters

status Output param set to success/failure code on exit, which must not indicate a failure before the function call. ICU 3.8

DateTimePatternGenerator * createInstanceNoStdPat (const Locale & uLocale, UErrorCode & status)

For ICU use only. Skips loading the standard date/time patterns (which is done via DateFormat).

DateTimePatternGenerator * createEmptyInstance (UErrorCode & status)

Create an empty generator, to be constructed with addPattern(...) etc.

Parameters

status Output param set to success/failure code on exit, which must not indicate a failure before the function call. ICU 3.8

void ~DateTimePatternGenerator ()

Destructor.

ICU 3.8

DateTimePatternGenerator * clone ()

Clone DateTimePatternGenerator object. Clients are responsible for

deleting the DateTimePatternGenerator object cloned.

ICU 3.8

bool operator== (const DateTimePatternGenerator & other)

Return true if another object is semantically equal to this one.

Parameters

other the DateTimePatternGenerator object to be compared with.

Returns

true if other is semantically equal to this.

ICU 3.8

bool operator!= (const DateTimePatternGenerator & other)

Return true if another object is semantically unequal to this one.

Parameters

other the DateTimePatternGenerator object to be compared with.

Returns

true if other is semantically unequal to this.

ICU 3.8

UnicodeString staticGetSkeleton (const UnicodeString & pattern, UErrorCode & status)

Utility to return a unique skeleton from a given pattern. For example,

both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".

Parameters

pattern Input pattern, such as "dd/MMM"

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

skeleton such as "MMMdd"

ICU 56

UnicodeString getSkeleton (const UnicodeString & pattern, UErrorCode & status)

Utility to return a unique skeleton from a given pattern. For example,

both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".

getSkeleton() works exactly like staticGetSkeleton().

Use staticGetSkeleton() instead of getSkeleton().

Parameters

pattern Input pattern, such as "dd/MMM"

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

skeleton such as "MMMdd"

ICU 3.8

UnicodeString staticGetBaseSkeleton (const UnicodeString & pattern, UErrorCode & status)

Utility to return a unique base skeleton from a given pattern. This is

the same as the skeleton, except that differences in length are minimized

so as to only preserve the difference between string and numeric form. So

for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"

(notice the single d).

Parameters

pattern Input pattern, such as "dd/MMM"

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

base skeleton, such as "MMMd"

ICU 56

UnicodeString getBaseSkeleton (const UnicodeString & pattern, UErrorCode & status)

Utility to return a unique base skeleton from a given pattern. This is

the same as the skeleton, except that differences in length are minimized

so as to only preserve the difference between string and numeric form. So

for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"

(notice the single d).

getBaseSkeleton() works exactly like staticGetBaseSkeleton().

Use staticGetBaseSkeleton() instead of getBaseSkeleton().

Parameters

pattern Input pattern, such as "dd/MMM"

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

base skeleton, such as "MMMd"

ICU 3.8

UDateTimePatternConflict addPattern (const UnicodeString & pattern, UBool override, UnicodeString & conflictingPattern, UErrorCode & status)

Adds a pattern to the generator. If the pattern has the same skeleton as

an existing pattern, and the override parameter is set, then the previous

value is overridden. Otherwise, the previous value is retained. In either

case, the conflicting status is set and previous vale is stored in

conflicting pattern.

Note that single-field patterns (like "MMM") are automatically added, and

don't need to be added explicitly!

Parameters

pattern Input pattern, such as "dd/MMM"

override When existing values are to be overridden use true, otherwise use false.

conflictingPattern Previous pattern with the same skeleton.

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

conflicting status. The value could be UDATPG_NO_CONFLICT,

UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.

ICU 3.8

void setAppendItemFormat (UDateTimePatternField field, const UnicodeString & value)

An AppendItem format is a pattern used to append a field if there is no

good match. For example, suppose that the input skeleton is "GyyyyMMMd",

and there is no matching pattern internally, but there is a pattern

matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the

G. The way these two are conjoined is by using the AppendItemFormat for G

(era). So if that value is, say "{0}, {1}" then the final resulting

pattern is "d-MM-yyyy, G".

There are actually three available variables: {0} is the pattern so far,

{1} is the element we are adding, and {2} is the name of the element.

This reflects the way that the CLDR data is organized.

Parameters

field such as UDATPG_ERA_FIELD.

value pattern, such as "{0}, {1}" ICU 3.8

const UnicodeString & getAppendItemFormat (UDateTimePatternField field)

Getter corresponding to setAppendItemFormat. Values below 0 or at or

above UDATPG_FIELD_COUNT are illegal arguments.

Parameters

field such as UDATPG_ERA_FIELD.

Returns

append pattern for field

ICU 3.8

void setAppendItemName (UDateTimePatternField field, const UnicodeString & value)

Sets the names of field, eg "era" in English for ERA. These are only

used if the corresponding AppendItemFormat is used, and if it contains a

{2} variable.

This reflects the way that the CLDR data is organized.

Parameters

field such as UDATPG_ERA_FIELD.

value name of the field ICU 3.8

const UnicodeString & getAppendItemName (UDateTimePatternField field)

Getter corresponding to setAppendItemNames. Values below 0 or at or above

UDATPG_FIELD_COUNT are illegal arguments. Note: The more general method

for getting date/time field display names is getFieldDisplayName.

Parameters

field such as UDATPG_ERA_FIELD.

Returns

name for field

UnicodeString getFieldDisplayName (UDateTimePatternField field, UDateTimePGDisplayWidth width)

The general interface to get a display name for a particular date/time field,

in one of several possible display widths.

Parameters

field The desired UDateTimePatternField, such as UDATPG_ERA_FIELD.

width The desired UDateTimePGDisplayWidth, such as UDATPG_ABBREVIATED.

Returns

The display name for field

ICU 61

void setDateTimeFormat (const UnicodeString & dateTimeFormat)

The DateTimeFormat is a message format pattern used to compose date and

time patterns. The default pattern in the root locale is "{1} {0}", where

{1} will be replaced by the date pattern and {0} will be replaced by the

time pattern; however, other locales may specify patterns such as

"{1}, {0}" or "{1} 'at' {0}", etc.

This is used when the input skeleton contains both date and time fields,

but there is not a close match among the added patterns. For example,

suppose that this object was created by adding "dd-MMM" and "hh:mm", and

its datetimeFormat is the default "{1} {0}". Then if the input skeleton

is "MMMdhmm", there is not an exact match, so the input skeleton is

broken up into two components "MMMd" and "hmm". There are close matches

for those two skeletons, so the result is put together with this pattern,

resulting in "d-MMM h:mm".

There are four DateTimeFormats in a DateTimePatternGenerator object,

corresponding to date styles UDAT_FULL..UDAT_SHORT. This method sets

all of them to the specified pattern. To set them individually, see

setDateTimeFormat(UDateFormatStyle style, ...).

Parameters

dateTimeFormat message format pattern, here {1} will be replaced by the date pattern and {0} will be replaced by the time pattern. ICU 3.8

const UnicodeString & getDateTimeFormat ()

Getter corresponding to setDateTimeFormat.

There are four DateTimeFormats in a DateTimePatternGenerator object,

corresponding to date styles UDAT_FULL..UDAT_SHORT. This method gets

the style for UDAT_MEDIUM (the default). To get them individually, see

getDateTimeFormat(UDateFormatStyle style).

Returns

DateTimeFormat.

ICU 3.8

void setDateTimeFormat (UDateFormatStyle style, const UnicodeString & dateTimeFormat, UErrorCode & status)

dateTimeFormats are message patterns used to compose combinations of date

and time patterns. There are four length styles, corresponding to the

inferred style of the date pattern; these are UDateFormatStyle values:

- UDAT_FULL (for date pattern with weekday and long month), else

- UDAT_LONG (for a date pattern with long month), else

- UDAT_MEDIUM (for a date pattern with abbreviated month), else

- UDAT_SHORT (for any other date pattern).

For details on dateTimeFormats, see

https://www.unicode.org/reports/tr35/tr35-dates.html#dateTimeFormats.

The default pattern in the root locale for all styles is "{1} {0}".

Parameters

style one of DateFormat.FULL..DateFormat.SHORT. Error if out of range.

dateTimeFormat the new dateTimeFormat to set for the the specified style

status in/out parameter; if no failure status is already set, it will be set according to result of the function (e.g. U_ILLEGAL_ARGUMENT_ERROR for style out of range). ICU 71

const UnicodeString & getDateTimeFormat (UDateFormatStyle style, UErrorCode & status)

Getter corresponding to setDateTimeFormat.

Parameters

style one of UDAT_FULL..UDAT_SHORT. Error if out of range.

status in/out parameter; if no failure status is already set, it will be set according to result of the function (e.g. U_ILLEGAL_ARGUMENT_ERROR for style out of range).

Returns

the current dateTimeFormat for the the specified style, or

empty string in case of error. The UnicodeString reference,

or the contents of the string, may no longer be valid if

setDateTimeFormat is called, or the DateTimePatternGenerator

object is deleted.

ICU 71

UnicodeString getBestPattern (const UnicodeString & skeleton, UErrorCode & status)

Return the best pattern matching the input skeleton. It is guaranteed to

have all of the fields in the skeleton.

Parameters

skeleton The skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

bestPattern

The best pattern found from the given skeleton.

ICU 3.8

UnicodeString getBestPattern (const UnicodeString & skeleton, UDateTimePatternMatchOptions options, UErrorCode & status)

Return the best pattern matching the input skeleton. It is guaranteed to

have all of the fields in the skeleton.

Parameters

skeleton The skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.

options Options for forcing the length of specified fields in the returned pattern to match those in the skeleton (when this would not happen otherwise). For default behavior, use UDATPG_MATCH_NO_OPTIONS.

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

bestPattern

The best pattern found from the given skeleton.

ICU 4.4

UnicodeString replaceFieldTypes (const UnicodeString & pattern, const UnicodeString & skeleton, UErrorCode & status)

Adjusts the field types (width and subtype) of a pattern to match what is

in a skeleton. That is, if you supply a pattern like "d-M H:m", and a

skeleton of "MMMMddhhmm", then the input pattern is adjusted to be

"dd-MMMM hh:mm". This is used internally to get the best match for the

input skeleton, but can also be used externally.

Parameters

pattern Input pattern

skeleton The skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

pattern adjusted to match the skeleton fields widths and subtypes.

ICU 3.8

UnicodeString replaceFieldTypes (const UnicodeString & pattern, const UnicodeString & skeleton, UDateTimePatternMatchOptions options, UErrorCode & status)

Adjusts the field types (width and subtype) of a pattern to match what is

in a skeleton. That is, if you supply a pattern like "d-M H:m", and a

skeleton of "MMMMddhhmm", then the input pattern is adjusted to be

"dd-MMMM hh:mm". This is used internally to get the best match for the

input skeleton, but can also be used externally.

Parameters

pattern Input pattern

skeleton The skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.

options Options controlling whether the length of specified fields in the pattern are adjusted to match those in the skeleton (when this would not happen otherwise). For default behavior, use UDATPG_MATCH_NO_OPTIONS.

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

pattern adjusted to match the skeleton fields widths and subtypes.

ICU 4.4

StringEnumeration * getSkeletons (UErrorCode & status)

Return a list of all the skeletons (in canonical form) from this class.

Call getPatternForSkeleton() to get the corresponding pattern.

Parameters

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

StringEnumeration with the skeletons.

The caller must delete the object.

ICU 3.8

const UnicodeString & getPatternForSkeleton (const UnicodeString & skeleton)

Get the pattern corresponding to a given skeleton.

Returns

pattern corresponding to a given skeleton.

ICU 3.8

StringEnumeration * getBaseSkeletons (UErrorCode & status)

Return a list of all the base skeletons (in canonical form) from this class.

Parameters

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

a StringEnumeration with the base skeletons.

The caller must delete the object.

ICU 3.8

StringEnumeration * getRedundants (UErrorCode & status)

Return a list of redundant patterns are those which if removed, make no

difference in the resulting getBestPattern values. This method returns a

list of them, to help check the consistency of the patterns used to build

this generator.

Parameters

status Output param set to success/failure code on exit, which must not indicate a failure before the function call.

Returns

a StringEnumeration with the redundant pattern.

The caller must delete the object.

void setDecimal (const UnicodeString & decimal)

The decimal value is used in formatting fractions of seconds. If the

skeleton contains fractional seconds, then this is used with the

fractional seconds. For example, suppose that the input pattern is

"hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and

the decimal string is ",". Then the resulting pattern is modified to be

"H:mm:ss,SSSS"

Parameters

decimal ICU 3.8

const UnicodeString & getDecimal ()

Getter corresponding to setDecimal.

Returns

UnicodeString corresponding to the decimal point

ICU 3.8

UDateFormatHourCycle getDefaultHourCycle (UErrorCode & status)

Get the default hour cycle for a locale. Uses the locale that the

DateTimePatternGenerator was initially created with.

Cannot be used on an empty DateTimePatternGenerator instance.

Parameters

status Output param set to success/failure code on exit, which which must not indicate a failure before the function call. Set to U_UNSUPPORTED_ERROR if used on an empty instance.

Returns

the default hour cycle.

ICU 67

UClassID getDynamicClassID ()

ICU "poor man's RTTI", returns a UClassID for the actual class.

ICU 3.8

UClassID getStaticClassID ()

ICU "poor man's RTTI", returns a UClassID for this class.

ICU 3.8