diff options
| -rw-r--r-- | api/current.txt | 4 | ||||
| -rw-r--r-- | api/system-current.txt | 4 | ||||
| -rw-r--r-- | api/test-current.txt | 4 | ||||
| -rw-r--r-- | core/java/android/util/LocaleList.java | 76 |
4 files changed, 55 insertions, 33 deletions
diff --git a/api/current.txt b/api/current.txt index 15fc14909231..5cd16c9569f0 100644 --- a/api/current.txt +++ b/api/current.txt @@ -40377,9 +40377,7 @@ package android.util { } public final class LocaleList implements android.os.Parcelable { - ctor public LocaleList(); - ctor public LocaleList(java.util.Locale); - ctor public LocaleList(java.util.Locale[]); + ctor public LocaleList(java.util.Locale...); method public int describeContents(); method public static android.util.LocaleList forLanguageTags(java.lang.String); method public java.util.Locale get(int); diff --git a/api/system-current.txt b/api/system-current.txt index c489435bc093..7539f87909db 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -43390,9 +43390,7 @@ package android.util { } public final class LocaleList implements android.os.Parcelable { - ctor public LocaleList(); - ctor public LocaleList(java.util.Locale); - ctor public LocaleList(java.util.Locale[]); + ctor public LocaleList(java.util.Locale...); method public int describeContents(); method public static android.util.LocaleList forLanguageTags(java.lang.String); method public java.util.Locale get(int); diff --git a/api/test-current.txt b/api/test-current.txt index f6340b205d60..73c7aefd1f92 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -40454,9 +40454,7 @@ package android.util { } public final class LocaleList implements android.os.Parcelable { - ctor public LocaleList(); - ctor public LocaleList(java.util.Locale); - ctor public LocaleList(java.util.Locale[]); + ctor public LocaleList(java.util.Locale...); method public int describeContents(); method public static android.util.LocaleList forLanguageTags(java.lang.String); method public java.util.Locale get(int); diff --git a/core/java/android/util/LocaleList.java b/core/java/android/util/LocaleList.java index fa3921c9020e..b153e925fbb0 100644 --- a/core/java/android/util/LocaleList.java +++ b/core/java/android/util/LocaleList.java @@ -32,8 +32,8 @@ import java.util.HashSet; import java.util.Locale; /** - * LocaleList is an immutable list of Locales, typically used to keep an - * ordered user preferences for locales. + * LocaleList is an immutable list of Locales, typically used to keep an ordered list of user + * preferences for locales. */ public final class LocaleList implements Parcelable { private final Locale[] mList; @@ -46,19 +46,42 @@ public final class LocaleList implements Parcelable { private static final Locale[] sEmptyList = new Locale[0]; private static final LocaleList sEmptyLocaleList = new LocaleList(); - public Locale get(int location) { - return (0 <= location && location < mList.length) ? mList[location] : null; + /** + * Retrieves the {@link Locale} at the specified index. + * + * @param index The position to retrieve. + * @return The {@link Locale} in the given index. + */ + public Locale get(int index) { + return (0 <= index && index < mList.length) ? mList[index] : null; } + /** + * Returns whether the {@link LocaleList} contains no {@link Locale} items. + * + * @return {@code true} if this {@link LocaleList} has no {@link Locale} items, {@code false} + * otherwise. + */ public boolean isEmpty() { return mList.length == 0; } + /** + * Returns the number of {@link Locale} items in this {@link LocaleList}. + */ @IntRange(from=0) public int size() { return mList.length; } + /** + * Searches this {@link LocaleList} for the specified {@link Locale} and returns the index of + * the first occurrence. + * + * @param locale The {@link Locale} to search for. + * @return The index of the first occurrence of the {@link Locale} or {@code -1} if the item + * wasn't found. + */ @IntRange(from=-1) public int indexOf(Locale locale) { for (int i = 0; i < mList.length; i++) { @@ -118,6 +141,9 @@ public final class LocaleList implements Parcelable { dest.writeString(mStringRepresentation); } + /** + * Retrieves a String representation of the language tags in this list. + */ @NonNull public String toLanguageTags() { return mStringRepresentation; @@ -126,6 +152,8 @@ public final class LocaleList implements Parcelable { /** * It is almost always better to call {@link #getEmptyLocaleList()} instead which returns * a pre-constructed empty locale list. + * + * @hide */ public LocaleList() { mList = sEmptyList; @@ -133,25 +161,15 @@ public final class LocaleList implements Parcelable { } /** + * Creates a new {@link LocaleList}. + * + * <p>For empty lists of {@link Locale} items it is better to use {@link #getEmptyLocaleList()}, + * which returns a pre-constructed empty list.</p> + * * @throws NullPointerException if any of the input locales is <code>null</code>. * @throws IllegalArgumentException if any of the input locales repeat. */ - public LocaleList(@Nullable Locale locale) { - if (locale == null) { - mList = sEmptyList; - mStringRepresentation = ""; - } else { - mList = new Locale[1]; - mList[0] = (Locale) locale.clone(); - mStringRepresentation = locale.toLanguageTag(); - } - } - - /** - * @throws NullPointerException if any of the input locales is <code>null</code>. - * @throws IllegalArgumentException if any of the input locales repeat. - */ - public LocaleList(@Nullable Locale[] list) { + public LocaleList(@Nullable Locale... list) { if (list == null || list.length == 0) { mList = sEmptyList; mStringRepresentation = ""; @@ -242,11 +260,20 @@ public final class LocaleList implements Parcelable { } }; + /** + * Retrieve an empty instance of {@link LocaleList}. + */ @NonNull public static LocaleList getEmptyLocaleList() { return sEmptyLocaleList; } + /** + * Generates a new LocaleList with the given language tags. + * + * @param list The language tags to be included as a single {@link String} separated by commas. + * @return A new instance with the {@link Locale} items identified by the given tags. + */ @NonNull public static LocaleList forLanguageTags(@Nullable String list) { if (list == null || list.equals("")) { @@ -374,7 +401,8 @@ public final class LocaleList implements Parcelable { * Returns the first match in the locale list given an unordered array of supported locales * in BCP 47 format. * - * If the locale list is empty, null would be returned. + * @return The first {@link Locale} from this list that appears in the given array, or + * {@code null} if the {@link LocaleList} is empty. */ @Nullable public Locale getFirstMatch(String[] supportedLocales) { @@ -445,9 +473,9 @@ public final class LocaleList implements Parcelable { * preferred locales, having concluded that the primary preference is not supported but a * secondary preference is. * - * Note that the default LocaleList would change if Locale.setDefault() is called. This method - * takes that into account by always checking the output of Locale.getDefault() and - * recalculating the default LocaleList if needed. + * <p>Note that the default LocaleList would change if Locale.setDefault() is called. This + * method takes that into account by always checking the output of Locale.getDefault() and + * recalculating the default LocaleList if needed.</p> */ @NonNull @Size(min=1) public static LocaleList getDefault() { |