organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-15 01:42:37 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 1

ICU-4264 clean up message format docs a bit to clarify use of RBNF, shorten long lines

Browse source 
X-SVN-Rev: 27158
This commit is contained in:
Doug Felt 2010-01-07 01:18:16 +00:00
parent 9054a6919b
commit fb6815fc9d
1 changed files with 61 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
icu4j/main/classes/core/src/com/ibm/icu/text/MessageFormat.java
View file

@ -1,6 +1,6 @@
/*
**********************************************************************
* Copyright (c) 2004-2009, International Business Machines
* Copyright (c) 2004-2010, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
* Author: Alan Liu
@ -109,7 +109,7 @@ import com.ibm.icu.util.ULocale;
* [:ID_START:][:ID_CONTINUE:]*
*
* <i>FormatType: one of </i>
* number date time choice
* number date time choice spellout ordinal duration plural
*
* <i>FormatStyle:</i>
* short
@ -120,6 +120,7 @@ import com.ibm.icu.util.ULocale;
* currency
* percent
* <i>SubformatPattern</i>
* <i>RulesetName</i>
*
* <i>String:</i>
* <i>StringPart<sub>opt</sub></i>
@ -139,6 +140,8 @@ import com.ibm.icu.util.ULocale;
* <i>UnquotedPattern</i>
* </pre></blockquote>
*
* <i>RulesetName:</i>
* <i>UnquotedString</i>
* <p>
* Within a <i>String</i>, <code>"''"</code> represents a single
* quote. A <i>QuotedString</i> can contain arbitrary characters
@ -255,16 +258,19 @@ import com.ibm.icu.util.ULocale;
* <td><code>new ChoiceFormat(subformatPattern)</code>
* <tr>
* <td><code>spellout</code>
* <td><i>Ruleset name (optional)</i>
* <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.SPELLOUT)<br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
* <td><i>RulesetName (optional)</i>
* <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.SPELLOUT)
* <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
* <tr>
* <td><code>ordinal</code>
* <td><i>Ruleset name (optional)</i>
* <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.ORDINAL)<br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
* <td><i>RulesetName (optional)</i>
* <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.ORDINAL)
* <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
* <tr>
* <td><code>duration</code>
* <td><i>Ruleset name (optional)</i>
* <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.DURATION)<br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
* <td><i>RulesetName (optional)</i>
* <td><code>new RuleBasedNumberFormat(getLocale(), RuleBasedNumberFormat.DURATION)
* <br/>&nbsp;&nbsp;&nbsp;&nbsp;.setDefaultRuleset(ruleset);</code>
* <tr>
* <td><code>plural</code>
* <td><i>SubformatPattern</i>
@ -391,9 +397,6 @@ import com.ibm.icu.util.ULocale;
* @author Mark Davis
* @stable ICU 3.0
*/
// TODO: Update JavaDoc class description with regards to named arguments.
// TODO: Update JavaDoc class description with regards to PluralFormat
// integration.
public class MessageFormat extends UFormat implements BaseFormat<Object,StringBuffer,String> {
// Generated by serialver from JDK 1.4.1_01
@ -588,7 +591,6 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
this.pattern = segments[0].toString();
}
/**
* Returns a pattern representing the current state of the message format.
* The string is constructed from internal information and therefore
@ -935,7 +937,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
}
/**
* Get the format argument names. For more details, see {@link #setFormatByArgumentName(String, Format)}.
* Get the format argument names. For more details, see
* {@link #setFormatByArgumentName(String, Format)}.
* @return List of names
* @deprecated This API is ICU internal only.
* @internal
@ -949,7 +952,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
}
/**
* Get the formats according to their argument names. For more details, see {@link #setFormatByArgumentName(String, Format)}.
* Get the formats according to their argument names. For more details, see
* {@link #setFormatByArgumentName(String, Format)}.
* @return format associated with the name, or null if there isn't one.
* @deprecated This API is ICU internal only.
* @internal
@ -1006,7 +1010,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
* <tr>
* <td><code>null</code>
* <td><code>instanceof Date</code>
* <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, getLocale()).format(argument)</code>
* <td><code>DateFormat.getDateTimeInstance(DateFormat.SHORT,
* DateFormat.SHORT, getLocale()).format(argument)</code>
* <tr>
* <td><code>null</code>
* <td><code>instanceof String</code>
@ -1083,7 +1088,9 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
* Creates a MessageFormat with the given pattern and uses it
* to format the given arguments. This is equivalent to
* <blockquote>
* <code>(new {@link #MessageFormat(String) MessageFormat}(pattern)).{@link #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition) format}(arguments, new StringBuffer(), null).toString()</code>
* <code>(new {@link #MessageFormat(String) MessageFormat}(pattern)).{@link
* #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition)
* format}(arguments, new StringBuffer(), null).toString()</code>
* </blockquote>
*
* @throws IllegalArgumentException if the pattern is invalid,
@ -1134,8 +1141,10 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
* provided <code>StringBuffer</code>.
* This is equivalent to either of
* <blockquote>
* <code>{@link #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition) format}((Object[]) arguments, result, pos)</code>
* <code>{@link #format(java.util.Map, java.lang.StringBuffer, java.text.FieldPosition) format}((Map) arguments, result, pos)</code>
* <code>{@link #format(java.lang.Object[], java.lang.StringBuffer,
* java.text.FieldPosition) format}((Object[]) arguments, result, pos)</code>
* <code>{@link #format(java.util.Map, java.lang.StringBuffer,
* java.text.FieldPosition) format}((Map) arguments, result, pos)</code>
* </blockquote>
* A map must be provided if this format uses named arguments, otherwise
* an IllegalArgumentException will be thrown.
@ -1177,7 +1186,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
* The text of the returned <code>AttributedCharacterIterator</code> is
* the same that would be returned by
* <blockquote>
* <code>{@link #format(java.lang.Object[], java.lang.StringBuffer, java.text.FieldPosition) format}(arguments, new StringBuffer(), null).toString()</code>
* <code>{@link #format(java.lang.Object[], java.lang.StringBuffer,
* java.text.FieldPosition) format}(arguments, new StringBuffer(), null).toString()</code>
* </blockquote>
* <p>
* In addition, the <code>AttributedCharacterIterator</code> contains at
@ -1204,7 +1214,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
@SuppressWarnings("unchecked")
public AttributedCharacterIterator formatToCharacterIterator(Object arguments) {
StringBuffer result = new StringBuffer();
ArrayList<AttributedCharacterIterator> iterators = new ArrayList<AttributedCharacterIterator>();
ArrayList<AttributedCharacterIterator> iterators =
new ArrayList<AttributedCharacterIterator>();
if (arguments == null) {
throw new NullPointerException(
@ -1542,7 +1553,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
*/
protected Object readResolve() throws InvalidObjectException {
if (this.getClass() != MessageFormat.Field.class) {
throw new InvalidObjectException("A subclass of MessageFormat.Field must implement readResolve.");
throw new InvalidObjectException(
"A subclass of MessageFormat.Field must implement readResolve.");
}
if (this.getName().equals(ARGUMENT.getName())) {
return ARGUMENT;
@ -1650,7 +1662,7 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
* expected by the format element(s) that use it.
*/
private StringBuffer subformat(Object[] arguments, StringBuffer result,
FieldPosition fp, List<AttributedCharacterIterator> characterIterators) {
FieldPosition fp, List<AttributedCharacterIterator> characterIterators) {
return subformat(arrayToMap(arguments), result, fp, characterIterators);
}
@ -1662,7 +1674,7 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
* expected by the format element(s) that use it.
*/
private StringBuffer subformat(Map<String, Object> arguments, StringBuffer result,
FieldPosition fp, List<AttributedCharacterIterator> characterIterators) {
FieldPosition fp, List<AttributedCharacterIterator> characterIterators) {
// note: this implementation assumes a fast substring & index.
// if this is not true, would be better to append chars one by one.
int lastOffset = 0;
@ -1735,9 +1747,11 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
append(result, subIterator);
if (last != result.length()) {
characterIterators.add(
_createAttributedCharacterIterator(
subIterator, Field.ARGUMENT,
argumentNamesAreNumeric ? (Object)new Integer(argumentName) : (Object)argumentName));
_createAttributedCharacterIterator(
subIterator, Field.ARGUMENT,
argumentNamesAreNumeric ?
(Object)new Integer(argumentName) :
(Object)argumentName));
last = result.length();
}
arg = null;
@ -1745,9 +1759,11 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
if (arg != null && arg.length() > 0) {
result.append(arg);
characterIterators.add(
_createAttributedCharacterIterator(
arg, Field.ARGUMENT,
argumentNamesAreNumeric ? (Object)new Integer(argumentName) : (Object)argumentName));
_createAttributedCharacterIterator(
arg, Field.ARGUMENT,
argumentNamesAreNumeric ?
(Object)new Integer(argumentName) :
(Object)argumentName));
last = result.length();
}
} else {
@ -1900,7 +1916,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
newFormat = NumberFormat.getIntegerInstance(ulocale);
break;
default: // pattern
newFormat = new DecimalFormat(segments[3].toString(), new DecimalFormatSymbols(ulocale));
newFormat = new DecimalFormat(segments[3].toString(),
new DecimalFormatSymbols(ulocale));
break;
}
break;
@ -1958,7 +1975,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
break;
case TYPE_SPELLOUT:
{
RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, RuleBasedNumberFormat.SPELLOUT);
RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale,
RuleBasedNumberFormat.SPELLOUT);
String ruleset = segments[3].toString().trim();
if (ruleset.length() != 0) {
try {
@ -1973,7 +1991,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
break;
case TYPE_ORDINAL:
{
RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, RuleBasedNumberFormat.ORDINAL);
RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale,
RuleBasedNumberFormat.ORDINAL);
String ruleset = segments[3].toString().trim();
if (ruleset.length() != 0) {
try {
@ -1988,7 +2007,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
break;
case TYPE_DURATION:
{
RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale, RuleBasedNumberFormat.DURATION);
RuleBasedNumberFormat rbnf = new RuleBasedNumberFormat(ulocale,
RuleBasedNumberFormat.DURATION);
String ruleset = segments[3].toString().trim();
if (ruleset.length() != 0) {
try {
@ -2048,7 +2068,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
return -1;
}
private static final void copyAndFixQuotes(String source, int start, int end, StringBuffer target) {
private static final void copyAndFixQuotes(String source, int start, int end,
StringBuffer target) {
// added 'gotLB' logic from ICU4C - questionable [alan]
boolean gotLB = false;
for (int i = start; i < end; ++i) {
@ -2101,7 +2122,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
}
}
if (!isValid) {
throw new InvalidObjectException("Could not reconstruct MessageFormat from corrupt stream.");
throw new InvalidObjectException(
"Could not reconstruct MessageFormat from corrupt stream.");
}
if (ulocale == null) {
ulocale = ULocale.forLocale(locale);
@ -2246,7 +2268,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
return as.getIterator();
}
private static AttributedCharacterIterator _createAttributedCharacterIterator(AttributedCharacterIterator[] iterators) {
private static AttributedCharacterIterator _createAttributedCharacterIterator(
AttributedCharacterIterator[] iterators) {
if (iterators == null || iterators.length == 0) {
return _createAttributedCharacterIterator("");
}
@ -2287,7 +2310,8 @@ public class MessageFormat extends UFormat implements BaseFormat<Object,StringBu
return as.getIterator();
}
private static AttributedCharacterIterator _createAttributedCharacterIterator(AttributedCharacterIterator iterator,
private static AttributedCharacterIterator _createAttributedCharacterIterator(
AttributedCharacterIterator iterator,
AttributedCharacterIterator.Attribute key, Object value) {
AttributedString as = new AttributedString(iterator);
as.addAttribute(key, value);