** If there is no match, then either the first or last index is used, depending * on whether the number (X) is too low or too high. If the limit array is not * in ascending order, the results of formatting will be incorrect. ChoiceFormat * also accepts* X matches j if and only if limit[j] ≤ X < limit[j+1] **
\u221E as equivalent to infinity(INF).
*
* * Note: * {@code ChoiceFormat} differs from the other {@code Format} * classes in that you create a {@code ChoiceFormat} object with a * constructor (not with a {@code getInstance} style factory * method). The factory methods aren't necessary because {@code ChoiceFormat} * doesn't require any complex setup for a given locale. In fact, * {@code ChoiceFormat} doesn't implement any locale specific behavior. * *
** * Note:The relation ≤ is not equivalent to <= * **
* *- Pattern: *
- SubPattern *("|" SubPattern) *
*
* *- SubPattern: *
- Limit Relation Format *
- Note: Each additional SubPattern must have an ascending Limit-Relation interval
**
* *- Limit: *
- Number / "∞" / "-∞" *
*
* *- Number: *
- ["-"] *(Digit) 1*(Decimal / Digit) *(Digit) [Exponent] *
*
* *- Decimal: *
- 1*(Digit ".") / 1*("." Digit) *
*
* *- Digit: *
- 0 - 9 *
*
* *- Exponent: *
- *(Digit) Digit ExponentSymbol Digit *(Digit) *
*
* *- ExponentSymbol: *
- "e" / "E" *
*
* *- Relation: *
- "#" / "<" / "≤" *
*
* *- Format: *
- Any characters except the special pattern character '|' *
To use a reserved special pattern character within a Format pattern, * it must be single quoted. For example, {@code new ChoiceFormat("1#'|'foo'|'").format(1)} * returns {@code "|foo|"}. * Use two single quotes in a row to produce a literal single quote. For example, * {@code new ChoiceFormat("1# ''one'' ").format(1)} returns {@code " 'one' "}. * *
* A {@code ChoiceFormat} can be constructed using either an array of formats * and an array of limits or a string pattern. When constructing with * format and limit arrays, the length of these arrays must be the same. * * For example, *
* Below is an example of constructing a ChoiceFormat with arrays to format * and parse values: * {@snippet lang=java : * double[] limits = {1,2,3,4,5,6,7}; * String[] dayOfWeekNames = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}; * ChoiceFormat form = new ChoiceFormat(limits, dayOfWeekNames); * ParsePosition status = new ParsePosition(0); * for (double i = 0.0; i <= 8.0; ++i) { * status.setIndex(0); * System.out.println(i + " -> " + form.format(i) + " -> " * + form.parse(form.format(i),status)); * } * } * *
Below is an example of constructing a ChoiceFormat with a String pattern:
* {@snippet lang=java :
* ChoiceFormat fmt = new ChoiceFormat(
* "-1#is negative| 0#is zero or fraction | 1#is one |1.0
* Choice formats are not synchronized.
* It is recommended to create separate format instances for each thread.
* If multiple threads access a format concurrently, it must be synchronized
* externally.
*
* @apiNote A subclass could perform more consistent pattern validation by
* throwing an {@code IllegalArgumentException} for all incorrect cases.
* See the {@code Implementation Note} for this implementation's behavior regarding
* incorrect patterns.
* This class inherits instance methods from {@code NumberFormat} it does
* not utilize; a subclass could override and throw {@code
* UnsupportedOperationException} for such methods.
* @implNote Given an incorrect pattern, this implementation may either
* throw an exception or succeed and discard the incorrect portion. A {@code
* NumberFormatException} is thrown if a {@code limit} can not be
* parsed as a numeric value and an {@code IllegalArgumentException} is thrown
* if a {@code SubPattern} is missing, or the intervals are not ascending.
* Discarding the incorrect portion may result in a ChoiceFormat with
* empty {@code limits} and {@code formats}.
*
*
* @see DecimalFormat
* @see MessageFormat
* @author Mark Davis
* @since 1.1
*/
public class ChoiceFormat extends NumberFormat {
// Proclaim serial compatibility with 1.1 FCS
@java.io.Serial
private static final long serialVersionUID = 1795184449645032964L;
/**
* Apply the given pattern to this ChoiceFormat object. The syntax and error
* related caveats for the ChoiceFormat pattern can be found in the
* {@linkplain ##patterns Patterns} section. Unlike {@link #setChoices(double[],
* String[])}, this method will throw an {@code IllegalArgumentException} if
* the {@code limits} are not in ascending order.
*
* @param newPattern a pattern string
* @throws NullPointerException if {@code newPattern}
* is {@code null}
* @throws IllegalArgumentException if {@code newPattern}
* violates the pattern syntax
* @see #ChoiceFormat(String)
*/
public void applyPattern(String newPattern) {
Objects.requireNonNull(newPattern, "newPattern must not be null");
applyPatternImpl(newPattern);
}
/**
* Implementation of applying a pattern to this ChoiceFormat.
* This method processes a String pattern in accordance with the ChoiceFormat
* pattern syntax and populates the internal {@code limits} and {@code formats}
* array variables. See the {@linkplain ##patterns} section for
* further understanding of certain special characters: "#", "<", "\u2264", "|".
*/
private void applyPatternImpl(String newPattern) {
// Set up components
ArrayList
* For example,
* {@snippet lang=java :
* var fmt = new ChoiceFormat("0#foo|1#bar|2#baz");
* fmt.parse("baz", new ParsePosition(0)); // returns 2.0
* fmt.parse("quux", new ParsePosition(0)); // returns NaN
* }
*
* @param text the source text.
* @param status an input-output parameter. On input, the
* status.index field indicates the first character of the
* source text that should be parsed. On exit, if no error
* occurred, status.index is set to the first unparsed character
* in the source text. On exit, if an error did occur,
* status.index is unchanged and status.errorIndex is set to the
* first index of the character that caused the parse to fail.
* @return A Number which represents the {@code limit} corresponding to the
* {@code format} parsed, or {@code Double.NaN} if the parse fails.
* @throws NullPointerException if {@code status} is {@code null}
* or if {@code text} is {@code null} and the list of
* choice strings is not empty.
*/
@Override
public Number parse(String text, ParsePosition status) {
// find the best number (defined as the one with the longest parse)
int start = status.index;
int furthest = start;
double bestNumber = Double.NaN;
double tempNumber = 0.0;
for (int i = 0; i < choiceFormats.length; ++i) {
String tempString = choiceFormats[i];
if (text.regionMatches(start, tempString, 0, tempString.length())) {
status.index = start + tempString.length();
tempNumber = choiceLimits[i];
if (status.index > furthest) {
furthest = status.index;
bestNumber = tempNumber;
if (furthest == text.length()) break;
}
}
}
status.index = furthest;
if (status.index == start) {
status.errorIndex = furthest;
}
return Double.valueOf(bestNumber);
}
/**
* @since 23
*/
@Override
public boolean isStrict() {
throw new UnsupportedOperationException(
"ChoiceFormat does not utilize leniency when parsing");
}
/**
* @since 23
*/
@Override
public void setStrict(boolean strict) {
throw new UnsupportedOperationException(
"ChoiceFormat does not utilize leniency when parsing");
}
/**
* Finds the least double greater than {@code d}.
* If {@code NaN}, returns same value.
* Used to make half-open intervals.
*
* @implNote This is equivalent to calling
* {@link Math#nextUp(double) Math.nextUp(d)}
*
* @param d the reference value
* @return the least double value greater than {@code d}
* @see #previousDouble
*/
public static final double nextDouble (double d) {
return Math.nextUp(d);
}
/**
* Finds the least double greater than {@code d} (if {@code positive} is
* {@code true}), or the greatest double less than {@code d} (if
* {@code positive} is {@code false}).
* If {@code NaN}, returns same value.
*
* @implNote This is equivalent to calling
* {@code positive ? Math.nextUp(d) : Math.nextDown(d)}
*
* @param d the reference value
* @param positive {@code true} if the least double is desired;
* {@code false} otherwise
* @return the least or greater double value
*/
public static double nextDouble (double d, boolean positive) {
return positive ? Math.nextUp(d) : Math.nextDown(d);
}
/**
* Finds the greatest double less than {@code d}.
* If {@code NaN}, returns same value.
*
* @implNote This is equivalent to calling
* {@link Math#nextDown(double) Math.nextDown(d)}
*
* @param d the reference value
* @return the greatest double value less than {@code d}
* @see #nextDouble
*/
public static final double previousDouble (double d) {
return Math.nextDown(d);
}
/**
* Overrides Cloneable
*/
@Override
public Object clone() {
ChoiceFormat other = (ChoiceFormat) super.clone();
// for primitives or immutables, shallow clone is enough
other.choiceLimits = choiceLimits.clone();
other.choiceFormats = choiceFormats.clone();
return other;
}
/**
* {@return the hash code for this {@code ChoiceFormat}}
*
* @implSpec This method calculates the hash code value using the values returned by
* {@link #getFormats()} and {@link #getLimits()}.
* @see Object#hashCode()
*/
@Override
public int hashCode() {
int result = choiceLimits.length;
if (choiceFormats.length > 0) {
// enough for reasonable distribution
result ^= choiceFormats[choiceFormats.length-1].hashCode();
}
return result;
}
/**
* {@return a string identifying this {@code ChoiceFormat}, for debugging}
*/
@Override
public String toString() {
return
"""
ChoiceFormat [pattern: "%s"]
""".formatted(toPattern());
}
/**
* Compares the specified object with this {@code ChoiceFormat} for equality.
* Returns true if the object is also a {@code ChoiceFormat} and the
* two formats would format any value the same.
*
* @implSpec This method performs an equality check with a notion of class
* identity based on {@code getClass()}, rather than {@code instanceof}.
* Therefore, in the equals methods in subclasses, no instance of this class
* should compare as equal to an instance of a subclass.
* @param obj object to be compared for equality
* @return {@code true} if the specified object is equal to this {@code ChoiceFormat}
* @see Object#equals(Object)
*/
@Override
public boolean equals(Object obj) {
if (this == obj) // quick check
return true;
if (obj == null || getClass() != obj.getClass())
return false;
ChoiceFormat other = (ChoiceFormat) obj;
return (Arrays.equals(choiceLimits, other.choiceLimits)
&& Arrays.equals(choiceFormats, other.choiceFormats));
}
/**
* After reading an object from the input stream, do a simple verification
* to maintain class invariants.
* @throws InvalidObjectException if the objects read from the stream is invalid.
*/
@java.io.Serial
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();
if (choiceLimits.length != choiceFormats.length) {
throw new InvalidObjectException(
"limits and format arrays of different length.");
}
}
// ===============privates===========================
/**
* A list of lower bounds for the choices. The formatter will return
* {@code choiceFormats[i]} if the number being formatted is greater than or equal to
* {@code choiceLimits[i]} and less than {@code choiceLimits[i+1]}.
* @serial
*/
private double[] choiceLimits;
/**
* A list of choice strings. The formatter will return
* {@code choiceFormats[i]} if the number being formatted is greater than or equal to
* {@code choiceLimits[i]} and less than {@code choiceLimits[i+1]}.
* @serial
*/
private String[] choiceFormats;
}
* See {@link MessageFormat##pattern_caveats MessageFormat} for caveats regarding
* {@code MessageFormat} patterns within a {@code ChoiceFormat} pattern.
*
*
* The disk "MyDisk" contains no files.
* The disk "MyDisk" contains one file.
* The disk "MyDisk" contains 1,273 files.
*
Synchronization
*
*