Improve documentation about the user's default locale.
Add a bit of text to Locale's class documentation, and include a link from
every method that uses Locale.getDefault(). Also try to consistently say
"user's default locale", as a subliminal hint that this isn't necessarily
the developer's locale, nor en_US.
Bug: 2593000
Change-Id: Ieebe864ed6b9fecbfef5d5415269299739cedd1b
diff --git a/luni/src/main/java/java/io/PrintStream.java b/luni/src/main/java/java/io/PrintStream.java
index 9e84342..ced2a7f 100644
--- a/luni/src/main/java/java/io/PrintStream.java
+++ b/luni/src/main/java/java/io/PrintStream.java
@@ -287,24 +287,21 @@
}
/**
- * Writes a string formatted by an intermediate {@code Formatter} to the
- * target stream using the specified format string and arguments. For the
- * locale, the default value of the current virtual machine instance is
- * used.
+ * Formats {@code args} according to the format string {@code format}, and writes the result
+ * to this stream. This method uses the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
- * @param format
- * the format string used for {@link java.util.Formatter#format}.
+ * @param format the format string (see {@link java.util.Formatter#format})
* @param args
* the list of arguments passed to the formatter. If there are
- * more arguments than required by the {@code format} string,
- * then the additional arguments are ignored.
+ * more arguments than required by {@code format},
+ * additional arguments are ignored.
* @return this stream.
* @throws IllegalFormatException
* if the format string is illegal or incompatible with the
* arguments, if there are not enough arguments or if any other
* error regarding the format string or arguments is detected.
- * @throws NullPointerException
- * if {@code format} is {@code null}.
+ * @throws NullPointerException if {@code format == null}
*/
public PrintStream format(String format, Object... args) {
return format(Locale.getDefault(), format, args);
diff --git a/luni/src/main/java/java/io/PrintWriter.java b/luni/src/main/java/java/io/PrintWriter.java
index 34842a9..9f5f3cd 100644
--- a/luni/src/main/java/java/io/PrintWriter.java
+++ b/luni/src/main/java/java/io/PrintWriter.java
@@ -281,24 +281,22 @@
}
/**
- * Writes a string formatted by an intermediate {@code Formatter} to the
- * target using the specified format string and arguments. For the locale,
- * the default value of the current virtual machine instance is used. If
- * automatic flushing is enabled then the buffer is flushed as well.
+ * Formats {@code args} according to the format string {@code format}, and writes the result
+ * to this stream. This method uses the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ * If automatic flushing is enabled then the buffer is flushed as well.
*
- * @param format
- * the format string used for {@link java.util.Formatter#format}.
+ * @param format the format string (see {@link java.util.Formatter#format})
* @param args
* the list of arguments passed to the formatter. If there are
- * more arguments than required by the {@code format} string,
- * then the additional arguments are ignored.
+ * more arguments than required by {@code format},
+ * additional arguments are ignored.
* @return this writer.
* @throws IllegalFormatException
* if the format string is illegal or incompatible with the
* arguments, if there are not enough arguments or if any other
* error regarding the format string or arguments is detected.
- * @throws NullPointerException
- * if {@code format} is {@code null}.
+ * @throws NullPointerException if {@code format == null}
*/
public PrintWriter format(String format, Object... args) {
return format(Locale.getDefault(), format, args);
diff --git a/luni/src/main/java/java/lang/String.java b/luni/src/main/java/java/lang/String.java
index 495cc63..c7236d5 100644
--- a/luni/src/main/java/java/lang/String.java
+++ b/luni/src/main/java/java/lang/String.java
@@ -1696,8 +1696,9 @@
}
/**
- * Converts this string to lowercase, using the rules of the default locale.
- *
+ * Converts this string to lowercase, using the rules of the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @return a new lowercase string, or {@code this} if it's already all-lowercase.
*/
public String toLowerCase() {
@@ -1732,8 +1733,9 @@
}
/**
- * Converts this this string to uppercase, using the rules of the default locale.
- *
+ * Converts this this string to uppercase, using the rules of the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @return a new uppercase string, or {@code this} if it's already all-uppercase.
*/
public String toUpperCase() {
@@ -2167,24 +2169,20 @@
* Returns a localized formatted string, using the supplied format and arguments,
* using the user's default locale.
*
- * <p>Note that this method can be dangerous: the user's default locale may
- * not be the locale you tested in, and this may have unexpected effects on
- * the output. In particular, floating point numbers may be output with
- * ',' instead of '.' as the decimal separator if that's what the user's
- * locale dictates. If you're formatting a string other than for human
+ * <p>If you're formatting a string other than for human
* consumption, you should use the {@code format(Locale, String, Object...)}
- * overload and supply {@code Locale.US}.
+ * overload and supply {@code Locale.US}. See
+ * "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
- * @param format
- * a format string.
+ * @param format the format string (see {@link java.util.Formatter#format})
* @param args
- * arguments to replace format specifiers (may be none).
+ * the list of arguments passed to the formatter. If there are
+ * more arguments than required by {@code format},
+ * additional arguments are ignored.
* @return the formatted string.
- * @throws NullPointerException
- * if {@code format} is {@code null}.
+ * @throws NullPointerException if {@code format == null}
* @throws java.util.IllegalFormatException
* if the format is invalid.
- * @see java.util.Formatter
* @since 1.5
*/
public static String format(String format, Object... args) {
@@ -2194,35 +2192,26 @@
/**
* Returns a formatted string, using the supplied format and arguments,
* localized to the given locale.
- * <p>
- * Note that this is a convenience method. Using it involves creating an
- * internal {@link java.util.Formatter} instance on-the-fly, which is
- * somewhat costly in terms of memory and time. This is probably acceptable
- * if you use the method only rarely, but if you rely on it for formatting a
- * large number of strings, consider creating and reusing your own
- * {@link java.util.Formatter} instance instead.
- *
- * @param loc
+ *
+ * @param locale
* the locale to apply; {@code null} value means no localization.
- * @param format
- * a format string.
+ * @param format the format string (see {@link java.util.Formatter#format})
* @param args
- * arguments to replace format specifiers (may be none).
+ * the list of arguments passed to the formatter. If there are
+ * more arguments than required by {@code format},
+ * additional arguments are ignored.
* @return the formatted string.
- * @throws NullPointerException
- * if {@code format} is {@code null}.
+ * @throws NullPointerException if {@code format == null}
* @throws java.util.IllegalFormatException
* if the format is invalid.
- * @see java.util.Formatter
* @since 1.5
*/
- public static String format(Locale loc, String format, Object... args) {
+ public static String format(Locale locale, String format, Object... args) {
if (format == null) {
throw new NullPointerException("null format argument");
}
- int bufferSize = format.length()
- + (args == null ? 0 : args.length * 10);
- Formatter f = new Formatter(new StringBuilder(bufferSize), loc);
+ int bufferSize = format.length() + (args == null ? 0 : args.length * 10);
+ Formatter f = new Formatter(new StringBuilder(bufferSize), locale);
return f.format(format, args).toString();
}
diff --git a/luni/src/main/java/java/util/Currency.java b/luni/src/main/java/java/util/Currency.java
index 6b6e902..a3ab15c 100644
--- a/luni/src/main/java/java/util/Currency.java
+++ b/luni/src/main/java/java/util/Currency.java
@@ -133,46 +133,32 @@
}
/**
- * Returns this {@code Currency}'s ISO 4217 currency code.
- *
- * @return this {@code Currency}'s ISO 4217 currency code.
+ * Returns this currency's ISO 4217 currency code.
*/
public String getCurrencyCode() {
return currencyCode;
}
/**
- * Returns the symbol for this currency in the default locale. For instance,
- * if the default locale is the US, the symbol of the US dollar is "$". For
- * other locales it may be "US$". If no symbol can be determined, the ISO
- * 4217 currency code of the US dollar is returned.
- *
- * @return the symbol for this {@code Currency} in the default {@code Locale}.
+ * Returns the localized currency symbol for this currency in the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*/
public String getSymbol() {
return getSymbol(Locale.getDefault());
}
/**
- * Returns the symbol for this currency in the given {@code Locale}.
+ * Returns the localized currency symbol for this currency in {@code locale}.
* That is, given "USD" and Locale.US, you'd get "$", but given "USD" and a non-US locale,
* you'd get "US$".
- * <p>
- * If the locale only specifies a language rather than a language and a countries (e.g.
- * {@code Locale.JAPANESE, new Locale("en","")}), the the ISO
- * 4217 currency code is returned.
- * <p>
- * If there is no currency symbol specific to this locale does not exist, the
- * ISO 4217 currency code is returned.
- * <p>
*
- * @param locale
- * the locale for which the currency symbol should be returned.
- * @return the representation of this {@code Currency}'s symbol in the specified
- * locale.
+ * <p>If the locale only specifies a language rather than a language and a country (such as
+ * {@code Locale.JAPANESE} or {new Locale("en", "")} rather than {@code Locale.JAPAN} or
+ * {new Locale("en", "US")}), the ISO 4217 currency code is returned.
+ *
+ * <p>If there is no locale-specific currency symbol, the ISO 4217 currency code is returned.
*/
public String getSymbol(Locale locale) {
- // BEGIN android-changed
if (locale.getCountry().length() == 0) {
return currencyCode;
}
@@ -186,7 +172,6 @@
// Try ICU, and fall back to the currency code if ICU has nothing.
String symbol = Resources.getCurrencySymbolNative(locale.toString(), currencyCode);
return symbol != null ? symbol : currencyCode;
- // END android-changed
}
/**
diff --git a/luni/src/main/java/java/util/Formatter.java b/luni/src/main/java/java/util/Formatter.java
index dec1416..91209d4 100644
--- a/luni/src/main/java/java/util/Formatter.java
+++ b/luni/src/main/java/java/util/Formatter.java
@@ -553,11 +553,11 @@
/**
* Constructs a {@code Formatter}.
*
- * The output is written to a {@code StringBuilder} which can be acquired by invoking
- * {@link #out()} and whose content can be obtained by calling
- * {@code toString()}.
+ * <p>The output is written to a {@code StringBuilder} which can be acquired by invoking
+ * {@link #out()} and whose content can be obtained by calling {@code toString}.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*/
public Formatter() {
this(new StringBuilder(), Locale.getDefault());
@@ -567,8 +567,9 @@
* Constructs a {@code Formatter} whose output will be written to the
* specified {@code Appendable}.
*
- * The locale for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param a
* the output destination of the {@code Formatter}. If {@code a} is {@code null},
* then a {@code StringBuilder} will be used.
@@ -580,9 +581,8 @@
/**
* Constructs a {@code Formatter} with the specified {@code Locale}.
*
- * The output is written to a {@code StringBuilder} which can be acquired by invoking
- * {@link #out()} and whose content can be obtained by calling
- * {@code toString()}.
+ * <p>The output is written to a {@code StringBuilder} which can be acquired by invoking
+ * {@link #out()} and whose content can be obtained by calling {@code toString}.
*
* @param l
* the {@code Locale} of the {@code Formatter}. If {@code l} is {@code null},
@@ -616,10 +616,11 @@
/**
* Constructs a {@code Formatter} whose output is written to the specified file.
*
- * The charset of the {@code Formatter} is the default charset.
+ * <p>The charset of the {@code Formatter} is the default charset.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param fileName
* the filename of the file that is used as the output
* destination for the {@code Formatter}. The file will be truncated to
@@ -641,8 +642,9 @@
/**
* Constructs a {@code Formatter} whose output is written to the specified file.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param fileName
* the filename of the file that is used as the output
* destination for the {@code Formatter}. The file will be truncated to
@@ -700,8 +702,9 @@
*
* The charset of the {@code Formatter} is the default charset.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param file
* the {@code File} that is used as the output destination for the
* {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File}
@@ -723,8 +726,9 @@
* Constructs a {@code Formatter} with the given charset,
* and whose output is written to the specified {@code File}.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param file
* the {@code File} that is used as the output destination for the
* {@code Formatter}. The {@code File} will be truncated to zero size if the {@code File}
@@ -791,10 +795,11 @@
/**
* Constructs a {@code Formatter} whose output is written to the specified {@code OutputStream}.
*
- * The charset of the {@code Formatter} is the default charset.
+ * <p>The charset of the {@code Formatter} is the default charset.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param os
* the stream to be used as the destination of the {@code Formatter}.
*/
@@ -807,8 +812,9 @@
* Constructs a {@code Formatter} with the given charset,
* and whose output is written to the specified {@code OutputStream}.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param os
* the stream to be used as the destination of the {@code Formatter}.
* @param csn
@@ -844,10 +850,11 @@
/**
* Constructs a {@code Formatter} whose output is written to the specified {@code PrintStream}.
*
- * The charset of the {@code Formatter} is the default charset.
+ * <p>The charset of the {@code Formatter} is the default charset.
*
- * The {@code Locale} for the {@code Formatter} is the default {@code Locale}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param ps
* the {@code PrintStream} used as destination of the {@code Formatter}. If
* {@code ps} is {@code null}, then a {@code NullPointerException} will
diff --git a/luni/src/main/java/java/util/Locale.java b/luni/src/main/java/java/util/Locale.java
index 75250b4..9195abc 100644
--- a/luni/src/main/java/java/util/Locale.java
+++ b/luni/src/main/java/java/util/Locale.java
@@ -17,23 +17,16 @@
package java.util;
-// BEGIN android-changed
-// import java.io.File;
+import com.ibm.icu4jni.util.Resources;
import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.ObjectStreamField;
import java.io.Serializable;
import java.security.AccessController;
-// import java.util.zip.ZipEntry;
-// import java.util.zip.ZipFile;
-
import org.apache.harmony.luni.util.PriviAction;
import org.apache.harmony.luni.util.Util;
-import com.ibm.icu4jni.util.Resources;
-// END android-changed
-
/**
* {@code Locale} represents a language/country/variant combination. Locales are used to
* alter the presentation of information such as numbers or dates to suit the conventions
@@ -58,9 +51,24 @@
* spoken in Spain), for example. The opposite may well be true for a device sold in Europe.
* (This limitation even affects those locales pre-defined as constants in this class.)
*
- * <p>You can use {@code getDefault} to get an appropriate locale for the device you're
- * running on, or {@code getAvailableLocales} to get a list of all the locales available
- * on the device you're running on.
+ * <p>You can use {@code getDefault} to get an appropriate locale for the <i>user</i> of
+ * the device you're running on, or {@code getAvailableLocales} to get a list of all the locales
+ * available on the device you're running on.
+ *
+ * <a name="default_locale"><h3>Be wary of the default locale</h3></a>
+ * <p>Note that there are many convenience methods that automatically use the default locale, but
+ * these may not be as convenient as you imagine. The default locale is appropriate for anything
+ * that involves presenting data to the user. You should use the user's date/time formats, number
+ * formats, rules for conversion to lowercase, and so on. A common mistake is to implicitly use the
+ * default locale when producing output meant to be machine-readable. This tends to work on the
+ * developer's test devices but fail when run on a device whose user is in a less conventional
+ * locale. For example, if you're formatting floating-point numbers some locales will use
+ * {@code ','} as the decimal point. That's correct for human-readable output, but likely to cause
+ * problems if presented to another computer ({@code Double.parseDouble} can't parse such a number,
+ * for example). The best choice for computer-readable output is usually {@code Locale.US}: this
+ * locale is guaranteed to be available on all devices, and the combination of no surprising
+ * behavior and frequent use (especially for computer-computer communication) means that it tends
+ * to be the most efficient choice too.
*
* @see ResourceBundle
*/
diff --git a/luni/src/main/java/java/util/TimeZone.java b/luni/src/main/java/java/util/TimeZone.java
index 2b35e61..dd320b8 100644
--- a/luni/src/main/java/java/util/TimeZone.java
+++ b/luni/src/main/java/java/util/TimeZone.java
@@ -214,7 +214,8 @@
* Gets the LONG name for this {@code TimeZone} for the default {@code Locale} in standard
* time. If the name is not available, the result is in the format
* {@code GMT[+-]hh:mm}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @return the {@code TimeZone} name.
*/
public final String getDisplayName() {
@@ -238,7 +239,8 @@
* Gets the specified style of name ({@code LONG} or {@code SHORT}) for this {@code TimeZone} for
* the default {@code Locale} in either standard or daylight time as specified. If
* the name is not available, the result is in the format {@code GMT[+-]hh:mm}.
- *
+ * <p>The {@code Locale} used is the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @param daylightTime
* {@code true} for daylight time, {@code false} for standard
* time.
diff --git a/text/src/main/java/java/text/BreakIterator.java b/text/src/main/java/java/text/BreakIterator.java
index 901f5ab..f14f728 100644
--- a/text/src/main/java/java/text/BreakIterator.java
+++ b/text/src/main/java/java/text/BreakIterator.java
@@ -258,8 +258,8 @@
/**
* Returns a new instance of {@code BreakIterator} to iterate over
- * characters using the default locale.
- *
+ * characters using the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getCharacterInstance() {
@@ -280,8 +280,8 @@
/**
* Returns a new instance of {{@code BreakIterator} to iterate over
- * line breaks using the default locale.
- *
+ * line breaks using the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getLineInstance() {
@@ -304,7 +304,7 @@
/**
* Returns a new instance of {@code BreakIterator} to iterate over
* sentence-breaks using the default locale.
- *
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getSentenceInstance() {
@@ -327,7 +327,7 @@
/**
* Returns a new instance of {@code BreakIterator} to iterate over
* word-breaks using the default locale.
- *
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @return a new instance of {@code BreakIterator} using the default locale.
*/
public static BreakIterator getWordInstance() {
diff --git a/text/src/main/java/java/text/Collator.java b/text/src/main/java/java/text/Collator.java
index fca464d..902eecc 100644
--- a/text/src/main/java/java/text/Collator.java
+++ b/text/src/main/java/java/text/Collator.java
@@ -279,22 +279,16 @@
}
/**
- * Returns a {@code Collator} instance which is appropriate for the default
+ * Returns a {@code Collator} instance which is appropriate for the user's default
* {@code Locale}.
- *
- * @return the collator for the default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*/
public static Collator getInstance() {
return getInstance(Locale.getDefault());
}
/**
- * Returns a {@code Collator} instance which is appropriate for the
- * specified {@code Locale}.
- *
- * @param locale
- * the locale.
- * @return the collator for {@code locale}.
+ * Returns a {@code Collator} instance which is appropriate for {@code locale}.
*/
public static Collator getInstance(Locale locale) {
// BEGIN android-changed: removed non-functional cache.
@@ -312,14 +306,6 @@
return strength_ICU_Java(this.icuColl.getStrength());
}
- /**
- * Returns an integer hash code for this collator.
- *
- * @return this collator's hash code.
- *
- * @see #equals(Object)
- * @see #equals(String, String)
- */
@Override
public abstract int hashCode();
diff --git a/text/src/main/java/java/text/DateFormat.java b/text/src/main/java/java/text/DateFormat.java
index 055cbc3..0beaac1 100644
--- a/text/src/main/java/java/text/DateFormat.java
+++ b/text/src/main/java/java/text/DateFormat.java
@@ -431,8 +431,8 @@
/**
* Returns a {@code DateFormat} instance for formatting and parsing dates in
- * the specified style for the default locale.
- *
+ * the specified style for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @param style
* one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @return the {@code DateFormat} instance for {@code style} and the default
@@ -480,8 +480,8 @@
/**
* Returns a {@code DateFormat} instance for formatting and parsing of both
- * dates and time values in the manner appropriate for the default locale.
- *
+ * dates and time values in the manner appropriate for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @param dateStyle
* one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @param timeStyle
@@ -492,8 +492,7 @@
* if {@code dateStyle} or {@code timeStyle} is not one of
* SHORT, MEDIUM, LONG, FULL, or DEFAULT.
*/
- public final static DateFormat getDateTimeInstance(int dateStyle,
- int timeStyle) {
+ public final static DateFormat getDateTimeInstance(int dateStyle, int timeStyle) {
checkTimeStyle(timeStyle);
checkDateStyle(dateStyle);
return getDateTimeInstance(dateStyle, timeStyle, Locale.getDefault());
@@ -558,8 +557,8 @@
/**
* Returns a {@code DateFormat} instance for formatting and parsing time
- * values in the specified style for the default locale.
- *
+ * values in the specified style for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @param style
* one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
* @return the {@code DateFormat} instance for {@code style} and the default
diff --git a/text/src/main/java/java/text/DateFormatSymbols.java b/text/src/main/java/java/text/DateFormatSymbols.java
index f702716..73e89e0 100644
--- a/text/src/main/java/java/text/DateFormatSymbols.java
+++ b/text/src/main/java/java/text/DateFormatSymbols.java
@@ -102,7 +102,8 @@
/**
* Constructs a new {@code DateFormatSymbols} instance containing the
- * symbols for the default locale.
+ * symbols for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*/
public DateFormatSymbols() {
this(Locale.getDefault());
@@ -130,8 +131,9 @@
}
/**
- * Returns a new {@code DateFormatSymbols} instance for the default locale.
- *
+ * Returns a new {@code DateFormatSymbols} instance for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @return an instance of {@code DateFormatSymbols}
* @since 1.6
* @hide
diff --git a/text/src/main/java/java/text/DecimalFormat.java b/text/src/main/java/java/text/DecimalFormat.java
index e33d407..2776575 100644
--- a/text/src/main/java/java/text/DecimalFormat.java
+++ b/text/src/main/java/java/text/DecimalFormat.java
@@ -554,7 +554,8 @@
/**
* Constructs a new {@code DecimalFormat} for formatting and parsing numbers
- * for the default locale.
+ * for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*/
public DecimalFormat() {
// BEGIN android-changed: reduce duplication.
@@ -567,8 +568,8 @@
/**
* Constructs a new {@code DecimalFormat} using the specified non-localized
- * pattern and the {@code DecimalFormatSymbols} for the default Locale.
- *
+ * pattern and the {@code DecimalFormatSymbols} for the user's default Locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
* @param pattern
* the non-localized pattern.
* @throws IllegalArgumentException
diff --git a/text/src/main/java/java/text/DecimalFormatSymbols.java b/text/src/main/java/java/text/DecimalFormatSymbols.java
index 0ee705c..7188745 100644
--- a/text/src/main/java/java/text/DecimalFormatSymbols.java
+++ b/text/src/main/java/java/text/DecimalFormatSymbols.java
@@ -65,7 +65,9 @@
/**
* Constructs a new {@code DecimalFormatSymbols} containing the symbols for
- * the default locale. Best practice is to create a {@code DecimalFormat}
+ * the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ * Best practice is to create a {@code DecimalFormat}
* and then to get the {@code DecimalFormatSymbols} from that object by
* calling {@link DecimalFormat#getDecimalFormatSymbols()}.
*/
@@ -75,7 +77,9 @@
/**
* Constructs a new DecimalFormatSymbols containing the symbols for the
- * specified Locale. Best practice is to create a {@code DecimalFormat}
+ * specified Locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ * Best practice is to create a {@code DecimalFormat}
* and then to get the {@code DecimalFormatSymbols} from that object by
* calling {@link DecimalFormat#getDecimalFormatSymbols()}.
*
@@ -103,8 +107,9 @@
}
/**
- * Returns a new {@code DecimalFormatSymbols} instance for the default locale.
- *
+ * Returns a new {@code DecimalFormatSymbols} instance for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @return an instance of {@code DecimalFormatSymbols}
* @since 1.6
* @hide
diff --git a/text/src/main/java/java/text/MessageFormat.java b/text/src/main/java/java/text/MessageFormat.java
index 4dc684d..1f3d24f 100644
--- a/text/src/main/java/java/text/MessageFormat.java
+++ b/text/src/main/java/java/text/MessageFormat.java
@@ -42,8 +42,8 @@
* {@code Format} classes in that you create a {@code MessageFormat}
* object with one of its constructors (not with a {@code getInstance}
* style factory method). The factory methods aren't necessary because
- * {@code MessageFormat} itself doesn't implement locale specific
- * behavior. Any locale specific behavior is defined by the pattern that you
+ * {@code MessageFormat} itself doesn't implement locale-specific
+ * behavior. Any locale-specific behavior is defined by the pattern that you
* provide as well as the subformats used for inserted arguments.
*
* <h4><a name="patterns">Patterns and their interpretation</a></h4>
@@ -338,7 +338,7 @@
private static final long serialVersionUID = 6479157306784022952L;
- private Locale locale = Locale.getDefault();
+ private Locale locale;
transient private String[] strings;
@@ -351,8 +351,7 @@
transient private int maxArgumentIndex;
/**
- * Constructs a new {@code MessageFormat} using the specified pattern and
- * the specified locale for formats.
+ * Constructs a new {@code MessageFormat} using the specified pattern and {@code locale}.
*
* @param template
* the pattern.
@@ -368,7 +367,8 @@
/**
* Constructs a new {@code MessageFormat} using the specified pattern and
- * the default locale for formats.
+ * the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
* @param template
* the pattern.
@@ -376,7 +376,7 @@
* if the pattern cannot be parsed.
*/
public MessageFormat(String template) {
- applyPattern(template);
+ this(template, Locale.getDefault());
}
/**
diff --git a/text/src/main/java/java/text/NumberFormat.java b/text/src/main/java/java/text/NumberFormat.java
index 2d0c6c5..52788bd 100644
--- a/text/src/main/java/java/text/NumberFormat.java
+++ b/text/src/main/java/java/text/NumberFormat.java
@@ -336,7 +336,8 @@
/**
* Returns a {@code NumberFormat} for formatting and parsing currency values
- * for the default locale.
+ * for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
* @return a {@code NumberFormat} for handling currency values.
*/
@@ -361,7 +362,8 @@
/**
* Returns a {@code NumberFormat} for formatting and parsing integers for the
- * default locale.
+ * user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
* @return a {@code NumberFormat} for handling integers.
*/
@@ -458,7 +460,8 @@
/**
* Returns a {@code NumberFormat} for formatting and parsing numbers for the
- * default locale.
+ * user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
* @return a {@code NumberFormat} for handling {@code Number} objects.
*/
@@ -483,7 +486,8 @@
/**
* Returns a {@code NumberFormat} for formatting and parsing percentage
- * values for the default locale.
+ * values for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
* @return a {@code NumberFormat} for handling percentage values.
*/
diff --git a/text/src/main/java/java/text/SimpleDateFormat.java b/text/src/main/java/java/text/SimpleDateFormat.java
index d5c06fe..6057b23 100644
--- a/text/src/main/java/java/text/SimpleDateFormat.java
+++ b/text/src/main/java/java/text/SimpleDateFormat.java
@@ -312,9 +312,7 @@
private static final long serialVersionUID = 4774881970558875024L;
- // BEGIN android-changed
- static final String patternChars = "GyMdkHmsSEDFwWahKzZ"; //$NON-NLS-1$
- // END android-changed
+ static final String patternChars = "GyMdkHmsSEDFwWahKzZ";
private String pattern;
@@ -324,28 +322,22 @@
private Date defaultCenturyStart;
- // BEGIN android-removed
- // private transient String tzId;
- //
- // private transient com.ibm.icu.text.SimpleDateFormat icuFormat;
- // END android-removed
-
/**
* Constructs a new {@code SimpleDateFormat} for formatting and parsing
- * dates and times in the {@code SHORT} style for the default locale.
+ * dates and times in the {@code SHORT} style for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*/
public SimpleDateFormat() {
this(Locale.getDefault());
- // BEGIN android-changed
- pattern = defaultPattern();
- // END android-changed
- formatData = new DateFormatSymbols(Locale.getDefault());
+ this.pattern = defaultPattern();
+ this.formatData = new DateFormatSymbols(Locale.getDefault());
}
/**
* Constructs a new {@code SimpleDateFormat} using the specified
* non-localized pattern and the {@code DateFormatSymbols} and {@code
- * Calendar} for the default locale.
+ * Calendar} for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
*
* @param pattern
* the pattern.
@@ -441,8 +433,9 @@
/**
* Constructs a new {@code SimpleDateFormat} using the specified
* non-localized pattern and {@code DateFormatSymbols} and the {@code
- * Calendar} for the default locale.
- *
+ * Calendar} for the user's default locale.
+ * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>".
+ *
* @param template
* the pattern.
* @param value
@@ -455,27 +448,10 @@
public SimpleDateFormat(String template, DateFormatSymbols value) {
this(Locale.getDefault());
validatePattern(template);
- // BEGIN android-removed
- // icuFormat = new com.ibm.icu.text.SimpleDateFormat(template, Locale.getDefault());
- // icuFormat.setTimeZone(com.ibm.icu.util.TimeZone.getTimeZone(tzId));
- // END android-removed
pattern = template;
formatData = (DateFormatSymbols) value.clone();
}
- // BEGIN android-removed
- // private void copySymbols(DateFormatSymbols value, com.ibm.icu.text.DateFormatSymbols icuSymbols) {
- // icuSymbols.setAmPmStrings(value.getAmPmStrings());
- // icuSymbols.setEras(value.getEras());
- // icuSymbols.setLocalPatternChars(value.getLocalPatternChars());
- // icuSymbols.setMonths(value.getMonths());
- // icuSymbols.setShortMonths(value.getShortMonths());
- // icuSymbols.setShortWeekdays(value.getShortWeekdays());
- // icuSymbols.setWeekdays(value.getWeekdays());
- // icuSymbols.setZoneStrings(value.getZoneStrings());
- // }
- // END android-removed
-
/**
* Constructs a new {@code SimpleDateFormat} using the specified
* non-localized pattern and the {@code DateFormatSymbols} and {@code
@@ -503,11 +479,6 @@
// END android-changed
}
- // BEGIN android-removed
- // SimpleDateFormat(Locale locale, com.ibm.icu.text.SimpleDateFormat icuFormat){
- // }
- // END android-removed
-
private SimpleDateFormat(Locale locale) {
numberFormat = NumberFormat.getInstance(locale);
numberFormat.setParseIntegerOnly(true);
@@ -602,18 +573,13 @@
SimpleDateFormat clone = (SimpleDateFormat) super.clone();
clone.formatData = (DateFormatSymbols) formatData.clone();
clone.defaultCenturyStart = new Date(defaultCenturyStart.getTime());
- // BEGIN android-removed
- // clone.tzId = tzId;
- // END android-removed
return clone;
}
- // BEGIN android-added
private static String defaultPattern() {
LocaleData localeData = com.ibm.icu4jni.util.Resources.getLocaleData(Locale.getDefault());
return localeData.getDateFormat(SHORT) + " " + localeData.getTimeFormat(SHORT);
}
- // END android-added
/**
* Compares the specified object with this simple date format and indicates