com.ibm.icu.text
Class DateTimePatternGenerator

java.lang.Object
  extended by com.ibm.icu.text.DateTimePatternGenerator
All Implemented Interfaces:
Freezable, Cloneable

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.

 // some simple use cases
 Date sampleDate = new Date(99, 9, 13, 23, 58, 59);
 ULocale locale = ULocale.GERMANY;
 TimeZone zone = TimeZone.getTimeZone("Europe/Paris");
 
 // make from locale
 
 DateTimePatternGenerator gen = DateTimePatternGenerator.getInstance(locale);
 SimpleDateFormat format = new SimpleDateFormat(gen.getBestPattern("MMMddHmm"),
     locale);
 format.setTimeZone(zone);
 assertEquals("simple format: MMMddHmm", 
     "8:58 14. Okt",
     format.format(sampleDate));
 // (a generator can be built from scratch, but that is not a typical use case)
 
 // modify the generator by adding patterns
 DateTimePatternGenerator.PatternInfo returnInfo = new DateTimePatternGenerator.PatternInfo();
 gen.add("d'. von' MMMM", true, returnInfo);
 // the returnInfo is mostly useful for debugging problem cases
 format.applyPattern(gen.getBestPattern("MMMMddHmm"));
 assertEquals("modified format: MMMddHmm",
     "8:58 14. von Oktober",
     format.format(sampleDate));
 
 // get a pattern and modify it
 format = (SimpleDateFormat) DateFormat.getDateTimeInstance(DateFormat.FULL,
     DateFormat.FULL, locale);
 format.setTimeZone(zone);
 String pattern = format.toPattern();
 assertEquals("full-date",
     "Donnerstag, 14. Oktober 1999 8:58 Uhr GMT+02:00",
     format.format(sampleDate));
 
 // modify it to change the zone.
 String newPattern = gen.replaceFieldTypes(pattern, "vvvv");
 format.applyPattern(newPattern);
 assertEquals("full-date, modified zone",
     "Donnerstag, 14. Oktober 1999 8:58 Uhr Frankreich",
     format.format(sampleDate));
 


Nested Class Summary
static class DateTimePatternGenerator.FormatParser
          Deprecated. This API is ICU internal only.
static class DateTimePatternGenerator.PatternInfo
          PatternInfo supplies output parameters for add(...).
static class DateTimePatternGenerator.VariableField
          Deprecated. This API is ICU internal only.
 
Field Summary
static int DAY
           
static int DAY_OF_WEEK_IN_MONTH
           
static int DAY_OF_YEAR
           
static int DAYPERIOD
           
static int ERA
           
static int FRACTIONAL_SECOND
           
static int HOUR
           
static int MINUTE
           
static int MONTH
           
static int QUARTER
           
static int SECOND
           
static int TYPE_LIMIT
           
static int WEEK_OF_MONTH
           
static int WEEK_OF_YEAR
           
static int WEEKDAY
           
static int YEAR
           
static int ZONE
           
 
Constructor Summary
protected DateTimePatternGenerator()
          Only for use by subclasses
 
Method Summary
 DateTimePatternGenerator addPattern(String pattern, boolean override, DateTimePatternGenerator.PatternInfo returnInfo)
          Adds a pattern to the generator.
 Object clone()
          Boilerplate
 Object cloneAsThawed()
          Boilerplate for Freezable
 Object freeze()
          Boilerplate for Freezable
 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 getBaseSkeletons(Set result)
          Return a list of all the base skeletons (in canonical form) from this class
 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 add(...) etc.
 String getFields(String pattern)
          Deprecated. This API is ICU internal only.
static DateTimePatternGenerator getInstance()
          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.
 Collection getRedundants(Collection output)
          Deprecated. This API is ICU internal only.
 String getSkeleton(String pattern)
          Utility to return a unique skeleton from a given pattern.
 Map getSkeletons(Map result)
          Return a list of all the skeletons (in canonical form) from this class, and the patterns that they map to.
 boolean isFrozen()
          Boilerplate for Freezable
static boolean isSingleField(String skeleton)
          Deprecated. This API is ICU internal only.
 String replaceFieldTypes(String pattern, String skeleton)
          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.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ERA

public static final int ERA
See Also:
Constant Field Values

YEAR

public static final int YEAR
See Also:
Constant Field Values

QUARTER

public static final int QUARTER
See Also:
Constant Field Values

MONTH

public static final int MONTH
See Also:
Constant Field Values

WEEK_OF_YEAR

public static final int WEEK_OF_YEAR
See Also:
Constant Field Values

WEEK_OF_MONTH

public static final int WEEK_OF_MONTH
See Also:
Constant Field Values

WEEKDAY

public static final int WEEKDAY
See Also:
Constant Field Values

DAY

public static final int DAY
See Also:
Constant Field Values

DAY_OF_YEAR

public static final int DAY_OF_YEAR
See Also:
Constant Field Values

DAY_OF_WEEK_IN_MONTH

public static final int DAY_OF_WEEK_IN_MONTH
See Also:
Constant Field Values

DAYPERIOD

public static final int DAYPERIOD
See Also:
Constant Field Values

HOUR

public static final int HOUR
See Also:
Constant Field Values

MINUTE

public static final int MINUTE
See Also:
Constant Field Values

SECOND

public static final int SECOND
See Also:
Constant Field Values

FRACTIONAL_SECOND

public static final int FRACTIONAL_SECOND
See Also:
Constant Field Values

ZONE

public static final int ZONE
See Also:
Constant Field Values

TYPE_LIMIT

public static final int TYPE_LIMIT
See Also:
Constant Field Values
Constructor Detail

DateTimePatternGenerator

protected DateTimePatternGenerator()
Only for use by subclasses

Method Detail

getEmptyInstance

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


getInstance

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


getInstance

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

Parameters:
uLocale -

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.

addPattern

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 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.

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"

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"

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.

getBaseSkeletons

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


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.

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 "{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.

getDateTimeFormat

public String getDateTimeFormat()
Getter corresponding to setDateTimeFormat.

Returns:
pattern

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 -

getDecimal

public String getDecimal()
Getter corresponding to setDecimal.

Returns:
string corresponding to the decimal point

getRedundants

public Collection getRedundants(Collection output)
Deprecated. This API is ICU internal only.

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.

setAppendItemFormat

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}"

getAppendItemFormat

public String getAppendItemFormat(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

setAppendItemName

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 -
value -

getAppendItemName

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

Parameters:
field -
Returns:
name for field

isSingleField

public static boolean isSingleField(String skeleton)
Deprecated. This API is ICU internal only.

Determines whether a skeleton contains a single field

Parameters:
skeleton -
Returns:
true or not

isFrozen

public boolean isFrozen()
Boilerplate for Freezable

Specified by:
isFrozen in interface Freezable

freeze

public Object freeze()
Boilerplate for Freezable

Specified by:
freeze in interface Freezable
Returns:
the object itself.

cloneAsThawed

public Object cloneAsThawed()
Boilerplate for Freezable

Specified by:
cloneAsThawed in interface Freezable

clone

public Object clone()
Boilerplate

Overrides:
clone in class Object

getFields

public String getFields(String pattern)
Deprecated. This API is ICU internal only.

internal routine

Parameters:
pattern -
Returns:
field value


Copyright (c) 2009 IBM Corporation and others.