Added in API level 24

DateTimePatternGenerator


open class DateTimePatternGenerator : Freezable<DateTimePatternGenerator!>, Cloneable
kotlin.Any
   ↳ android.icu.text.DateTimePatternGenerator

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.

Summary

Nested classes

Field display name width constants for getFieldDisplayName

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

Constants
static Int

static Int

static Int

static Int

static Int

static Int

static Int

static Int

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

static Int

Option mask for forcing the width of hour field.

static Int

Default option mask used for getBestPattern(java.lang.String,int) and replaceFieldTypes(java.lang.String,java.lang.String,int).

static Int

static Int

static Int

static Int

static Int

static Int

static Int

static Int

static Int

Protected constructors

Only for use by subclasses

Public methods
open DateTimePatternGenerator!
addPattern(pattern: String!, override: Boolean, returnInfo: DateTimePatternGenerator.PatternInfo!)

Adds a pattern to the generator.

open Any

Returns a copy of this DateTimePatternGenerator object.

open DateTimePatternGenerator!

Provides for the clone operation.

open DateTimePatternGenerator!

Freezes the object.

open String!

Getter corresponding to setAppendItemFormats.

open String!

Getter corresponding to setAppendItemName.

open String!

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

open MutableSet<String!>!

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

open String!
getBestPattern(skeleton: String!)

Return the best pattern matching the input skeleton.

open String!
getBestPattern(skeleton: String!, options: Int)

Return the best pattern matching the input skeleton.

open String!

Getter corresponding to setDateTimeFormat.

open String!

Getter corresponding to setDateTimeFormat.

open String!

Getter corresponding to setDecimal.

open DateFormat.HourCycle!

Return the default hour cycle.

open static DateTimePatternGenerator!

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

open String!

The general interface to get a display name for a particular date/time field, in one of several possible display widths.

open static DateTimePatternGenerator!

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

open static DateTimePatternGenerator!
getInstance(uLocale: ULocale!)

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

open static DateTimePatternGenerator!
getInstance(locale: Locale!)

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

open String!
getSkeleton(pattern: String!)

Utility to return a unique skeleton from a given pattern.

open MutableMap<String!, String!>!

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

open Boolean

Determines whether the object has been frozen or not.

open String!
replaceFieldTypes(pattern: String!, skeleton: String!)

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

open String!
replaceFieldTypes(pattern: String!, skeleton: String!, options: Int)

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

open Unit
setAppendItemFormat(field: Int, value: String!)

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

open Unit
setAppendItemName(field: Int, value: String!)

Sets the names of fields, eg "era" in English for ERA.

open Unit
setDateTimeFormat(dateTimeFormat: String!)

The date time format is a message format pattern used to compose date and time patterns.

open Unit
setDateTimeFormat(style: Int, dateTimeFormat: String!)

dateTimeFormats are message patterns used to compose combinations of date and time patterns.

open Unit
setDecimal(decimal: String!)

The decimal value is used in formatting fractions of seconds.

Constants

DAY

Added in API level 24
static val DAY: Int
Value: 7

DAYPERIOD

Added in API level 24
static val DAYPERIOD: Int
Value: 10

DAY_OF_WEEK_IN_MONTH

Added in API level 24
static val DAY_OF_WEEK_IN_MONTH: Int
Value: 9

DAY_OF_YEAR

Added in API level 24
static val DAY_OF_YEAR: Int
Value: 8

ERA

Added in API level 24
static val ERA: Int
Value: 0

FRACTIONAL_SECOND

Added in API level 24
static val FRACTIONAL_SECOND: Int
Value: 14

HOUR

Added in API level 24
static val HOUR: Int
Value: 11

MATCH_ALL_FIELDS_LENGTH

Added in API level 24
static val MATCH_ALL_FIELDS_LENGTH: Int

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

Value: 65535

MATCH_HOUR_FIELD_LENGTH

Added in API level 24
static val MATCH_HOUR_FIELD_LENGTH: Int

