Add Java 6's getAvailableLocales/getInstance to DateFormatSymbols and DecimalFormatSymbols.

This patch also improves the documentation of all getAvailableLocales methods
to clarify exactly what "available" means. Note that at the moment, many of
our implementations just return Locale.getAvailableLocales. It turns out that
ICU does the same in most cases, but I'll come back in a separate patch and
add code so we just pass these down to ICU, and wash our hands of the matter.

I've rewritten DateFormatSymbols.equals, which was very wrong. The time zone
names comparison had an invalid optimization, and its slow-path loop was wrong
too: it only ever tested values against themselves, which isn't likely to have
been the author's intention.

I've added toString overrides to DateFormatSymbols and DecimalFormatSymbols,
because I need them every time I work on these classes.

I've made the constants in DecimalFormatSymbols static final, and given them
idiomatic names. (I still think we might benefit from breaking these into
separate fields, as in the serialized form, but that's a separate issue.)

Finally, and unrelatedly, I've added a comment to BreakIteratorProvider that
I missed in my last change to that file.

Change-Id: I5d6cb30f9afdb502d38353d8a624dc2f0fef41ac

7 files changed, 158 insertions, 94 deletions

diff --git a/text/src/main/java/java/text/BreakIterator.java b/text/src/main/java/java/text/BreakIterator.java
index b93f882..0144d1e 100644
--- a/text/src/main/java/java/text/BreakIterator.java
+++ b/text/src/main/java/java/text/BreakIterator.java
@@ -252,9 +252,8 @@ public abstract class BreakIterator implements Cloneable {
     }
 
     /**
-     * Returns all supported locales in an array.
-     * 
-     * @return all supported locales.
+     * Returns an array of locales for which custom {@code BreakIterator} instances
+     * are available.
      */
     public static Locale[] getAvailableLocales() {
         return NativeBreakIterator.getAvailableLocales();
diff --git a/text/src/main/java/java/text/Collator.java b/text/src/main/java/java/text/Collator.java
index f324231..1064459 100644
--- a/text/src/main/java/java/text/Collator.java
+++ b/text/src/main/java/java/text/Collator.java
@@ -260,10 +260,8 @@ public abstract class Collator implements Comparator<Object>, Cloneable {
     }
 
     /**
-     * Gets the list of installed {@link java.util.Locale} objects which support
-     * {@code Collator}.
-     * 
-     * @return an array of {@code Locale}.
+     * Returns an array of locales for which custom {@code Collator} instances
+     * are available.
      */
     public static Locale[] getAvailableLocales() {
         return com.ibm.icu4jni.text.Collator.getAvailableLocales();
diff --git a/text/src/main/java/java/text/DateFormat.java b/text/src/main/java/java/text/DateFormat.java
index 2a329e1..57c9852 100644
--- a/text/src/main/java/java/text/DateFormat.java
+++ b/text/src/main/java/java/text/DateFormat.java
@@ -407,9 +407,8 @@ public abstract class DateFormat extends Format {
             FieldPosition field);
 
     /**
-     * Gets the list of installed locales which support {@code DateFormat}.
-     * 
-     * @return an array of locales.
+     * Returns an array of locales for which custom {@code DateFormat} instances
+     * are available.
      */
     public static Locale[] getAvailableLocales() {
         return Locale.getAvailableLocales();
diff --git a/text/src/main/java/java/text/DateFormatSymbols.java b/text/src/main/java/java/text/DateFormatSymbols.java
index ac23ad2..fe63829 100644
--- a/text/src/main/java/java/text/DateFormatSymbols.java
+++ b/text/src/main/java/java/text/DateFormatSymbols.java
@@ -135,6 +135,42 @@ public class DateFormatSymbols implements Serializable, Cloneable {
         // END android-changed
     }
 
+    /**
+     * Returns a new {@code DateFormatSymbols} instance for the default locale.
+     *
+     * @return an instance of {@code DateFormatSymbols}
+     * @since 1.6
+     * @hide
+     */
+    public static final DateFormatSymbols getInstance() {
+        return getInstance(Locale.getDefault());
+    }
+
+    /**
+     * Returns a new {@code DateFormatSymbols} for the given locale.
+     *
+     * @param locale the locale
+     * @return an instance of {@code DateFormatSymbols}
+     * @exception NullPointerException if {@code locale == null}
+     * @since 1.6
+     * @hide
+     */
+    public static final DateFormatSymbols getInstance(Locale locale) {
+        if (locale == null) {
+            throw new NullPointerException();
+        }
+        return new DateFormatSymbols(locale);
+    }
+
+    /**
+     * Returns an array of locales for which custom {@code DateFormatSymbols} instances
+     * are available.
+     * @since 1.6
+     * @hide
+     */
+    public static Locale[] getAvailableLocales() {
+        return Locale.getAvailableLocales();
+    }
 
     private void writeObject(ObjectOutputStream oos) throws IOException {
         // BEGIN android-changed
@@ -188,64 +224,41 @@ public class DateFormatSymbols implements Serializable, Cloneable {
         if (!(object instanceof DateFormatSymbols)) {
             return false;
         }
+        DateFormatSymbols rhs = (DateFormatSymbols) object;
+        return localPatternChars.equals(rhs.localPatternChars) &&
+                Arrays.equals(ampms, rhs.ampms) &&
+                Arrays.equals(eras, rhs.eras) &&
+                Arrays.equals(months, rhs.months) &&
+                Arrays.equals(shortMonths, rhs.shortMonths) &&
+                Arrays.equals(shortWeekdays, rhs.shortWeekdays) &&
+                Arrays.equals(weekdays, rhs.weekdays) &&
+                timeZoneStringsEqual(this, rhs);
+    }
 
-        // BEGIN android-removed
-        // if (zoneStrings == null) {
-        //     zoneStrings = icuSymbols.getZoneStrings();
-        // }
-        // END android-removed
-        DateFormatSymbols obj = (DateFormatSymbols) object;
-        // BEGIN android-removed
-        // if (obj.zoneStrings == null) {
-        //     obj.zoneStrings = obj.icuSymbols.getZoneStrings();
-        // }
-        // END android-removed
-        if (!localPatternChars.equals(obj.localPatternChars)) {
-            return false;
-        }
-        if (!Arrays.equals(ampms, obj.ampms)) {
-            return false;
-        }
-        if (!Arrays.equals(eras, obj.eras)) {
-            return false;
-        }
-        if (!Arrays.equals(months, obj.months)) {
-            return false;
-        }
-        if (!Arrays.equals(shortMonths, obj.shortMonths)) {
-            return false;
-        }
-        if (!Arrays.equals(shortWeekdays, obj.shortWeekdays)) {
-            return false;
-        }
-        if (!Arrays.equals(weekdays, obj.weekdays)) {
-            return false;
-        }
-        // BEGIN android-changed
+    private static boolean timeZoneStringsEqual(DateFormatSymbols lhs, DateFormatSymbols rhs) {
         // Quick check that may keep us from having to load the zone strings.
-        if (zoneStrings == null && obj.zoneStrings == null
-                    && !locale.equals(obj.locale)) {
-            return false;
-        }
-        // Make sure zone strings are loaded.
-        internalZoneStrings();
-        obj.internalZoneStrings();
-        // END android-changed
-        if (zoneStrings.length != obj.zoneStrings.length) {
-            return false;
-        }
-        for (String[] element : zoneStrings) {
-            if (element.length != element.length) {
-                return false;
-            }
-            for (int j = 0; j < element.length; j++) {
-                if (element[j] != element[j]
-                        && !(element[j].equals(element[j]))) {
-                    return false;
-                }
-            }
+        // Note that different locales may have the same strings, so the opposite check isn't valid.
+        if (lhs.zoneStrings == null && rhs.zoneStrings == null && lhs.locale.equals(rhs.locale)) {
+            return true;
         }
-        return true;
+        // Make sure zone strings are loaded, then check.
+        return Arrays.deepEquals(lhs.internalZoneStrings(), rhs.internalZoneStrings());
+    }
+
+    @Override
+    public String toString() {
+        // 'locale' isn't part of the externally-visible state.
+        // 'zoneStrings' is so large, we just print a representative value.
+        return getClass() + "[amPmStrings=" + Arrays.toString(ampms) +
+                ",customZoneStrings=" + customZoneStrings +
+                ",eras=" + Arrays.toString(eras) +
+                ",localPatternChars=" + new String(localPatternChars) +
+                ",months=" + Arrays.toString(months) +
+                ",shortMonths=" + Arrays.toString(shortMonths) +
+                ",shortWeekdays=" + Arrays.toString(shortWeekdays) +
+                ",weekdays=" + Arrays.toString(weekdays) +
+                ",zoneStrings=[" + Arrays.toString(internalZoneStrings()[0]) + "...]" +
+                "]";
     }
 
     /**
diff --git a/text/src/main/java/java/text/DecimalFormatSymbols.java b/text/src/main/java/java/text/DecimalFormatSymbols.java
index 28e9603..05ffda7 100644
--- a/text/src/main/java/java/text/DecimalFormatSymbols.java
+++ b/text/src/main/java/java/text/DecimalFormatSymbols.java
@@ -43,11 +43,19 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
 
     private static final long serialVersionUID = 5772796243397350300L;
 
-    private final int ZeroDigit = 0, Digit = 1, DecimalSeparator = 2,
-            GroupingSeparator = 3, PatternSeparator = 4, Percent = 5,
-            PerMill = 6, Exponent = 7, MonetaryDecimalSeparator = 8,
-            MinusSign = 9;
-
+    // Indexes into the patternChars array.
+    private static final int ZERO_DIGIT = 0;
+    private static final int DIGIT = 1;
+    private static final int DECIMAL_SEPARATOR = 2;
+    private static final int GROUPING_SEPARATOR = 3;
+    private static final int PATTERN_SEPARATOR = 4;
+    private static final int PERCENT = 5;
+    private static final int PER_MILL = 6;
+    private static final int EXPONENT = 7;
+    private static final int MONETARY_DECIMAL_SEPARATOR = 8;
+    private static final int MINUS_SIGN = 9;
+
+    // TODO: replace this with individual char fields.
     private transient char[] patternChars;
 
     private transient Currency currency;
@@ -94,7 +102,43 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
         // END android-changed
     }
 
- 
+    /**
+     * Returns a new {@code DecimalFormatSymbols} instance for the default locale.
+     *
+     * @return an instance of {@code DecimalFormatSymbols}
+     * @since 1.6
+     * @hide
+     */
+    public static final DecimalFormatSymbols getInstance() {
+        return getInstance(Locale.getDefault());
+    }
+
+    /**
+     * Returns a new {@code DecimalFormatSymbols} for the given locale.
+     *
+     * @param locale the locale
+     * @return an instance of {@code DecimalFormatSymbols}
+     * @exception NullPointerException if {@code locale == null}
+     * @since 1.6
+     * @hide
+     */
+    public static final DecimalFormatSymbols getInstance(Locale locale) {
+        if (locale == null) {
+            throw new NullPointerException();
+        }
+        return new DecimalFormatSymbols(locale);
+    }
+
+    /**
+     * Returns an array of locales for which custom {@code DecimalFormatSymbols} instances
+     * are available.
+     * @since 1.6
+     * @hide
+     */
+    public static Locale[] getAvailableLocales() {
+        return Locale.getAvailableLocales();
+    }
+
     /**
      * Returns a new {@code DecimalFormatSymbols} with the same symbols as this
      * {@code DecimalFormatSymbols}.
@@ -140,6 +184,17 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
                 && intlCurrencySymbol.equals(obj.intlCurrencySymbol);
     }
 
+    @Override
+    public String toString() {
+        // Most of the externally-visible state is stashed in 'patternChars', and not obviously
+        // worth breaking out individually, since this is only meant for debugging.
+        return getClass() + "[patternChars=" + new String(patternChars) +
+                ",infinity=" + infinity +
+                ",currencySymbol=" + currencySymbol +
+                ",intlCurrencySymbol=" + intlCurrencySymbol +
+                "]";
+    }
+
     /**
      * Returns the currency.
      * <p>
@@ -182,7 +237,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the decimal separator character.
      */
     public char getDecimalSeparator() {
-        return patternChars[DecimalSeparator];
+        return patternChars[DECIMAL_SEPARATOR];
     }
 
     /**
@@ -192,7 +247,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the digit pattern character.
      */
     public char getDigit() {
-        return patternChars[Digit];
+        return patternChars[DIGIT];
     }
 
     /**
@@ -201,7 +256,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the thousands separator character.
      */
     public char getGroupingSeparator() {
-        return patternChars[GroupingSeparator];
+        return patternChars[GROUPING_SEPARATOR];
     }
 
     /**
@@ -219,7 +274,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the minus sign as a character.
      */
     public char getMinusSign() {
-        return patternChars[MinusSign];
+        return patternChars[MINUS_SIGN];
     }
 
     /**
@@ -229,7 +284,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the monetary decimal point as a character.
      */
     public char getMonetaryDecimalSeparator() {
-        return patternChars[MonetaryDecimalSeparator];
+        return patternChars[MONETARY_DECIMAL_SEPARATOR];
     }
 
     /**
@@ -248,7 +303,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the pattern separator character.
      */
     public char getPatternSeparator() {
-        return patternChars[PatternSeparator];
+        return patternChars[PATTERN_SEPARATOR];
     }
 
     /**
@@ -257,7 +312,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the percent character.
      */
     public char getPercent() {
-        return patternChars[Percent];
+        return patternChars[PERCENT];
     }
 
     /**
@@ -266,7 +321,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the per mill sign character.
      */
     public char getPerMill() {
-        return patternChars[PerMill];
+        return patternChars[PER_MILL];
     }
 
     /**
@@ -275,14 +330,14 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      * @return the zero character.
      */
     public char getZeroDigit() {
-        return patternChars[ZeroDigit];
+        return patternChars[ZERO_DIGIT];
     }
 
     /*
      * Returns the exponent as a character.
      */
     char getExponential() {
-        return patternChars[Exponent];
+        return patternChars[EXPONENT];
     }
 
     @Override
@@ -364,7 +419,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the decimal separator character.
      */
     public void setDecimalSeparator(char value) {
-        patternChars[DecimalSeparator] = value;
+        patternChars[DECIMAL_SEPARATOR] = value;
     }
 
     /**
@@ -374,7 +429,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the digit character.
      */
     public void setDigit(char value) {
-        patternChars[Digit] = value;
+        patternChars[DIGIT] = value;
     }
 
     /**
@@ -384,7 +439,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the grouping separator character.
      */
     public void setGroupingSeparator(char value) {
-        patternChars[GroupingSeparator] = value;
+        patternChars[GROUPING_SEPARATOR] = value;
     }
 
     /**
@@ -404,7 +459,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the minus sign character.
      */
     public void setMinusSign(char value) {
-        patternChars[MinusSign] = value;
+        patternChars[MINUS_SIGN] = value;
     }
 
     /**
@@ -415,7 +470,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the monetary decimal separator character.
      */
     public void setMonetaryDecimalSeparator(char value) {
-        patternChars[MonetaryDecimalSeparator] = value;
+        patternChars[MONETARY_DECIMAL_SEPARATOR] = value;
     }
 
     /**
@@ -436,7 +491,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the pattern separator character.
      */
     public void setPatternSeparator(char value) {
-        patternChars[PatternSeparator] = value;
+        patternChars[PATTERN_SEPARATOR] = value;
     }
 
     /**
@@ -446,7 +501,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the percent character.
      */
     public void setPercent(char value) {
-        patternChars[Percent] = value;
+        patternChars[PERCENT] = value;
     }
 
     /**
@@ -456,7 +511,7 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the per mill character.
      */
     public void setPerMill(char value) {
-        patternChars[PerMill] = value;
+        patternChars[PER_MILL] = value;
     }
 
     /**
@@ -466,14 +521,14 @@ public final class DecimalFormatSymbols implements Cloneable, Serializable {
      *            the zero digit character.
      */
     public void setZeroDigit(char value) {
-        patternChars[ZeroDigit] = value;
+        patternChars[ZERO_DIGIT] = value;
     }
 
     /*
      * Sets the exponent character.
      */
     void setExponential(char value) {
-        patternChars[Exponent] = value;
+        patternChars[EXPONENT] = value;
     }
 
     private static final ObjectStreamField[] serialPersistentFields = {
diff --git a/text/src/main/java/java/text/NumberFormat.java b/text/src/main/java/java/text/NumberFormat.java
index 2bf898d..b187f53 100644
--- a/text/src/main/java/java/text/NumberFormat.java
+++ b/text/src/main/java/java/text/NumberFormat.java
@@ -315,9 +315,8 @@ public abstract class NumberFormat extends Format {
     }
 
     /**
-     * Gets the list of installed locales which support {@code NumberFormat}.
-     * 
-     * @return an array of locales.
+     * Returns an array of locales for which custom {@code NumberFormat} instances
+     * are available.
      */
     public static Locale[] getAvailableLocales() {
         return Locale.getAvailableLocales();
diff --git a/text/src/main/java/java/text/spi/BreakIteratorProvider.java b/text/src/main/java/java/text/spi/BreakIteratorProvider.java
index 70caeb2..e2f85d7 100644
--- a/text/src/main/java/java/text/spi/BreakIteratorProvider.java
+++ b/text/src/main/java/java/text/spi/BreakIteratorProvider.java
@@ -24,6 +24,7 @@ import java.util.spi.LocaleServiceProvider;
 /**
  * This abstract class should be extended by service providers that provide
  * instances of {@code BreakIterator}.
+ * <p>Note that Android does not currently support user-supplied locale service providers.
  * @since 1.6
  * @hide
  */