com.ibm.icu.text

Class DateTimePatternGenerator

public class DateTimePatternGenerator extends Object implements Freezable, Cloneable

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.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Nested Class Summary
static classDateTimePatternGenerator.FormatParser
Class providing date formatting
static classDateTimePatternGenerator.PatternInfo
PatternInfo supplies output parameters for add(...).
static classDateTimePatternGenerator.VariableField
Utility class for FormatParser.
Field Summary
static intDAY
static intDAYPERIOD
static intDAY_OF_WEEK_IN_MONTH
static intDAY_OF_YEAR
static intERA
static intFRACTIONAL_SECOND
static intHOUR
static intMINUTE
static intMONTH
static intQUARTER
static intSECOND
static intTYPE_LIMIT
static intWEEKDAY
static intWEEK_OF_MONTH
static intWEEK_OF_YEAR
static intYEAR
static intZONE
Constructor Summary
protected DateTimePatternGenerator()
Only for use by subclasses
Method Summary
DateTimePatternGeneratoradd(String pattern, boolean override, DateTimePatternGenerator.PatternInfo returnInfo)
Adds a pattern to the generator.
Objectclone()
Boilerplate
ObjectcloneAsThawed()
Boilerplate for Freezable
Objectfreeze()
Boilerplate for Freezable
StringgetAppendItemFormats(int field)
Getter corresponding to setAppendItemFormats.
StringgetAppendItemNames(int field)
Getter corresponding to setAppendItemNames.
StringgetBaseSkeleton(String pattern)
Utility to return a unique base skeleton from a given pattern.
SetgetBaseSkeletons(Set result)
Return a list of all the base skeletons (in canonical form) from this class
StringgetBestPattern(String skeleton)
Return the best pattern matching the input skeleton.
StringgetDateTimeFormat()
Getter corresponding to setDateTimeFormat.
StringgetDecimal()
Getter corresponding to setDecimal.
StringgetFields(String pattern)
internal routine
static DateTimePatternGeneratorgetInstance()
Construct a flexible generator according to data for a given locale.
static DateTimePatternGeneratorgetInstance(ULocale uLocale)
Construct a flexible generator according to data for a given locale.
CollectiongetRedundants(Collection output)
Redundant patterns are those which if removed, make no difference in the resulting getBestPattern values.
StringgetSkeleton(String pattern)
Utility to return a unique skeleton from a given pattern.
MapgetSkeletons(Map result)
Return a list of all the skeletons (in canonical form) from this class, and the patterns that they map to.
booleanisFrozen()
Boilerplate for Freezable
static booleanisSingleField(String skeleton)
Determines whether a skeleton contains a single field
static DateTimePatternGeneratornewInstance()
Create empty generator, to be constructed with add(...) etc.
StringreplaceFieldTypes(String pattern, String skeleton)
Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.
voidsetAppendItemFormats(int field, String value)
An AppendItem format is a pattern used to append a field if there is no good match.
voidsetAppendItemNames(int field, String value)
Sets the names of fields, eg "era" in English for ERA.
voidsetDateTimeFormat(String dateTimeFormat)
The date time format is a message format pattern used to compose date and time patterns.
voidsetDecimal(String decimal)
The decimal value is used in formatting fractions of seconds.

Field Detail

DAY

public static final int DAY

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

DAYPERIOD

public static final int DAYPERIOD

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

DAY_OF_WEEK_IN_MONTH

public static final int DAY_OF_WEEK_IN_MONTH

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

DAY_OF_YEAR

public static final int DAY_OF_YEAR

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ERA

public static final int ERA

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

FRACTIONAL_SECOND

public static final int FRACTIONAL_SECOND

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

HOUR

public static final int HOUR

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

MINUTE

public static final int MINUTE

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

MONTH

public static final int MONTH

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

QUARTER

public static final int QUARTER

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

SECOND

public static final int SECOND

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

TYPE_LIMIT

public static final int TYPE_LIMIT

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

WEEKDAY

public static final int WEEKDAY

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

WEEK_OF_MONTH

public static final int WEEK_OF_MONTH

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

WEEK_OF_YEAR

public static final int WEEK_OF_YEAR

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

YEAR

public static final int YEAR

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

ZONE

public static final int ZONE

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Constructor Detail

