com.ibm.icu.text

Class DateTimePatternGenerator

java.lang.Object

com.ibm.icu.text.DateTimePatternGenerator

All Implemented Interfaces:

Freezable<DateTimePatternGenerator>, Cloneable

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.

 // 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));
 

Status:

Stable ICU 3.6.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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

Fields

Modifier and Type	Field and 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 for getBestPattern(String, int) and replaceFieldTypes(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
static int	WEEK_OF_MONTH
static int	WEEK_OF_YEAR
static int	WEEKDAY
static int	YEAR
static int	ZONE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DateTimePatternGenerator() Only for use by subclasses

Method Summary

Methods

Modifier and Type	Method and Description
DateTimePatternGenerator	addPattern(String pattern, boolean override, DateTimePatternGenerator.PatternInfo returnInfo) Adds a pattern to the generator.
DateTimePatternGenerator	addPatternWithSkeleton(String pattern, String skeletonToUse, boolean override, DateTimePatternGenerator.PatternInfo returnInfo) Deprecated. This API is ICU internal only.
Object	clone() Boilerplate
DateTimePatternGenerator	cloneAsThawed() Boilerplate for Freezable
DateTimePatternGenerator	freeze() Boilerplate for Freezable
static int	getAppendFormatNumber(String string) Deprecated. This API is ICU internal only.
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) Return the best pattern matching the input skeleton.
String	getBestPattern(String skeleton, int options) Return the best pattern matching the input skeleton.
String	getCanonicalSkeletonAllowingDuplicates(String pattern) Deprecated. This API is ICU internal only.
String	getDateTimeFormat() Getter corresponding to setDateTimeFormat.
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 add(...) etc.
String	getFields(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 default FORMAT locale.
static DateTimePatternGenerator	getInstance(ULocale uLocale) Construct a flexible generator according to data for a given locale.
Collection<String>	getRedundants(Collection<String> output) Deprecated. This API is ICU internal only.
String	getSkeleton(String pattern) Utility to return a unique skeleton from a given pattern.
String	getSkeletonAllowingDuplicates(String pattern) Deprecated. This API is ICU internal only.
Map<String,String>	getSkeletons(Map<String,String> 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.
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.
void	setDefaultHourFormatChar(char defaultHourFormatChar) Deprecated. This API is ICU internal only.
boolean	skeletonsAreSimilar(String id, String skeleton) Deprecated. This API is ICU internal only.

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

Status:

Stable ICU 3.6.

YEAR

public static final int YEAR

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

QUARTER

public static final int QUARTER

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

MONTH

public static final int MONTH

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

WEEK_OF_YEAR

public static final int WEEK_OF_YEAR

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

WEEK_OF_MONTH

public static final int WEEK_OF_MONTH

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

WEEKDAY

public static final int WEEKDAY

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

DAY

public static final int DAY

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

DAY_OF_YEAR

public static final int DAY_OF_YEAR

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

DAY_OF_WEEK_IN_MONTH

public static final int DAY_OF_WEEK_IN_MONTH

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

DAYPERIOD

public static final int DAYPERIOD

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

HOUR

public static final int HOUR

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

MINUTE

public static final int MINUTE

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

SECOND

public static final int SECOND

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

FRACTIONAL_SECOND

public static final int FRACTIONAL_SECOND

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

ZONE

public static final int ZONE

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

TYPE_LIMIT

public static final int TYPE_LIMIT

See Also:

Constant Field Values

Status:

Stable ICU 3.6.

MATCH_NO_OPTIONS

public static final int MATCH_NO_OPTIONS

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

See Also:

getBestPattern(String, int), replaceFieldTypes(String, String, int), Constant Field Values

Status:

Stable ICU 4.4.

MATCH_HOUR_FIELD_LENGTH

public static final int MATCH_HOUR_FIELD_LENGTH

Option mask for forcing the width of hour field.

See Also:

getBestPattern(String, int), replaceFieldTypes(String, String, int), Constant Field Values

Status:

Stable ICU 4.4.

MATCH_MINUTE_FIELD_LENGTH

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

Status:

Internal. This API is ICU internal only.

MATCH_SECOND_FIELD_LENGTH

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

Status:

Internal. This API is ICU internal only.

MATCH_ALL_FIELDS_LENGTH

public static final int MATCH_ALL_FIELDS_LENGTH

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

See Also:

getBestPattern(String, int), replaceFieldTypes(String, String, int), Constant Field Values

Status:

Stable ICU 4.4.

Constructor Detail

DateTimePatternGenerator

protected DateTimePatternGenerator()

Only for use by subclasses

Status:

Stable ICU 3.6.

Method Detail

getEmptyInstance

public static DateTimePatternGenerator getEmptyInstance()

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

Status:

Stable ICU 3.6.

getInstance

public static DateTimePatternGenerator getInstance()

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

See Also:

ULocale.Category.FORMAT

Status:

Stable ICU 3.6.

getInstance

public static DateTimePatternGenerator getInstance(ULocale uLocale)

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

Parameters:

uLocale - The locale to pass.

Status:

Stable ICU 3.6.

getFrozenInstance

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.

Status:

Internal. This API is ICU internal only.

getDefaultHourFormatChar

public char getDefaultHourFormatChar()

Deprecated. This API is ICU internal only.

Status:

Internal. This API is ICU internal only.

setDefaultHourFormatChar

public void setDefaultHourFormatChar(char defaultHourFormatChar)

Deprecated. This API is ICU internal only.

Status:

Internal. This API is ICU internal only.

getAppendFormatNumber

public static int getAppendFormatNumber(String string)

Deprecated. This API is ICU internal only.

Status:

Internal. This API is ICU internal only.

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.

Returns:

Best pattern matching the input skeleton.

Status:

Stable ICU 3.6.

getBestPattern

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

Status:

Stable ICU 4.4.

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

Parameters:

pattern - Pattern to add.

override - When existing values are to be overridden use true, otherwise use false.

returnInfo - Returned information.

Status:

Stable ICU 3.6.

addPatternWithSkeleton

public DateTimePatternGenerator addPatternWithSkeleton(String pattern,
                                              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.

Status:

Internal. This API is ICU internal only.

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"

Status:

Stable ICU 3.6.

getSkeletonAllowingDuplicates

public String getSkeletonAllowingDuplicates(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"

Status:

Internal. This API is ICU internal only.

getCanonicalSkeletonAllowingDuplicates

public String getCanonicalSkeletonAllowingDuplicates(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"

Status:

Internal. This API is ICU internal only.

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"

Status:

Stable ICU 3.6.

getSkeletons

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

Status:

Stable ICU 3.6.

getBaseSkeletons

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

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

Status:

Stable ICU 3.6.

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 - For the pattern to match to.

Returns:

pattern adjusted to match the skeleton fields widths and subtypes.

Status:

Stable ICU 3.6.

replaceFieldTypes

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.

Status:

Stable ICU 4.4.

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.

Status:

Stable ICU 3.6.

getDateTimeFormat

public String getDateTimeFormat()

Getter corresponding to setDateTimeFormat.

Returns:

pattern

Status:

Stable ICU 3.6.

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

Status:

Stable ICU 3.6.

getDecimal

public String getDecimal()

Getter corresponding to setDecimal.

Returns:

string corresponding to the decimal point

Status:

Stable ICU 3.6.

getRedundants

public Collection<String> getRedundants(Collection<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.

Status:

Internal. This API is ICU internal only.

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

Status:

Stable ICU 3.6.

getAppendItemFormat

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

Status:

Stable ICU 3.6.

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 - Index of the append item names.

value - The value to set the item to.

Status:

Stable ICU 3.6.

getAppendItemName

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

Status:

Stable ICU 3.6.

isSingleField

public static boolean isSingleField(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

Status:

Internal. This API is ICU internal only.

isFrozen

public boolean isFrozen()

Boilerplate for Freezable

Specified by:

isFrozen in interface Freezable<DateTimePatternGenerator>

Status:

Stable ICU 3.6.

freeze

public DateTimePatternGenerator freeze()

Boilerplate for Freezable

Specified by:

freeze in interface Freezable<DateTimePatternGenerator>

Returns:

the object itself.

Status:

Stable ICU 4.4.

cloneAsThawed

public DateTimePatternGenerator cloneAsThawed()

Boilerplate for Freezable

Specified by:

cloneAsThawed in interface Freezable<DateTimePatternGenerator>

Status:

Stable ICU 4.4.

clone

public Object clone()

Boilerplate

Overrides:

clone in class Object

Status:

Stable ICU 3.6.

skeletonsAreSimilar

public boolean skeletonsAreSimilar(String id,
                          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.

Status:

Internal. This API is ICU internal only.

getFields

public String getFields(String pattern)

Deprecated. This API is ICU internal only.

internal routine

Parameters:

pattern - The pattern that is passed.

Returns:

field value

Status:

Internal. This API is ICU internal only.