Summary

Update ChoiceFormat to allow "#", "<", and "≤" in the format segment of a ChoiceFormat String pattern.

Problem

A ChoiceFormat sub-pattern has the syntax "limit relation format", for example, "1#foo" has a limit of "1", symbol of "#", and format of "foo".

ChoiceFormat currently does not allow "#" "<" and "≤" in the format segment of a pattern, (an IllegalArgumentException will be thrown). This is an unnecessary limitation on the class, as based on the pattern syntax, only '|' needs to be treated as a special pattern character in the format segment.

Solution

Adjust the implementation so that the relational symbols are only recognized by their syntactical meaning when the implementation is parsing a limit segment, as opposed to the current implementation, which always recognizes the symbols by its syntactical meaning.

This will then allow behavior such as new ChoiceFormat("1#The code is #7281"). Previously, the workaround would have been new ChoiceFormat("1#The code is '#'7281") to achieve the same formatted behavior.

Compatibility wise, any existing code that escaped a special relational symbol still functions exactly as before. Thus, before and after this proposed change, new ChoiceFormat("1#The code is '#'7281") produces the same value when format is invoked.

Specification

Adjust the Format pattern definition,

  * <dt><i>Format:</i>
- * <dd>Any characters except the <i>Relation</i> symbols
+ * <dd>Any characters except the special pattern character '|'

Adjust the quoting disclaimer for using escaping special characters in a Format pattern,

- * <p>If a <i>Relation</i> symbol is to be used within a <i>Format</i> pattern,
- * it must be single quoted. For example,
- * {@code new ChoiceFormat("1# '#'1 ").format(1)} returns {@code " #1 "}.
+ * <p> To use a reserved special pattern character within a <i>Format</i> pattern,
+ * it must be single quoted. For example, {@code new ChoiceFormat("1#'|'foo'|'").format(1)}
+ * returns {@code "|foo|"}.

Not related to the fix, but other spec changes included with the patch

Improve and move the note under Pattern to SubPattern,

  * <dd>SubPattern *("|" SubPattern)
- * <dd><i>Note: Each additional SubPattern must have a Limit greater than the previous SubPattern's Limit</i>
  * </dl>
  *
  * <dl>
  * <dt><i>SubPattern:</i>
  * <dd>Limit Relation Format
+ * <dd><sub>Note: Each additional SubPattern must have an ascending Limit-Relation interval</sub></dd>

Create a Usage Information section (similar to the other j.text.Format classes), that groups all the examples under a header (trivial diff omitted for brevity)