Option mask for forcing the width of hour field.

Value: 2048

MINUTE

Added in API level 24
static val MINUTE: Int
Value: 12

MONTH

Added in API level 24
static val MONTH: Int
Value: 3

QUARTER

Added in API level 24
static val QUARTER: Int
Value: 2

SECOND

Added in API level 24
static val SECOND: Int
Value: 13

WEEKDAY

Added in API level 24
static val WEEKDAY: Int
Value: 6

WEEK_OF_MONTH

Added in API level 24
static val WEEK_OF_MONTH: Int
Value: 5

WEEK_OF_YEAR

Added in API level 24
static val WEEK_OF_YEAR: Int
Value: 4

YEAR

Added in API level 24
static val YEAR: Int
Value: 1

ZONE

Added in API level 24
static val ZONE: Int
Value: 15

Protected constructors

DateTimePatternGenerator

Added in API level 24
protected DateTimePatternGenerator()

Only for use by subclasses

Public methods

addPattern

Added in API level 24
open fun addPattern(
    pattern: String!,
    override: Boolean,
    returnInfo: DateTimePatternGenerator.PatternInfo!
): DateTimePatternGenerator!

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:

Parameters
pattern String!: Pattern to add.
override Boolean: When existing values are to be overridden use true, otherwise use false.
returnInfo DateTimePatternGenerator.PatternInfo!: Returned information.

clone

Added in API level 24
open fun clone(): Any

Returns a copy of this DateTimePatternGenerator object.

Return
Any A copy of this DateTimePatternGenerator object.
Exceptions
java.lang.CloneNotSupportedException if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.

cloneAsThawed

Added in API level 24
open fun cloneAsThawed(): DateTimePatternGenerator!

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

freeze

Added in API level 24
open fun freeze(): DateTimePatternGenerator!

Freezes the object.

Return
DateTimePatternGenerator! the object itself.

getAppendItemFormat

Added in API level 24
open fun getAppendItemFormat(field: Int): String!

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

Parameters
field Int: The index to retrieve the append item formats.
Return
String! append pattern for field

getAppendItemName

Added in API level 24
open fun getAppendItemName(field: Int): String!

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 Int: The index to get the append item name.
Return
String! name for field

getBaseSkeleton

Added in API level 24
open fun getBaseSkeleton(pattern: String!): String!

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 String!: Input pattern, such as "dd/MMM"
Return
String! skeleton, such as "MMMdd"

getBaseSkeletons

Added in API level 24
open fun getBaseSkeletons(result: MutableSet<String!>!): MutableSet<String!>!

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

getBestPattern

Added in API level 24
open fun getBestPattern(skeleton: String!): String!

Return the best pattern matching the input skeleton. It is guaranteed to have all of the fields in the skeleton.

Example code:

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

getBestPattern

Added in API level 24
open fun getBestPattern(
    skeleton: String!,
    options: Int
): String!

Return the best pattern matching the input skeleton. It is guaranteed to have all of the fields in the skeleton.

Parameters
skeleton String!: The skeleton is a pattern containing only the variable fields. For example, "MMMdd" and "mmhh" are skeletons.
options Int: 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.
Return
String! Best pattern matching the input skeleton (and options).

getDateTimeFormat

Added in API level 24
open fun getDateTimeFormat(): String!

Getter corresponding to setDateTimeFormat. There are four DateTimeFormats in a DateTimePatternGenerator object, corresponding to date styles DateFormat.FULL..DateFormat.SHORT. This method gets the style for DateFormat.MEDIUM (the default). To get them individually, see getDateTimeFormat(int style).

Return
String! pattern

getDateTimeFormat

Added in API level 35
open fun getDateTimeFormat(style: Int): String!

Getter corresponding to setDateTimeFormat.

Parameters
style Int: one of DateFormat.FULL..DateFormat.SHORT. An exception will be thrown if out of range.
Return
String! the current dateTimeFormat for the specified style.

getDecimal

