com.ibm.icu.text.SimpleFormatter Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of icu4j Show documentation
Show all versions of icu4j Show documentation
International Component for Unicode for Java (ICU4J) is a mature, widely used Java library
providing Unicode and Globalization support
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html#License
/*
*******************************************************************************
* Copyright (C) 2014-2016, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/
package com.ibm.icu.text;
import com.ibm.icu.impl.SimpleFormatterImpl;
/**
* Formats simple patterns like "{1} was born in {0}".
* Minimal subset of MessageFormat; fast, simple, minimal dependencies.
* Supports only numbered arguments with no type nor style parameters,
* and formats only string values.
* Quoting via ASCII apostrophe compatible with ICU MessageFormat default behavior.
*
* Factory methods throw exceptions for syntax errors
* and for too few or too many arguments/placeholders.
*
*
SimpleFormatter objects are immutable and can be safely cached like strings.
*
*
Example:
*
* SimpleFormatter fmt = SimpleFormatter.compile("{1} '{born}' in {0}");
*
* // Output: "paul {born} in england"
* System.out.println(fmt.format("england", "paul"));
*
*
* @see MessageFormat
* @see MessagePattern.ApostropheMode
* @stable ICU 57
*/
public final class SimpleFormatter {
// For internal use in Java, use SimpleFormatterImpl directly instead:
// It is most efficient to compile patterns to compiled-pattern strings
// and use them with static methods.
// (Avoids allocating SimpleFormatter wrapper objects.)
/**
* Binary representation of the compiled pattern.
* @see SimpleFormatterImpl
*/
private final String compiledPattern;
private SimpleFormatter(String compiledPattern) {
this.compiledPattern = compiledPattern;
}
/**
* Creates a formatter from the pattern string.
*
* @param pattern The pattern string.
* @return The new SimpleFormatter object.
* @throws IllegalArgumentException for bad argument syntax.
* @stable ICU 57
*/
public static SimpleFormatter compile(CharSequence pattern) {
return compileMinMaxArguments(pattern, 0, Integer.MAX_VALUE);
}
/**
* Creates a formatter from the pattern string.
* The number of arguments checked against the given limits is the
* highest argument number plus one, not the number of occurrences of arguments.
*
* @param pattern The pattern string.
* @param min The pattern must have at least this many arguments.
* @param max The pattern must have at most this many arguments.
* @return The new SimpleFormatter object.
* @throws IllegalArgumentException for bad argument syntax and too few or too many arguments.
* @stable ICU 57
*/
public static SimpleFormatter compileMinMaxArguments(CharSequence pattern, int min, int max) {
StringBuilder sb = new StringBuilder();
String compiledPattern = SimpleFormatterImpl.compileToStringMinMaxArguments(pattern, sb, min, max);
return new SimpleFormatter(compiledPattern);
}
/**
* @return The max argument number + 1.
* @stable ICU 57
*/
public int getArgumentLimit() {
return SimpleFormatterImpl.getArgumentLimit(compiledPattern);
}
/**
* Formats the given values.
* @stable ICU 57
*/
public String format(CharSequence... values) {
return SimpleFormatterImpl.formatCompiledPattern(compiledPattern, values);
}
/**
* Formats the given values, appending to the appendTo builder.
*
* @param appendTo Gets the formatted pattern and values appended.
* @param offsets offsets[i] receives the offset of where
* values[i] replaced pattern argument {i}.
* Can be null, or can be shorter or longer than values.
* If there is no {i} in the pattern, then offsets[i] is set to -1.
* @param values The argument values.
* An argument value must not be the same object as appendTo.
* values.length must be at least getArgumentLimit().
* Can be null if getArgumentLimit()==0.
* @return appendTo
* @stable ICU 57
*/
public StringBuilder formatAndAppend(
StringBuilder appendTo, int[] offsets, CharSequence... values) {
return SimpleFormatterImpl.formatAndAppend(compiledPattern, appendTo, offsets, values);
}
/**
* Formats the given values, replacing the contents of the result builder.
* May optimize by actually appending to the result if it is the same object
* as the value corresponding to the initial argument in the pattern.
*
* @param result Gets its contents replaced by the formatted pattern and values.
* @param offsets offsets[i] receives the offset of where
* values[i] replaced pattern argument {i}.
* Can be null, or can be shorter or longer than values.
* If there is no {i} in the pattern, then offsets[i] is set to -1.
* @param values The argument values.
* An argument value may be the same object as result.
* values.length must be at least getArgumentLimit().
* @return result
* @stable ICU 57
*/
public StringBuilder formatAndReplace(
StringBuilder result, int[] offsets, CharSequence... values) {
return SimpleFormatterImpl.formatAndReplace(compiledPattern, result, offsets, values);
}
/**
* Returns a string similar to the original pattern, only for debugging.
*
* @stable ICU 57
*/
@Override
public String toString() {
String[] values = new String[getArgumentLimit()];
for (int i = 0; i < values.length; i++) {
values[i] = "{" + i + '}';
}
return formatAndAppend(new StringBuilder(), null, values).toString();
}
/**
* Returns the pattern text with none of the arguments.
* Like formatting with all-empty string values.
*
* @stable ICU 57
*/
public String getTextWithNoArguments() {
return SimpleFormatterImpl.getTextWithNoArguments(compiledPattern);
}
}