W3cubDocs

/OpenJDK 25

Class ListFormat

java.lang.Object
java.text.Format
java.text.ListFormat
All Implemented Interfaces:
Serializable, Cloneable
public final class ListFormat extends Format
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"))
This will produce the concatenated list string, "Foo, Bar, and Baz" as seen in the following:
Formatting examples
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
Note: these examples are from CLDR, there could be different results from other locale providers.

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 Type Class Description
static enum  ListFormat.Style
A ListFormat style - FULL, SHORT, and NARROW.
static enum  ListFormat.Type
A ListFormat type - STANDARD, OR, and UNIT.

Nested classes/interfaces declared in class Format

Format.Field

Method Summary

Modifier and Type Method Description
boolean equals(Object obj)
Compares the specified object with this ListFormat for equality.
StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
Formats an object and appends the resulting text to a given string buffer.
String format(List<String> input)
Returns the string that consists of the input strings, concatenated with the patterns of this ListFormat.
static Locale[] getAvailableLocales()
Returns the available locales that support ListFormat.
static ListFormat getInstance()
Returns the ListFormat object for the default FORMAT Locale, STANDARD type, and FULL style.
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 the ListFormat object for the specified Locale, Type, and Style.
Locale getLocale()
Returns the Locale of this ListFormat.
String[] getPatterns()
Returns the patterns used in this ListFormat.
List<String> parse(String source)
Returns the parsed list of strings from the source string.
Object parseObject(String source, ParsePosition parsePos)
Parses text from a string to produce a list of strings.
String toString()
Returns a string identifying this ListFormat, for debugging.

Methods declared in class Format

clone, format, formatToCharacterIterator, parseObject

Methods declared in class Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

getAvailableLocales

public static Locale[] getAvailableLocales()
Returns the available locales that support ListFormat.
Returns:
the available locales that support ListFormat

getInstance

public static ListFormat getInstance()
Returns the ListFormat object for the default FORMAT Locale, STANDARD type, and FULL style.
Returns:
the ListFormat object for the default FORMAT Locale, STANDARD type, and FULL style

getInstance

public static ListFormat getInstance(Locale locale, ListFormat.Type type, ListFormat.Style style)
Returns the ListFormat object for the specified Locale, Type, and Style.
Parameters:
locale - Locale to be used, not null
type - type of the ListFormat. One of STANDARD, OR, or UNIT, not null
style - style of the ListFormat. One of FULL, SHORT, or NARROW, not null
Returns:
the ListFormat object for the specified Locale, Type, and Style
Throws:
NullPointerException - if any of the arguments are null

getInstance

public static ListFormat getInstance(String[] patterns)
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, or Style.

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, an IllegalArgumentException is thrown.

Each pattern string is first parsed as follows. Literals in parentheses, such as "start_before", are optional: 

start := (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)
If two or three pattern string is empty, it falls back to "(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 an IllegalArgumentException.

On formatting, the input string list with n elements substitutes above placeholders based on the number of elements: 

n = 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)
As an example, the following table shows a pattern array which is equivalent to STANDARD type, FULL style in US English:
Standard/Full Patterns in US English
Pattern Kind Pattern String
start "{0}, {1}"
middle "{0}, {1}"
end "{0}, and {1}"
two "{0} and {1}"
three ""
Here are the resulting formatted strings with the above pattern array.
Formatting examples
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 length patterns array is not 5, or any of start, middle, end, two, or three patterns cannot be parsed.
NullPointerException - if patterns is null.

getLocale

public Locale getLocale()
Returns the Locale of this ListFormat. The locale is defined by getInstance(Locale, Type, Style) or getInstance(String[]).
Returns:
the Locale of this ListFormat

getPatterns

public String[] getPatterns()
Returns the patterns used in this ListFormat. The patterns are defined by getInstance(Locale, Type, Style) or getInstance(String[]).
Returns:
the patterns used in this ListFormat

format

public String format(List<String> input)
Returns the string that consists of the input strings, concatenated with the patterns of this ListFormat.
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 an IllegalArgumentException is thrown.
Returns:
the string that consists of the input strings, concatenated with the patterns of this ListFormat
Throws:
IllegalArgumentException - if the length of input is zero.
NullPointerException - if input is null.

format

public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
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 class Format
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 appended
pos - Ignored. Not used in ListFormat. May be null
Returns:
the string buffer passed in as toAppendTo, with formatted text appended
Throws:
NullPointerException - if obj or toAppendTo is null
IllegalArgumentException - if obj is neither a List nor an array of Objects, or its length is zero.

parse

public List<String> parse(String source) throws ParseException
Returns the parsed list of strings from the source string. Note that format(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 failed
NullPointerException - if source is null

parseObject

public Object parseObject(String source, ParsePosition parsePos)
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 of parsePos 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 updated parsePos can be used to indicate the starting point for the next call to parse additional text. If an error occurs, then the index of parsePos is not changed, the error index of parsePos is set to the index of the character where the error occurred, and null is returned. See the parse(String) method for more information on list parsing.

Specified by:
parseObject in class Format
Parameters:
source - A string, part of which should be parsed.
parsePos - A ParsePosition 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 - if source or parsePos is null.
IndexOutOfBoundsException - if the starting index given by parsePos is outside source.

equals

public boolean equals(Object obj)
Compares the specified object with this ListFormat for equality. Returns true if the specified object is also a ListFormat, and locale and patterns, returned from getLocale() and getPatterns() respectively, are equal.
Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality.
Returns:
true if the specified object is equal to this ListFormat
See Also:

toString

public String toString()
Returns a string identifying this ListFormat, for debugging.
Overrides:
toString in class Object
Returns:
a string identifying this ListFormat, for debugging

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/text/ListFormat.html