DateTimePatternGenerator

protected DateTimePatternGenerator()
Only for use by subclasses

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Method Detail

add

public DateTimePatternGenerator add(String pattern, boolean override, DateTimePatternGenerator.PatternInfo returnInfo)
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 overriden. Otherwise, the previous value is retained. In either case, the conflicting information is returned in PatternInfo.

Note that single-field patterns (like "MMM") are automatically added, and don't need to be added explicitly!

Parameters: override when existing values are to be overridden use true, otherwise use false.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

clone

public Object clone()
Boilerplate

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

cloneAsThawed

public Object cloneAsThawed()
Boilerplate for Freezable

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

freeze

public Object freeze()
Boilerplate for Freezable

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getAppendItemFormats

public String getAppendItemFormats(int field)
Getter corresponding to setAppendItemFormats. Values below 0 or at or above TYPE_LIMIT are illegal arguments.

Parameters: field

Returns: append pattern for field

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getAppendItemNames

public String getAppendItemNames(int field)
Getter corresponding to setAppendItemNames. Values below 0 or at or above TYPE_LIMIT are illegal arguments.

Parameters: field

Returns: name for field

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getBaseSkeleton

public String getBaseSkeleton(String pattern)
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"

Returns: skeleton, such as "MMMdd"

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getBaseSkeletons

public Set getBaseSkeletons(Set result)
Return a list of all the base skeletons (in canonical form) from this class

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getBestPattern

public String getBestPattern(String skeleton)
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.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getDateTimeFormat

public String getDateTimeFormat()
Getter corresponding to setDateTimeFormat.

Returns: pattern

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getDecimal

public String getDecimal()
Getter corresponding to setDecimal.

Returns: string corresponding to the decimal point

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getFields

public String getFields(String pattern)

Deprecated:

internal routine

Parameters: pattern

Returns: field value

UNKNOWN:

getInstance

public static DateTimePatternGenerator getInstance()
Construct a flexible generator according to data for a given locale.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getInstance

public static DateTimePatternGenerator getInstance(ULocale uLocale)
Construct a flexible generator according to data for a given locale.

Parameters: uLocale

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getRedundants

public Collection getRedundants(Collection output)

Deprecated:

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: output stores the redundant patterns that are removed. To get these in internal order, supply a LinkedHashSet. If null, a collection is allocated.

Returns: the collection with added elements.

UNKNOWN:

getSkeleton

public String getSkeleton(String pattern)
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"

Returns: skeleton, such as "MMMdd"

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

getSkeletons

public Map getSkeletons(Map result)
Return a list of all the skeletons (in canonical form) from this class, and the patterns that they map to.

Parameters: result an output Map in which to place the mapping from skeleton to pattern. If you want to see the internal order being used, supply a LinkedHashMap. If the input value is null, then a LinkedHashMap is allocated.

Issue: an alternate API would be to just return a list of the skeletons, and then have a separate routine to get from skeleton to pattern.

Returns: the input Map containing the values.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

isFrozen

public boolean isFrozen()
Boilerplate for Freezable

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

isSingleField

public static boolean isSingleField(String skeleton)

Deprecated:

Determines whether a skeleton contains a single field

Parameters: skeleton

Returns: true or not

UNKNOWN:

newInstance

public static DateTimePatternGenerator newInstance()
Create empty generator, to be constructed with add(...) etc.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

replaceFieldTypes

public String replaceFieldTypes(String pattern, String skeleton)
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

Returns: pattern adjusted to match the skeleton fields widths and subtypes.

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setAppendItemFormats

public void setAppendItemFormats(int field, String 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 ERA value pattern, such as "{0}, {1}"

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setAppendItemNames

public void setAppendItemNames(int field, String value)
Sets the names of fields, 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 value

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setDateTimeFormat

public void setDateTimeFormat(String dateTimeFormat)
The date time format is a message format pattern used to compose date and time patterns. The default value is "{0} {1}", where {0} will be replaced by the date pattern and {1} will be replaced by the time pattern.

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 "{0} {1}". 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".

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

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

setDecimal

public void setDecimal(String 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

UNKNOWN: ICU 3.6 This API might change or be removed in a future release.

Copyright (c) 2007 IBM Corporation and others.