Class ListFormat
- All Implemented Interfaces:
Serializable
,Cloneable
ListFormat
formats or parses a list of strings in a locale-sensitive way.
Use ListFormat
to construct a list of strings displayed for end users.
For example, displaying a list of 3 weekdays, e.g. "Monday", "Wednesday", "Friday"
as "Monday, Wednesday, and Friday" in an inclusive list type. This class provides
the functionality defined in Unicode Consortium's LDML specification for
List Patterns.
Three formatting types are provided: STANDARD
, OR
,
and UNIT
, which determines the punctuation
between the strings and the connecting words if any. Also, three formatting styles for each
type are provided: FULL
, SHORT
, and
NARROW
, suitable for how the strings are abbreviated (or not).
The following snippet is an example of formatting
the list of Strings "Foo", "Bar", "Baz"
in US English with
STANDARD
type and FULL
style:
ListFormat.getInstance(Locale.US, ListFormat.Type.STANDARD, ListFormat.Style.FULL)
.format(List.of("Foo", "Bar", "Baz"))
FULL | SHORT | NARROW | |
---|---|---|---|
STANDARD | Foo, Bar, and Baz | Foo, Bar, & Baz | Foo, Bar, Baz |
OR | Foo, Bar, or Baz | Foo, Bar, or Baz | Foo, Bar, or Baz |
UNIT | Foo, Bar, Baz | Foo, Bar, Baz | Foo Bar Baz |
Alternatively, Locale, Type, and/or Style independent instances
can be created with getInstance(String[])
. The String array to the
method specifies the delimiting patterns for the start/middle/end portion of
the formatted string, as well as optional specialized patterns for two or three
elements. Refer to the method description for more detail.
On parsing, if some ambiguity is found in the input string, such as delimiting sequences in the input string, the result, when formatted with the same formatting, does not re-produce the input string. For example, a two element String list "a, b,", "c" will be formatted as "a, b, and c", but may be parsed as three elements "a", "b", "c".
- Implementation Requirements:
- This class is immutable and thread-safe
- Since:
- 22
- External Specifications
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic enum
static enum
Nested classes/interfaces inherited from class java.text.Format
Format.Field
-
Method Summary
Modifier and TypeMethodDescriptionboolean
Compares the specified object with thisListFormat
for equality.format
(Object obj, StringBuffer toAppendTo, FieldPosition pos) Formats an object and appends the resulting text to a given string buffer.Returns the string that consists of the input strings, concatenated with the patterns of thisListFormat
.formatToCharacterIterator
(Object arguments) Formats an Object producing anAttributedCharacterIterator
.static Locale[]
Returns the available locales that support ListFormat.static ListFormat
static ListFormat
getInstance
(String[] patterns) Returns the ListFormat object for the specified patterns.static ListFormat
getInstance
(Locale locale, ListFormat.Type type, ListFormat.Style style) Returns theLocale
of this ListFormat.String[]
Returns the patterns used in this ListFormat.int
hashCode()
Returns a hash code value for this object.Returns the parsed list of strings from thesource
string.parseObject
(String source, ParsePosition parsePos) Parses text from a string to produce a list of strings.toString()
Returns a string identifying thisListFormat
, for debugging.Methods inherited from class java.text.Format
clone, format, parseObject
-
Method Details
-
getAvailableLocales
Returns the available locales that support ListFormat.- Returns:
- the available locales that support ListFormat
-
getInstance
- Returns:
- the ListFormat object for the default
FORMAT Locale
,STANDARD
type, andFULL
style
-
getInstance
- Parameters:
locale
-Locale
to be used, not nulltype
- type of the ListFormat. One ofSTANDARD
,OR
, orUNIT
, not nullstyle
- style of the ListFormat. One ofFULL
,SHORT
, orNARROW
, not null- Returns:
- the ListFormat object for the specified
Locale
,Type
, andStyle
- Throws:
NullPointerException
- if any of the arguments are null
-
getInstance
Returns the ListFormat object for the specified patterns.This factory returns an instance based on the customized patterns array, instead of letting the runtime provide appropriate patterns for the
Locale
,Type
, orStyle
.The patterns array should contain five String patterns, each corresponding to the Unicode LDML's
listPatternPart
, i.e., "start", "middle", "end", two element, and three element patterns in this order. Each pattern contains "{0}" and "{1}" (and "{2}" for the three element pattern) placeholders that are substituted with the passed input strings on formatting. If the length of the patterns array is not 5, anIllegalArgumentException
is thrown.Each pattern string is first parsed as follows. Literals in parentheses, such as "start_before", are optional:
If two or three pattern string is empty, it falls back tostart := (start_before){0}start_between{1} middle := {0}middle_between{1} end := {0}end_between{1}(end_after) two := (two_before){0}two_between{1}(two_after) three := (three_before){0}three_between1{1}three_between2{2}(three_after)
"(start_before){0}end_between{1}(end_after)"
,"(start_before){0}start_between{1}end_between{2}(end_after)"
respectively. If parsing of any pattern string for start, middle, end, two, or three fails, it throws anIllegalArgumentException
.On formatting, the input string list with
n
elements substitutes above placeholders based on the number of elements:
As an example, the following table shows a pattern array which is equivalent ton = 1: {0} n = 2: parsed pattern for "two" n = 3: parsed pattern for "three" n > 3: (start_before){0}start_between{1}middle_between{2} ... middle_between{m}end_between{n}(end_after)
STANDARD
type,FULL
style in US English:Pattern Kind Pattern String start "{0}, {1}" middle "{0}, {1}" end "{0}, and {1}" two "{0} and {1}" three "" Input String List Formatted String "Foo", "Bar", "Baz", "Qux" "Foo, Bar, Baz, and Qux" "Foo", "Bar", "Baz" "Foo, Bar, and Baz" "Foo", "Bar" "Foo and Bar" "Foo" "Foo" - Parameters:
patterns
- array of patterns, not null- Returns:
- the ListFormat object for the specified patterns
- Throws:
IllegalArgumentException
- if the lengthpatterns
array is not 5, or any ofstart
,middle
,end
,two
, orthree
patterns cannot be parsed.NullPointerException
- ifpatterns
is null.
-
getLocale
Returns theLocale
of this ListFormat. Thelocale
is defined bygetInstance(Locale, Type, Style)
orgetInstance(String[])
.- Returns:
- the
Locale
of this ListFormat
-
getPatterns
Returns the patterns used in this ListFormat. Thepatterns
are defined bygetInstance(Locale, Type, Style)
orgetInstance(String[])
.- Returns:
- the patterns used in this ListFormat
-
format
Returns the string that consists of the input strings, concatenated with the patterns of thisListFormat
.- API Note:
- Formatting the string from an excessively long list may exceed memory or string sizes.
- Parameters:
input
- The list of input strings to format. There should at least one String element in this list, otherwise anIllegalArgumentException
is thrown.- Returns:
- the string that consists of the input strings, concatenated with the
patterns of this
ListFormat
- Throws:
IllegalArgumentException
- if the length ofinput
is zero.NullPointerException
- ifinput
is null.
-
format
Formats an object and appends the resulting text to a given string buffer. The object should either be a List or an array of Objects.- Specified by:
format
in classFormat
- API Note:
- Formatting the string from an excessively long list or array may exceed memory or string sizes.
- Parameters:
obj
- The object to format. Must be a List or an array of Object.toAppendTo
- where the text is to be appendedpos
- Ignored. Not used in ListFormat. May be null- Returns:
- the string buffer passed in as
toAppendTo
, with formatted text appended - Throws:
NullPointerException
- ifobj
ortoAppendTo
is nullIllegalArgumentException
- ifobj
is neither aList
nor an array ofObject
s, or its length is zero.
-
parse
Returns the parsed list of strings from thesource
string. Note thatformat(List)
and this method may not guarantee a round-trip, if the input strings contain ambiguous delimiters. For example, a two element String list"a, b,", "c"
will be formatted as"a, b, and c"
, but may be parsed as three elements"a", "b", "c"
.- Parameters:
source
- the string to parse, not null.- Returns:
- the parsed list of strings from the
source
string - Throws:
ParseException
- if parse failedNullPointerException
- if source is null
-
parseObject
Parses text from a string to produce a list of strings.The method attempts to parse text starting at the index given by
parsePos
. If parsing succeeds, then the index ofparsePos
is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed object is returned. The updatedparsePos
can be used to indicate the starting point for the next call to parse additional text. If an error occurs, then the index ofparsePos
is not changed, the error index ofparsePos
is set to the index of the character where the error occurred, and null is returned. See theparse(String)
method for more information on list parsing.- Specified by:
parseObject
in classFormat
- Parameters:
source
- A string, part of which should be parsed.parsePos
- AParsePosition
object with index and error index information as described above.- Returns:
- A list of string parsed from the
source
. In case of error, returns null. - Throws:
NullPointerException
- ifsource
orparsePos
is null.IndexOutOfBoundsException
- if the starting index given byparsePos
is outsidesource
.
-
formatToCharacterIterator
Description copied from class:Format
Formats an Object producing anAttributedCharacterIterator
. You can use the returnedAttributedCharacterIterator
to build the resulting String, as well as to determine information about the resulting String.Each attribute key of the AttributedCharacterIterator will be of type
Field
. It is up to eachFormat
implementation to define what the legal values are for each attribute in theAttributedCharacterIterator
, but typically the attribute key is also used as the attribute value.- Overrides:
formatToCharacterIterator
in classFormat
- Parameters:
arguments
- The object to format- Returns:
- AttributedCharacterIterator describing the formatted value.
-
equals
Compares the specified object with thisListFormat
for equality. Returnstrue
if the specified object is also aListFormat
, andlocale
andpatterns
, returned fromgetLocale()
andgetPatterns()
respectively, are equal. -
hashCode
public int hashCode()Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided byHashMap
.The general contract of
hashCode
is:- Whenever it is invoked on the same object more than once during
an execution of a Java application, the
hashCode
method must consistently return the same integer, provided no information used inequals
comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. - If two objects are equal according to the
equals
method, then calling thehashCode
method on each of the two objects must produce the same integer result. - It is not required that if two objects are unequal
according to the
equals
method, then calling thehashCode
method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
- Whenever it is invoked on the same object more than once during
an execution of a Java application, the
-
toString
-