com.ibm.icu.text.ListFormatter Maven / Gradle / Ivy
The newest version!
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
* Copyright (C) 2012-2016, Google, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/
package com.ibm.icu.text;
import java.io.InvalidObjectException;
import java.text.AttributedCharacterIterator;
import java.text.Format;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Iterator;
import java.util.Locale;
import java.util.regex.Pattern;
import com.ibm.icu.impl.FormattedStringBuilder;
import com.ibm.icu.impl.FormattedValueStringBuilderImpl;
import com.ibm.icu.impl.FormattedValueStringBuilderImpl.SpanFieldPlaceholder;
import com.ibm.icu.impl.ICUCache;
import com.ibm.icu.impl.ICUData;
import com.ibm.icu.impl.ICUResourceBundle;
import com.ibm.icu.impl.SimpleCache;
import com.ibm.icu.impl.SimpleFormatterImpl;
import com.ibm.icu.impl.SimpleFormatterImpl.IterInternal;
import com.ibm.icu.impl.Utility;
import com.ibm.icu.util.ULocale;
import com.ibm.icu.util.UResourceBundle;
/**
* Immutable class for formatting a list, using data from CLDR (or supplied
* separately). The class is not subclassable.
*
* @author Mark Davis
* @stable ICU 50
*/
final public class ListFormatter {
// Compiled SimpleFormatter patterns.
private final String start;
private final String middle;
private final ULocale locale;
private interface PatternHandler {
public String getTwoPattern(String text);
public String getEndPattern(String text);
}
private final PatternHandler patternHandler;
/**
* Type of meaning expressed by the list.
*
* @stable ICU 67
*/
public enum Type {
/**
* Conjunction formatting, e.g. "Alice, Bob, Charlie, and Delta".
*
* @stable ICU 67
*/
AND,
/**
* Disjunction (or alternative, or simply one of) formatting, e.g.
* "Alice, Bob, Charlie, or Delta".
*
* @stable ICU 67
*/
OR,
/**
* Formatting of a list of values with units, e.g. "5 pounds, 12 ounces".
*
* @stable ICU 67
*/
UNITS
};
/**
* Verbosity level of the list patterns.
*
* @stable ICU 67
*/
public enum Width {
/**
* Use list formatting with full words (no abbreviations) when possible.
*
* @stable ICU 67
*/
WIDE,
/**
* Use list formatting of typical length.
*
* @stable ICU 67
*/
SHORT,
/**
* Use list formatting of the shortest possible length.
*
* @stable ICU 67
*/
NARROW,
};
/**
* Class for span fields in FormattedList.
*
* @stable ICU 67
*/
public static final class SpanField extends UFormat.SpanField {
private static final long serialVersionUID = 3563544214705634403L;
/**
* The concrete field used for spans in FormattedList.
*
* Instances of LIST_SPAN should have an associated value, the index
* within the input list that is represented by the span.
*
* @stable ICU 67
*/
public static final SpanField LIST_SPAN = new SpanField("list-span");
private SpanField(String name) {
super(name);
}
/**
* serialization method resolve instances to the constant
* ListFormatter.SpanField values
* @internal
* @deprecated This API is ICU internal only.
*/
@Deprecated
@Override
protected Object readResolve() throws InvalidObjectException {
if (this.getName().equals(LIST_SPAN.getName()))
return LIST_SPAN;
throw new InvalidObjectException("An invalid object.");
}
}
/**
* Field selectors for format fields defined by ListFormatter.
* @stable ICU 67
*/
public static final class Field extends Format.Field {
private static final long serialVersionUID = -8071145668708265437L;
/**
* The literal text in the result which came from the resources.
* @stable ICU 67
*/
public static Field LITERAL = new Field("literal");
/**
* The element text in the result which came from the input strings.
* @stable ICU 67
*/
public static Field ELEMENT = new Field("element");
private Field(String name) {
super(name);
}
/**
* Serialization method resolve instances to the constant Field values
*
* @internal
* @deprecated This API is ICU internal only.
*/
@Deprecated
@Override
protected Object readResolve() throws InvalidObjectException {
if (this.getName().equals(LITERAL.getName()))
return LITERAL;
if (this.getName().equals(ELEMENT.getName()))
return ELEMENT;
throw new InvalidObjectException("An invalid object.");
}
}
/**
* An immutable class containing the result of a list formatting operation.
*
* Instances of this class are immutable and thread-safe.
*
* Not intended for public subclassing.
*
* @stable ICU 67
*/
public static final class FormattedList implements FormattedValue {
private final FormattedStringBuilder string;
FormattedList(FormattedStringBuilder string) {
this.string = string;
}
/**
* {@inheritDoc}
* @stable ICU 67
*/
@Override
public String toString() {
return string.toString();
}
/**
* {@inheritDoc}
* @stable ICU 67
*/
@Override
public int length() {
return string.length();
}
/**
* {@inheritDoc}
* @stable ICU 67
*/
@Override
public char charAt(int index) {
return string.charAt(index);
}
/**
* {@inheritDoc}
* @stable ICU 67
*/
@Override
public CharSequence subSequence(int start, int end) {
return string.subString(start, end);
}
/**
* {@inheritDoc}
* @stable ICU 67
*/
@Override
public A appendTo(A appendable) {
return Utility.appendTo(string, appendable);
}
/**
* {@inheritDoc}
* @stable ICU 67
*/
@Override
public boolean nextPosition(ConstrainedFieldPosition cfpos) {
return FormattedValueStringBuilderImpl.nextPosition(string, cfpos, null);
}
/**
* {@inheritDoc}
* @stable ICU 67
*/
@Override
public AttributedCharacterIterator toCharacterIterator() {
return FormattedValueStringBuilderImpl.toCharacterIterator(string, null);
}
}
/**
* Internal: Create a ListFormatter from component strings,
* with definitions as in LDML.
*
* @param two
* string for two items, containing {0} for the first, and {1}
* for the second.
* @param start
* string for the start of a list items, containing {0} for the
* first, and {1} for the rest.
* @param middle
* string for the start of a list items, containing {0} for the
* first part of the list, and {1} for the rest of the list.
* @param end
* string for the end of a list items, containing {0} for the
* first part of the list, and {1} for the last item.
* @internal
* @deprecated This API is ICU internal only.
*/
@Deprecated
public ListFormatter(String two, String start, String middle, String end) {
this(
compilePattern(two, new StringBuilder()),
compilePattern(start, new StringBuilder()),
compilePattern(middle, new StringBuilder()),
compilePattern(end, new StringBuilder()),
null);
}
private ListFormatter(String two, String start, String middle, String end, ULocale locale) {
this.start = start;
this.middle = middle;
this.locale = locale;
this.patternHandler = createPatternHandler(two, end);
}
private static String compilePattern(String pattern, StringBuilder sb) {
return SimpleFormatterImpl.compileToStringMinMaxArguments(pattern, sb, 2, 2);
}
/**
* Create a list formatter that is appropriate for a locale.
*
* @param locale
* the locale in question.
* @return ListFormatter
* @stable ICU 67
*/
public static ListFormatter getInstance(ULocale locale, Type type, Width width) {
String styleName = typeWidthToStyleString(type, width);
if (styleName == null) {
throw new IllegalArgumentException("Invalid list format type/width");
}
return cache.get(locale, styleName);
}
/**
* Create a list formatter that is appropriate for a locale.
*
* @param locale
* the locale in question.
* @return ListFormatter
* @stable ICU 67
*/
public static ListFormatter getInstance(Locale locale, Type type, Width width) {
return getInstance(ULocale.forLocale(locale), type, width);
}
/**
* Create a list formatter that is appropriate for a locale.
*
* @param locale
* the locale in question.
* @return ListFormatter
* @stable ICU 50
*/
public static ListFormatter getInstance(ULocale locale) {
return getInstance(locale, Type.AND, Width.WIDE);
}
/**
* Create a list formatter that is appropriate for a locale.
*
* @param locale
* the locale in question.
* @return ListFormatter
* @stable ICU 50
*/
public static ListFormatter getInstance(Locale locale) {
return getInstance(ULocale.forLocale(locale), Type.AND, Width.WIDE);
}
/**
* Create a list formatter that is appropriate for the default FORMAT locale.
*
* @return ListFormatter
* @stable ICU 50
*/
public static ListFormatter getInstance() {
return getInstance(ULocale.getDefault(ULocale.Category.FORMAT));
}
/**
* Format a list of objects.
*
* @param items
* items to format. The toString() method is called on each.
* @return items formatted into a string
* @stable ICU 50
*/
public String format(Object... items) {
return format(Arrays.asList(items));
}
/**
* Format a collection of objects. The toString() method is called on each.
*
* @param items
* items to format. The toString() method is called on each.
* @return items formatted into a string
* @stable ICU 50
*/
public String format(Collection items) {
return formatImpl(items, false).toString();
}
/**
* Format a list of objects to a FormattedList. You can access the offsets
* of each element from the FormattedList.
*
* @param items
* items to format. The toString() method is called on each.
* @return items formatted into a FormattedList
* @stable ICU 67
*/
public FormattedList formatToValue(Object... items) {
return formatToValue(Arrays.asList(items));
}
/**
* Format a collection of objects to a FormattedList. You can access the offsets
* of each element from the FormattedList.
*
* @param items
* items to format. The toString() method is called on each.
* @return items formatted into a FormattedList
* @stable ICU 67
*/
public FormattedList formatToValue(Collection items) {
return formatImpl(items, true).toValue();
}
// Formats a collection of objects and returns the formatted string plus the offset
// in the string where the index th element appears. index is zero based. If index is
// negative or greater than or equal to the size of items then this function returns -1 for
// the offset.
FormattedListBuilder formatImpl(Collection items, boolean needsFields) {
Iterator it = items.iterator();
int count = items.size();
switch (count) {
case 0:
return new FormattedListBuilder("", needsFields);
case 1:
return new FormattedListBuilder(it.next(), needsFields);
case 2:
Object first = it.next();
Object second = it.next();
return new FormattedListBuilder(first, needsFields)
.append(patternHandler.getTwoPattern(String.valueOf(second)), second, 1);
}
FormattedListBuilder builder = new FormattedListBuilder(it.next(), needsFields);
builder.append(start, it.next(), 1);
for (int idx = 2; idx < count - 1; ++idx) {
builder.append(middle, it.next(), idx);
}
Object last = it.next();
return builder.append(patternHandler.getEndPattern(String.valueOf(last)), last, count - 1);
}
// A static handler just returns the pattern without considering the input text.
private static final class StaticHandler implements PatternHandler {
StaticHandler(String two, String end) {
twoPattern = two;
endPattern = end;
}
@Override
public String getTwoPattern(String text) { return twoPattern; }
@Override
public String getEndPattern(String text) { return endPattern; }
private final String twoPattern;
private final String endPattern;
}
// A contextual handler returns one of the two patterns depending on whether the text matched the regexp.
private static final class ContextualHandler implements PatternHandler {
ContextualHandler(Pattern regexp, String thenTwo, String elseTwo, String thenEnd, String elseEnd) {
this.regexp = regexp;
thenTwoPattern = thenTwo;
elseTwoPattern = elseTwo;
thenEndPattern = thenEnd;
elseEndPattern = elseEnd;
}
@Override
public String getTwoPattern(String text) {
if(regexp.matcher(text).matches()) {
return thenTwoPattern;
} else {
return elseTwoPattern;
}
}
@Override
public String getEndPattern(String text) {
if(regexp.matcher(text).matches()) {
return thenEndPattern;
} else {
return elseEndPattern;
}
}
private final Pattern regexp;
private final String thenTwoPattern;
private final String elseTwoPattern;
private final String thenEndPattern;
private final String elseEndPattern;
}
// Pattern in the ICU Data which might be replaced y by e.
private static final String compiledY = compilePattern("{0} y {1}", new StringBuilder());
// The new pattern to replace y to e
private static final String compiledE = compilePattern("{0} e {1}", new StringBuilder());
// Pattern in the ICU Data which might be replaced o by u.
private static final String compiledO = compilePattern("{0} o {1}", new StringBuilder());
// The new pattern to replace u to o
private static final String compiledU = compilePattern("{0} u {1}", new StringBuilder());
// Condition to change to e.
// Starts with "hi" or "i" but not with "hie" nor "hia"a
private static final Pattern changeToE = Pattern.compile("(i.*|hi|hi[^ae].*)", Pattern.CASE_INSENSITIVE);
// Condition to change to u.
// Starts with "o", "ho", and "8". Also "11" by itself.
private static final Pattern changeToU = Pattern.compile("((o|ho|8).*|11)", Pattern.CASE_INSENSITIVE);
// Pattern in the ICU Data which might need to add a DASH after VAV.
private static final String compiledVav = compilePattern("{0} \u05D5{1}", new StringBuilder());
// Pattern to add a DASH after VAV.
private static final String compiledVavDash = compilePattern("{0} \u05D5-{1}", new StringBuilder());
// Condition to change to VAV follow by a dash.
// Starts with non Hebrew letter.
private static final Pattern changeToVavDash = Pattern.compile("^[\\P{InHebrew}].*$");
// A factory function to create function based on locale
// Handle specal case of Spanish and Hebrew
private PatternHandler createPatternHandler(String two, String end) {
if (this.locale != null) {
String language = this.locale.getLanguage();
if (language.equals("es")) {
boolean twoIsY = two.equals(compiledY);
boolean endIsY = end.equals(compiledY);
if (twoIsY || endIsY) {
return new ContextualHandler(
changeToE, twoIsY ? compiledE : two, two, endIsY ? compiledE : end, end);
}
boolean twoIsO = two.equals(compiledO);
boolean endIsO = end.equals(compiledO);
if (twoIsO || endIsO) {
return new ContextualHandler(
changeToU, twoIsO ? compiledU : two, two, endIsO ? compiledU : end, end);
}
} else if (language.equals("he") || language.equals("iw")) {
boolean twoIsVav = two.equals(compiledVav);
boolean endIsVav = end.equals(compiledVav);
if (twoIsVav || endIsVav) {
return new ContextualHandler(changeToVavDash,
twoIsVav ? compiledVavDash : two, two, endIsVav ? compiledVavDash : end, end);
}
}
}
return new StaticHandler(two, end);
}
/**
* Returns the pattern to use for a particular item count.
* @param count the item count.
* @return the pattern with {0}, {1}, {2}, etc. For English,
* getPatternForNumItems(3) == "{0}, {1}, and {2}"
* @throws IllegalArgumentException when count is 0 or negative.
* @stable ICU 52
*/
public String getPatternForNumItems(int count) {
if (count <= 0) {
throw new IllegalArgumentException("count must be > 0");
}
ArrayList list = new ArrayList<>();
for (int i = 0; i < count; i++) {
list.add(String.format("{%d}", i));
}
return format(list);
}
/**
* Returns the locale of this object.
* @internal
* @deprecated This API is ICU internal only.
*/
@Deprecated
public ULocale getLocale() {
return locale;
}
// Builds a formatted list
static class FormattedListBuilder {
private FormattedStringBuilder string;
boolean needsFields;
// Start is the first object in the list; If needsFields is true, enable the slightly
// more expensive code path that records offsets of each element.
public FormattedListBuilder(Object start, boolean needsFields) {
string = new FormattedStringBuilder();
this.needsFields = needsFields;
string.setAppendableField(Field.LITERAL);
appendElement(start, 0);
}
// Appends additional object. pattern is a template indicating where the new object gets
// added in relation to the rest of the list. {0} represents the rest of the list; {1}
// represents the new object in pattern. next is the object to be added. position is the
// index of the next object in the list of inputs.
public FormattedListBuilder append(String compiledPattern, Object next, int position) {
assert SimpleFormatterImpl.getArgumentLimit(compiledPattern) == 2;
string.setAppendIndex(0);
long state = 0;
while (true) {
state = IterInternal.step(state, compiledPattern, string);
if (state == IterInternal.DONE) {
break;
}
int argIndex = IterInternal.getArgIndex(state);
if (argIndex == 0) {
string.setAppendIndex(string.length());
} else {
appendElement(next, position);
}
}
return this;
}
private void appendElement(Object element, int position) {
String elementString = element.toString();
if (needsFields) {
SpanFieldPlaceholder field = new SpanFieldPlaceholder();
field.spanField = SpanField.LIST_SPAN;
field.normalField = Field.ELEMENT;
field.value = position;
field.start = -1;
field.length = elementString.length();
string.append(elementString, field);
} else {
string.append(elementString, null);
}
}
public void appendTo(Appendable appendable) {
Utility.appendTo(string, appendable);
}
public int getOffset(int fieldPositionFoundIndex) {
return FormattedValueStringBuilderImpl.findSpan(string, fieldPositionFoundIndex);
}
@Override
public String toString() {
return string.toString();
}
public FormattedList toValue() {
return new FormattedList(string);
}
}
private static class Cache {
private final ICUCache cache =
new SimpleCache<>();
public ListFormatter get(ULocale locale, String style) {
String key = String.format("%s:%s", locale.toString(), style);
ListFormatter result = cache.get(key);
if (result == null) {
result = load(locale, style);
cache.put(key, result);
}
return result;
}
private static ListFormatter load(ULocale ulocale, String style) {
ICUResourceBundle r = (ICUResourceBundle)UResourceBundle.
getBundleInstance(ICUData.ICU_BASE_NAME, ulocale);
StringBuilder sb = new StringBuilder();
return new ListFormatter(
compilePattern(r.getWithFallback("listPattern/" + style + "/2").getString(), sb),
compilePattern(r.getWithFallback("listPattern/" + style + "/start").getString(), sb),
compilePattern(r.getWithFallback("listPattern/" + style + "/middle").getString(), sb),
compilePattern(r.getWithFallback("listPattern/" + style + "/end").getString(), sb),
ulocale);
}
}
static Cache cache = new Cache();
static String typeWidthToStyleString(Type type, Width width) {
switch (type) {
case AND:
switch (width) {
case WIDE:
return "standard";
case SHORT:
return "standard-short";
case NARROW:
return "standard-narrow";
}
break;
case OR:
switch (width) {
case WIDE:
return "or";
case SHORT:
return "or-short";
case NARROW:
return "or-narrow";
}
break;
case UNITS:
switch (width) {
case WIDE:
return "unit";
case SHORT:
return "unit-short";
case NARROW:
return "unit-narrow";
}
}
return null;
}
}