DateTimePatternGenerator

public class DateTimePatternGenerator extends Object
implements Freezable<DateTimePatternGenerator> 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.

Nested Class Summary

class DateTimePatternGenerator.PatternInfo PatternInfo supplies output parameters for addPattern(...). 

Constant Summary

int DAY
int DAYPERIOD
int DAY_OF_WEEK_IN_MONTH
int DAY_OF_YEAR
int ERA
int FRACTIONAL_SECOND
int HOUR
int MATCH_ALL_FIELDS_LENGTH Option mask for forcing the width of all date and time fields.
int MATCH_HOUR_FIELD_LENGTH Option mask for forcing the width of hour field.
int MATCH_NO_OPTIONS Default option mask used for getBestPattern(String, int) and replaceFieldTypes(String, String, int).
int MINUTE
int MONTH
int QUARTER
int SECOND
int WEEKDAY
int WEEK_OF_MONTH
int WEEK_OF_YEAR
int YEAR
int ZONE

Protected Constructor Summary

DateTimePatternGenerator()
Only for use by subclasses

Public Method Summary

DateTimePatternGenerator
addPattern(String pattern, boolean override, DateTimePatternGenerator.PatternInfo returnInfo)
Adds a pattern to the generator.
Object
clone()
Returns a copy of this DateTimePatternGenerator object.
DateTimePatternGenerator
cloneAsThawed()
Provides for the clone operation.
DateTimePatternGenerator
freeze()
Freezes the object.
String
getAppendItemFormat(int field)
Getter corresponding to setAppendItemFormats.
String
getAppendItemName(int field)
Getter corresponding to setAppendItemNames.
String
getBaseSkeleton(String pattern)
Utility to return a unique base skeleton from a given pattern.
Set<String>
getBaseSkeletons(Set<String> result)
Return a list of all the base skeletons (in canonical form) from this class
String
getBestPattern(String skeleton, int options)
Return the best pattern matching the input skeleton.
String
getBestPattern(String skeleton)
Return the best pattern matching the input skeleton.
String
getDateTimeFormat()
Getter corresponding to setDateTimeFormat.
String
getDecimal()
Getter corresponding to setDecimal.
static DateTimePatternGenerator
getEmptyInstance()
Create empty generator, to be constructed with addPattern(...) etc.
static DateTimePatternGenerator
getInstance()
Construct a flexible generator according to data for the default FORMAT locale.
static DateTimePatternGenerator
getInstance(Locale locale)
Construct a flexible generator according to data for a given locale.
static DateTimePatternGenerator
getInstance(ULocale uLocale)
Construct a flexible generator according to data for a given locale.
String
getSkeleton(String pattern)
Utility to return a unique skeleton from a given pattern.
Map<StringString>
getSkeletons(Map<StringString> result)
Return a list of all the skeletons (in canonical form) from this class, and the patterns that they map to.
boolean
isFrozen()
Determines whether the object has been frozen or not.
String
replaceFieldTypes(String pattern, String skeleton)
Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.
String
replaceFieldTypes(String pattern, String skeleton, int options)
Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.
void
setAppendItemFormat(int field, String value)
An AppendItem format is a pattern used to append a field if there is no good match.
void
setAppendItemName(int field, String value)
Sets the names of fields, eg "era" in English for ERA.
void
setDateTimeFormat(String dateTimeFormat)
The date time format is a message format pattern used to compose date and time patterns.
void
setDecimal(String decimal)
The decimal value is used in formatting fractions of seconds.

Inherited Method Summary

Constants

public static final int DAY

Constant Value: 7

public static final int DAYPERIOD

Constant Value: 10

public static final int DAY_OF_WEEK_IN_MONTH

Constant Value: 9

public static final int DAY_OF_YEAR

Constant Value: 8

public static final int ERA

Constant Value: 0

public static final int FRACTIONAL_SECOND

Constant Value: 14

public static final int HOUR

Constant Value: 11

public static final int MATCH_ALL_FIELDS_LENGTH

Option mask for forcing the width of all date and time fields.

Constant Value: 65535

public static final int MATCH_HOUR_FIELD_LENGTH

Option mask for forcing the width of hour field.

Constant Value: 2048

public static final int MATCH_NO_OPTIONS

public static final int MINUTE

Constant Value: 12

public static final int MONTH

Constant Value: 3

public static final int QUARTER

Constant Value: 2

public static final int SECOND

Constant Value: 13

public static final int WEEKDAY

Constant Value: 6

public static final int WEEK_OF_MONTH

Constant Value: 5

public static final int WEEK_OF_YEAR

Constant Value: 4

public static final int YEAR

Constant Value: 1

public static final int ZONE

Constant Value: 15

Protected Constructors

protected DateTimePatternGenerator ()

Only for use by subclasses

Public Methods

public DateTimePatternGenerator addPattern (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 overridden. 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! *

Example code:

INCLUDE_ERROR

Parameters
pattern Pattern to add.
override When existing values are to be overridden use true, otherwise use false.
returnInfo Returned information.

public Object clone ()

Returns a copy of this DateTimePatternGenerator object.

Returns
  • A copy of this DateTimePatternGenerator object.

public DateTimePatternGenerator cloneAsThawed ()

Provides for the clone operation. Any clone is initially unfrozen.

public DateTimePatternGenerator freeze ()

Freezes the object.

Returns
  • the object itself.

public String getAppendItemFormat (int field)

Getter corresponding to setAppendItemFormats. Values below 0 or at or above TYPE_LIMIT are illegal arguments.

Parameters
field The index to retrieve the append item formats.
Returns
  • append pattern for field

public String getAppendItemName (int field)

Getter corresponding to setAppendItemNames. Values below 0 or at or above TYPE_LIMIT are illegal arguments.

Parameters
field The index to get the append item name.
Returns
  • name for field

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"

public Set<String> getBaseSkeletons (Set<String> result)

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

Parameters
result

public String getBestPattern (String skeleton, int options)

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 MATCH_xxx 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 MATCH_NO_OPTIONS.
Returns
  • Best pattern matching the input skeleton (and options).

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.

Example code:

INCLUDE_ERROR

Parameters
skeleton The skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
Returns
  • Best pattern matching the input skeleton.

public String getDateTimeFormat ()

Getter corresponding to setDateTimeFormat.

Returns
  • pattern

public String getDecimal ()

Getter corresponding to setDecimal.

Returns
  • string corresponding to the decimal point

public static DateTimePatternGenerator getEmptyInstance ()

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

public static DateTimePatternGenerator getInstance ()

Construct a flexible generator according to data for the default FORMAT locale.

See Also

public static DateTimePatternGenerator getInstance (Locale locale)

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

Parameters
locale The Locale to pass.

public static DateTimePatternGenerator getInstance (ULocale uLocale)

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

Parameters
uLocale The locale to pass.

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"

public Map<StringString> getSkeletons (Map<StringString> 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.

public boolean isFrozen ()

Determines whether the object has been frozen or not.

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.

Example code:

INCLUDE_ERROR

Parameters
pattern input pattern
skeleton For the pattern to match to.
Returns
  • pattern adjusted to match the skeleton fields widths and subtypes.

public String replaceFieldTypes (String pattern, String skeleton, int options)

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 For the pattern to match to.
options MATCH_xxx 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 MATCH_NO_OPTIONS.
Returns
  • pattern adjusted to match the skeleton fields widths and subtypes.

public void setAppendItemFormat (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}"

public void setAppendItemName (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 Index of the append item names.
value The value to set the item to.

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 "{1} {0}", where {1} will be replaced by the date pattern and {0} 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 "{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".

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

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 The decimal to set to.