Class DateTimePatternGenerator
- java.lang.Object
-
- com.ibm.icu.text.DateTimePatternGenerator
-
- All Implemented Interfaces:
Freezable<DateTimePatternGenerator>
,java.lang.Cloneable
public class DateTimePatternGenerator extends java.lang.Object implements Freezable<DateTimePatternGenerator>, java.lang.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
Nested Classes Modifier and Type Class Description static class
DateTimePatternGenerator.DisplayWidth
Field display name width constants for getFieldDisplayNamestatic class
DateTimePatternGenerator.FormatParser
Deprecated.This API is ICU internal only.static class
DateTimePatternGenerator.PatternInfo
PatternInfo supplies output parameters for addPattern(...).static class
DateTimePatternGenerator.VariableField
Deprecated.This API is ICU internal only.
-
Field Summary
Fields Modifier and Type Field Description 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
MATCH_ALL_FIELDS_LENGTH
Option mask for forcing the width of all date and time fields.static int
MATCH_HOUR_FIELD_LENGTH
Option mask for forcing the width of hour field.static int
MATCH_MINUTE_FIELD_LENGTH
Deprecated.This API is ICU internal only.static int
MATCH_NO_OPTIONS
Default option mask used forgetBestPattern(String, int)
andreplaceFieldTypes(String, String, int)
.static int
MATCH_SECOND_FIELD_LENGTH
Deprecated.This API is ICU internal only.static int
MINUTE
static int
MONTH
static int
QUARTER
static int
SECOND
static int
TYPE_LIMIT
Deprecated.ICU 58 The numeric value may change over time, see ICU ticket #12420.static int
WEEK_OF_MONTH
static int
WEEK_OF_YEAR
static int
WEEKDAY
static int
YEAR
static int
ZONE
-
Constructor Summary
Constructors Modifier Constructor Description protected
DateTimePatternGenerator()
Only for use by subclasses
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description DateTimePatternGenerator
addPattern(java.lang.String pattern, boolean override, DateTimePatternGenerator.PatternInfo returnInfo)
Adds a pattern to the generator.DateTimePatternGenerator
addPatternWithSkeleton(java.lang.String pattern, java.lang.String skeletonToUse, boolean override, DateTimePatternGenerator.PatternInfo returnInfo)
Deprecated.This API is ICU internal only.java.lang.Object
clone()
Returns a copy of thisDateTimePatternGenerator
object.DateTimePatternGenerator
cloneAsThawed()
Provides for the clone operation.DateTimePatternGenerator
freeze()
Freezes the object.static int
getAppendFormatNumber(com.ibm.icu.impl.UResource.Key key)
Deprecated.This API is ICU internal only.static int
getAppendFormatNumber(java.lang.String string)
Deprecated.This API is ICU internal only.java.lang.String
getAppendItemFormat(int field)
Getter corresponding to setAppendItemFormats.java.lang.String
getAppendItemName(int field)
Getter corresponding to setAppendItemName.java.lang.String
getBaseSkeleton(java.lang.String pattern)
Utility to return a unique base skeleton from a given pattern.java.util.Set<java.lang.String>
getBaseSkeletons(java.util.Set<java.lang.String> result)
Return a list of all the base skeletons (in canonical form) from this classjava.lang.String
getBestPattern(java.lang.String skeleton)
Return the best pattern matching the input skeleton.java.lang.String
getBestPattern(java.lang.String skeleton, int options)
Return the best pattern matching the input skeleton.java.lang.String
getCanonicalSkeletonAllowingDuplicates(java.lang.String pattern)
Deprecated.This API is ICU internal only.java.lang.String
getDateTimeFormat()
Getter corresponding to setDateTimeFormat.java.lang.String
getDecimal()
Getter corresponding to setDecimal.char
getDefaultHourFormatChar()
Deprecated.This API is ICU internal only.static DateTimePatternGenerator
getEmptyInstance()
Create empty generator, to be constructed with addPattern(...) etc.java.lang.String
getFieldDisplayName(int field, DateTimePatternGenerator.DisplayWidth width)
The general interface to get a display name for a particular date/time field, in one of several possible display widths.java.lang.String
getFields(java.lang.String pattern)
Deprecated.This API is ICU internal only.static DateTimePatternGenerator
getFrozenInstance(ULocale uLocale)
Deprecated.This API is ICU internal only.static DateTimePatternGenerator
getInstance()
Construct a flexible generator according to data for the defaultFORMAT
locale.static DateTimePatternGenerator
getInstance(ULocale uLocale)
Construct a flexible generator according to data for a given locale.static DateTimePatternGenerator
getInstance(java.util.Locale locale)
Construct a flexible generator according to data for a given locale.java.util.Collection<java.lang.String>
getRedundants(java.util.Collection<java.lang.String> output)
Deprecated.This API is ICU internal only.java.lang.String
getSkeleton(java.lang.String pattern)
Utility to return a unique skeleton from a given pattern.java.lang.String
getSkeletonAllowingDuplicates(java.lang.String pattern)
Deprecated.This API is ICU internal only.java.util.Map<java.lang.String,java.lang.String>
getSkeletons(java.util.Map<java.lang.String,java.lang.String> 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.static boolean
isSingleField(java.lang.String skeleton)
Deprecated.This API is ICU internal only.java.lang.String
replaceFieldTypes(java.lang.String pattern, java.lang.String skeleton)
Adjusts the field types (width and subtype) of a pattern to match what is in a skeleton.java.lang.String
replaceFieldTypes(java.lang.String pattern, java.lang.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, java.lang.String value)
An AppendItem format is a pattern used to append a field if there is no good match.void
setAppendItemName(int field, java.lang.String value)
Sets the names of fields, eg "era" in English for ERA.void
setDateTimeFormat(java.lang.String dateTimeFormat)
The date time format is a message format pattern used to compose date and time patterns.void
setDecimal(java.lang.String decimal)
The decimal value is used in formatting fractions of seconds.void
setDefaultHourFormatChar(char defaultHourFormatChar)
Deprecated.This API is ICU internal only.boolean
skeletonsAreSimilar(java.lang.String id, java.lang.String skeleton)
Deprecated.This API is ICU internal only.
-
-
-
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
@Deprecated public static final int TYPE_LIMIT
Deprecated.ICU 58 The numeric value may change over time, see ICU ticket #12420.One more than the highest normal field number.- See Also:
- Constant Field Values
-
MATCH_NO_OPTIONS
public static final int MATCH_NO_OPTIONS
Default option mask used forgetBestPattern(String, int)
andreplaceFieldTypes(String, String, int)
.
-
MATCH_HOUR_FIELD_LENGTH
public static final int MATCH_HOUR_FIELD_LENGTH
Option mask for forcing the width of hour field.
-
MATCH_MINUTE_FIELD_LENGTH
@Deprecated public static final int MATCH_MINUTE_FIELD_LENGTH
Deprecated.This API is ICU internal only.Option mask for forcing the width of minute field.- See Also:
- Constant Field Values
-
MATCH_SECOND_FIELD_LENGTH
@Deprecated public static final int MATCH_SECOND_FIELD_LENGTH
Deprecated.This API is ICU internal only.Option mask for forcing the width of second field.- See Also:
- Constant Field Values
-
MATCH_ALL_FIELDS_LENGTH
public static final int MATCH_ALL_FIELDS_LENGTH
Option mask for forcing the width of all date and time fields.
-
-
Method Detail
-
getEmptyInstance
public static DateTimePatternGenerator getEmptyInstance()
Create empty generator, to be constructed with addPattern(...) etc.
-
getInstance
public static DateTimePatternGenerator getInstance()
Construct a flexible generator according to data for the defaultFORMAT
locale.- See Also:
ULocale.Category.FORMAT
-
getInstance
public static DateTimePatternGenerator getInstance(ULocale uLocale)
Construct a flexible generator according to data for a given locale.- Parameters:
uLocale
- The locale to pass.
-
getInstance
public static DateTimePatternGenerator getInstance(java.util.Locale locale)
Construct a flexible generator according to data for a given locale.- Parameters:
locale
- TheLocale
to pass.
-
getFrozenInstance
@Deprecated public static DateTimePatternGenerator getFrozenInstance(ULocale uLocale)
Deprecated.This API is ICU internal only.Construct a frozen instance of DateTimePatternGenerator for a given locale. This method returns a cached frozen instance of DateTimePatternGenerator, so less expensive than the regular factory method.- Parameters:
uLocale
- The locale to pass.- Returns:
- A frozen DateTimePatternGenerator.
-
getDefaultHourFormatChar
@Deprecated public char getDefaultHourFormatChar()
Deprecated.This API is ICU internal only.
-
setDefaultHourFormatChar
@Deprecated public void setDefaultHourFormatChar(char defaultHourFormatChar)
Deprecated.This API is ICU internal only.
-
getAppendFormatNumber
@Deprecated public static int getAppendFormatNumber(com.ibm.icu.impl.UResource.Key key)
Deprecated.This API is ICU internal only.
-
getAppendFormatNumber
@Deprecated public static int getAppendFormatNumber(java.lang.String string)
Deprecated.This API is ICU internal only.
-
getBestPattern
public java.lang.String getBestPattern(java.lang.String skeleton)
Return the best pattern matching the input skeleton. It is guaranteed to have all of the fields in the skeleton.Example code:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---getBestPatternExample}
- 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.
-
getBestPattern
public java.lang.String getBestPattern(java.lang.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).
-
addPattern
public DateTimePatternGenerator addPattern(java.lang.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:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---addPatternExample}
- Parameters:
pattern
- Pattern to add.override
- When existing values are to be overridden use true, otherwise use false.returnInfo
- Returned information.
-
addPatternWithSkeleton
@Deprecated public DateTimePatternGenerator addPatternWithSkeleton(java.lang.String pattern, java.lang.String skeletonToUse, boolean override, DateTimePatternGenerator.PatternInfo returnInfo)
Deprecated.This API is ICU internal only.addPatternWithSkeleton: If skeletonToUse is specified, then an availableFormats entry is being added. In this case: 1. We pass that skeleton to DateTimeMatcher().set instead of having it derive a skeleton from the pattern. 2. If the new entry's skeleton or basePattern does match an existing entry but that entry also had a skeleton specified (i.e. it was also from availableFormats), then the new entry does not override it regardless of the value of the override parameter. This prevents later availableFormats entries from a parent locale overriding earlier ones from the actual specified locale. However, availableFormats entries *should* override entries with matching skeleton whose skeleton was derived (i.e. entries derived from the standard date/time patters for the specified locale). 3. When adding the pattern (skeleton2pattern.put, basePattern_pattern.put), we set a field to indicate that the added entry had a specified skeleton.
-
getSkeleton
public java.lang.String getSkeleton(java.lang.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"
-
getSkeletonAllowingDuplicates
@Deprecated public java.lang.String getSkeletonAllowingDuplicates(java.lang.String pattern)
Deprecated.This API is ICU internal only.Same as getSkeleton, but allows duplicates- Parameters:
pattern
- Input pattern, such as "dd/MMM"- Returns:
- skeleton, such as "MMMdd"
-
getCanonicalSkeletonAllowingDuplicates
@Deprecated public java.lang.String getCanonicalSkeletonAllowingDuplicates(java.lang.String pattern)
Deprecated.This API is ICU internal only.Same as getSkeleton, but allows duplicates and returns a string using canonical pattern chars- Parameters:
pattern
- Input pattern, such as "ccc, d LLL"- Returns:
- skeleton, such as "MMMEd"
-
getBaseSkeleton
public java.lang.String getBaseSkeleton(java.lang.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 java.util.Map<java.lang.String,java.lang.String> getSkeletons(java.util.Map<java.lang.String,java.lang.String> 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 java.util.Set<java.lang.String> getBaseSkeletons(java.util.Set<java.lang.String> result)
Return a list of all the base skeletons (in canonical form) from this class
-
replaceFieldTypes
public java.lang.String replaceFieldTypes(java.lang.String pattern, java.lang.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:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---replaceFieldTypesExample}
- Parameters:
pattern
- input patternskeleton
- For the pattern to match to.- Returns:
- pattern adjusted to match the skeleton fields widths and subtypes.
-
replaceFieldTypes
public java.lang.String replaceFieldTypes(java.lang.String pattern, java.lang.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 patternskeleton
- 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.
-
setDateTimeFormat
public void setDateTimeFormat(java.lang.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 java.lang.String getDateTimeFormat()
Getter corresponding to setDateTimeFormat.- Returns:
- pattern
-
setDecimal
public void setDecimal(java.lang.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.
-
getDecimal
public java.lang.String getDecimal()
Getter corresponding to setDecimal.- Returns:
- string corresponding to the decimal point
-
getRedundants
@Deprecated public java.util.Collection<java.lang.String> getRedundants(java.util.Collection<java.lang.String> 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, java.lang.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 ERAvalue
- pattern, such as "{0}, {1}"
-
getAppendItemFormat
public java.lang.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
-
setAppendItemName
public void setAppendItemName(int field, java.lang.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.
-
getAppendItemName
public java.lang.String getAppendItemName(int field)
Getter corresponding to setAppendItemName. Values below 0 or at or above TYPE_LIMIT are illegal arguments. Note: The more general method for getting date/time field display names is getFieldDisplayName.- Parameters:
field
- The index to get the append item name.- Returns:
- name for field
- See Also:
getFieldDisplayName(int, DisplayWidth)
-
getFieldDisplayName
public java.lang.String getFieldDisplayName(int field, DateTimePatternGenerator.DisplayWidth 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 field type, such as ERA.width
- The desired DisplayWidth, such as DisplayWidth.ABBREVIATED.- Returns:
- The display name for the field
-
isSingleField
@Deprecated public static boolean isSingleField(java.lang.String skeleton)
Deprecated.This API is ICU internal only.Determines whether a skeleton contains a single field- Parameters:
skeleton
- The skeleton to determine if it contains a single field.- Returns:
- true or not
-
isFrozen
public boolean isFrozen()
Determines whether the object has been frozen or not.- Specified by:
isFrozen
in interfaceFreezable<DateTimePatternGenerator>
-
freeze
public DateTimePatternGenerator freeze()
Freezes the object.- Specified by:
freeze
in interfaceFreezable<DateTimePatternGenerator>
- Returns:
- the object itself.
-
cloneAsThawed
public DateTimePatternGenerator cloneAsThawed()
Provides for the clone operation. Any clone is initially unfrozen.- Specified by:
cloneAsThawed
in interfaceFreezable<DateTimePatternGenerator>
-
clone
public java.lang.Object clone()
Returns a copy of thisDateTimePatternGenerator
object.- Overrides:
clone
in classjava.lang.Object
- Returns:
- A copy of this
DateTimePatternGenerator
object.
-
skeletonsAreSimilar
@Deprecated public boolean skeletonsAreSimilar(java.lang.String id, java.lang.String skeleton)
Deprecated.This API is ICU internal only.Used by CLDR tooling; not in ICU4C. Note, this will not work correctly with normal skeletons, since fields that should be related in the two skeletons being compared - like EEE and ccc, or y and U - will not be sorted in the same relative place as each other when iterating over both TreeSets being compare, using TreeSet's "natural" code point ordering (this could be addressed by initializing the TreeSet with a comparator that compares fields first by their index from getCanonicalIndex()). However if comparing canonical skeletons from getCanonicalSkeletonAllowingDuplicates it will be OK regardless, since in these skeletons all fields are normalized to the canonical pattern char for those fields - M or L to M, E or c to E, y or U to y, etc. - so corresponding fields will sort in the same way for both TreeMaps.
-
getFields
@Deprecated public java.lang.String getFields(java.lang.String pattern)
Deprecated.This API is ICU internal only.internal routine- Parameters:
pattern
- The pattern that is passed.- Returns:
- field value
-
-