Added in API level 24
open fun getDecimal(): String!

Getter corresponding to setDecimal.

Return
String! string corresponding to the decimal point

getDefaultHourCycle

Added in API level 33
open fun getDefaultHourCycle(): DateFormat.HourCycle!

Return the default hour cycle.

getEmptyInstance

Added in API level 24
open static fun getEmptyInstance(): DateTimePatternGenerator!

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

getFieldDisplayName

Added in API level 30
open fun getFieldDisplayName(
    field: Int,
    width: DateTimePatternGenerator.DisplayWidth!
): String!

The general interface to get a display name for a particular date/time field, in one of several possible display widths.

Parameters
field Int: The field type, such as ERA.
width DateTimePatternGenerator.DisplayWidth!: The desired DisplayWidth, such as DisplayWidth.ABBREVIATED.
Return
String! The display name for the field

getInstance

Added in API level 24
open static fun getInstance(): DateTimePatternGenerator!

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

getInstance

Added in API level 24
open static fun getInstance(uLocale: ULocale!): DateTimePatternGenerator!

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

Parameters
uLocale ULocale!: The locale to pass.

getInstance

Added in API level 24
open static fun getInstance(locale: Locale!): DateTimePatternGenerator!

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

Parameters
locale Locale!: The java.util.Locale to pass.

getSkeleton

Added in API level 24
open fun getSkeleton(pattern: String!): String!

Utility to return a unique skeleton from a given pattern. For example, both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".

Parameters
pattern String!: Input pattern, such as "dd/MMM"
Return
String! skeleton, such as "MMMdd"

getSkeletons

Added in API level 24
open fun getSkeletons(result: MutableMap<String!, String!>!): MutableMap<String!, String!>!

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

Parameters
result MutableMap<String!, String!>!: 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.

Return
MutableMap<String!, String!>! the input Map containing the values.

isFrozen

Added in API level 24
open fun isFrozen(): Boolean

Determines whether the object has been frozen or not.

replaceFieldTypes

Added in API level 24
open fun replaceFieldTypes(
    pattern: String!,
    skeleton: String!
): String!

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:

Parameters
pattern String!: input pattern
skeleton String!: For the pattern to match to.
Return
String! pattern adjusted to match the skeleton fields widths and subtypes.

replaceFieldTypes

Added in API level 24
open fun replaceFieldTypes(
    pattern: String!,
    skeleton: String!,
    options: Int
): String!

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 String!: input pattern
skeleton String!: For the pattern to match to.
options Int: 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.
Return
String! pattern adjusted to match the skeleton fields widths and subtypes.

setAppendItemFormat

Added in API level 24
open fun setAppendItemFormat(
    field: Int,
    value: String!
): Unit

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 Int: such as ERA
value String!: pattern, such as "{0}, {1}"

setAppendItemName

Added in API level 24
open fun setAppendItemName(
    field: Int,
    value: String!
): Unit

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 Int: Index of the append item names.
value String!: The value to set the item to.

setDateTimeFormat

Added in API level 24
open fun setDateTimeFormat(dateTimeFormat: String!): Unit

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". There are four DateTimeFormats in a DateTimePatternGenerator object, corresponding to date styles DateFormat.FULL..DateFormat.SHORT. This method sets all of them to the specified pattern. To set them individually, see setDateTimeFormat(int style, ...).

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

setDateTimeFormat

Added in API level 35
open fun setDateTimeFormat(
    style: Int,
    dateTimeFormat: String!
): Unit

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: - DateFormat.FULL (for date pattern with weekday and long month), else - DateFormat.LONG (for a date pattern with long month), else - DateFormat.MEDIUM (for a date pattern with abbreviated month), else - DateFormat.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 Int: one of DateFormat.FULL..DateFormat.SHORT. An exception will be thrown if out of range.
dateTimeFormat String!: the new dateTimeFormat to set for the specified style

setDecimal

Added in API level 24
open fun setDecimal(decimal: String!): Unit

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