diff --git a/src/java.base/share/classes/java/text/ChoiceFormat.java b/src/java.base/share/classes/java/text/ChoiceFormat.java index c080bc897ab..a75aad0a303 100644 --- a/src/java.base/share/classes/java/text/ChoiceFormat.java +++ b/src/java.base/share/classes/java/text/ChoiceFormat.java @@ -44,8 +44,9 @@ import java.io.ObjectInputStream; import java.util.Arrays; /** - * A {@code ChoiceFormat} allows you to attach a format to a range of numbers. - * It is generally used in a {@code MessageFormat} for handling plurals. + * {@code ChoiceFormat} is a concrete subclass of {@code NumberFormat} that + * allows you to attach a format to a range of numbers. + * It is generally used in a {@link MessageFormat} for handling plurals. * The choice is specified with an ascending list of doubles, where each item * specifies a half-open interval up to the next item: *
@@ -68,8 +69,10 @@ import java.util.Arrays; * {@code ChoiceFormat} doesn't implement any locale specific behavior. * *

- * When creating a {@code ChoiceFormat}, you must specify an array of formats - * and an array of limits. The length of these arrays must be the same. + * 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, *

* *

- * Here is a simple example that shows formatting and parsing: + * 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}; @@ -97,7 +101,8 @@ import java.util.Arrays; * } * } *
- * Here is a more complex example, with a pattern format: + * For more sophisticated patterns, {@code ChoiceFormat} can be used with + * {@link MessageFormat} to produce accurate forms for singular and plural: *
* {@snippet lang=java : * double[] filelimits = {0,1,2}; @@ -114,42 +119,92 @@ import java.util.Arrays; * } * } *
- *

- * Specifying a pattern for ChoiceFormat objects is fairly straightforward. - * For example: + * Would output the following: + *

+ * 
{@code
+ * There are no files on ADisk
+ * There is one file on ADisk
+ * There are 2 files on ADisk
+ * There are 3 files on ADisk
+ * }
+ *
+ * + *

Patterns

+ * A {@code ChoiceFormat} pattern has the following syntax: + *
+ *
+ *
Pattern: + *
SubPattern *("|" SubPattern) + *
Note: Each additional SubPattern must have a Limit greater than the previous SubPattern's Limit + *
+ * + *
+ *
SubPattern: + *
Limit Relation Format + *
+ * + *
+ *
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 Relation symbols + *
+ * + *
+ * + * Note:The relation ≤ is not equivalent to <= + * + *

Below is an example of constructing a ChoiceFormat with a pattern: *

* {@snippet lang=java : * ChoiceFormat fmt = new ChoiceFormat( * "-1#is negative| 0#is zero or fraction | 1#is one |1.0 - * And the output result would be like the following: - *
- * 
{@code
- * Format with -INF : is negative
- * Format with -1.0 : is negative
- * Format with 0 : is zero or fraction
- * Format with 0.9 : is zero or fraction
- * Format with 1.0 : is one
- * Format with 1.5 : is 1+
- * Format with 2 : is two
- * Format with 2.1 : is more than 2.
- * Format with NaN : is negative
- * Format with +INF : is more than 2.
- * }
- *
* *

Synchronization

* @@ -172,12 +227,16 @@ public class ChoiceFormat extends NumberFormat { private static final long serialVersionUID = 1795184449645032964L; /** - * Sets the pattern. - * @param newPattern See the class description. + * Apply the given pattern to this ChoiceFormat object. The syntax + * for the ChoiceFormat pattern can be seen in the {@linkplain ##patterns + * Patterns} section. + * + * @param newPattern a pattern string * @throws NullPointerException if {@code newPattern} * is {@code null} * @throws IllegalArgumentException if {@code newPattern} - * is invalid + * violates the pattern syntax + * @see #ChoiceFormat(String) */ public void applyPattern(String newPattern) { StringBuilder[] segments = new StringBuilder[2]; @@ -260,9 +319,14 @@ public class ChoiceFormat extends NumberFormat { } /** - * Gets the pattern. + * {@return a pattern {@code string} that represents the the limits and formats + * of this ChoiceFormat object} * - * @return the pattern string + * The {@code string} returned is not guaranteed to be the same input + * {@code string} passed to either {@link #applyPattern(String)} or + * {@link #ChoiceFormat(String)}. + * + * @see #applyPattern(String) */ public String toPattern() { StringBuilder result = new StringBuilder(); @@ -312,13 +376,16 @@ public class ChoiceFormat extends NumberFormat { } /** - * Constructs with limits and corresponding formats based on the pattern. + * Constructs a ChoiceFormat with limits and corresponding formats + * based on the pattern. + * The syntax for the ChoiceFormat pattern can be seen in the {@linkplain + * ##patterns Patterns} section. * * @param newPattern the new pattern string * @throws NullPointerException if {@code newPattern} is * {@code null} * @throws IllegalArgumentException if {@code newPattern} - * is invalid + * violates the pattern syntax * @see #applyPattern */ public ChoiceFormat(String newPattern) { @@ -364,8 +431,7 @@ public class ChoiceFormat extends NumberFormat { } /** - * Get the limits passed in the constructor. - * @return the limits. + * {@return the limits of this ChoiceFormat} */ public double[] getLimits() { double[] newLimits = Arrays.copyOf(choiceLimits, choiceLimits.length); @@ -373,8 +439,7 @@ public class ChoiceFormat extends NumberFormat { } /** - * Get the formats passed in the constructor. - * @return the formats. + * {@return the formats of this ChoiceFormat} */ public Object[] getFormats() { Object[] newFormats = Arrays.copyOf(choiceFormats, choiceFormats.length); @@ -390,6 +455,7 @@ public class ChoiceFormat extends NumberFormat { * the range that can be stored by double. This will never be * a practical limitation. */ + @Override public StringBuffer format(long number, StringBuffer toAppendTo, FieldPosition status) { return format((double)number, toAppendTo, status); @@ -403,7 +469,8 @@ public class ChoiceFormat extends NumberFormat { * @throws NullPointerException if {@code toAppendTo} * is {@code null} */ - public StringBuffer format(double number, StringBuffer toAppendTo, + @Override + public StringBuffer format(double number, StringBuffer toAppendTo, FieldPosition status) { // find the number int i; @@ -434,6 +501,7 @@ public class ChoiceFormat extends NumberFormat { * 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; @@ -493,6 +561,7 @@ public class ChoiceFormat extends NumberFormat { /** * Overrides Cloneable */ + @Override public Object clone() { ChoiceFormat other = (ChoiceFormat) super.clone();