| /* |
| * Copyright (C) 2015 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.os; |
| |
| import android.annotation.IntRange; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.annotation.Size; |
| import android.annotation.UnsupportedAppUsage; |
| import android.icu.util.ULocale; |
| |
| import com.android.internal.annotations.GuardedBy; |
| |
| import java.util.Arrays; |
| import java.util.Collection; |
| import java.util.HashSet; |
| import java.util.Locale; |
| |
| /** |
| * 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; |
| // This is a comma-separated list of the locales in the LocaleList created at construction time, |
| // basically the result of running each locale's toLanguageTag() method and concatenating them |
| // with commas in between. |
| @NonNull |
| private final String mStringRepresentation; |
| |
| private static final Locale[] sEmptyList = new Locale[0]; |
| private static final LocaleList sEmptyLocaleList = new LocaleList(); |
| |
| /** |
| * 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++) { |
| if (mList[i].equals(locale)) { |
| return i; |
| } |
| } |
| return -1; |
| } |
| |
| @Override |
| public boolean equals(Object other) { |
| if (other == this) |
| return true; |
| if (!(other instanceof LocaleList)) |
| return false; |
| final Locale[] otherList = ((LocaleList) other).mList; |
| if (mList.length != otherList.length) |
| return false; |
| for (int i = 0; i < mList.length; i++) { |
| if (!mList[i].equals(otherList[i])) |
| return false; |
| } |
| return true; |
| } |
| |
| @Override |
| public int hashCode() { |
| int result = 1; |
| for (int i = 0; i < mList.length; i++) { |
| result = 31 * result + mList[i].hashCode(); |
| } |
| return result; |
| } |
| |
| @Override |
| public String toString() { |
| StringBuilder sb = new StringBuilder(); |
| sb.append("["); |
| for (int i = 0; i < mList.length; i++) { |
| sb.append(mList[i]); |
| if (i < mList.length - 1) { |
| sb.append(','); |
| } |
| } |
| sb.append("]"); |
| return sb.toString(); |
| } |
| |
| @Override |
| public int describeContents() { |
| return 0; |
| } |
| |
| @Override |
| public void writeToParcel(Parcel dest, int parcelableFlags) { |
| dest.writeString(mStringRepresentation); |
| } |
| |
| /** |
| * Retrieves a String representation of the language tags in this list. |
| */ |
| @NonNull |
| public String toLanguageTags() { |
| return mStringRepresentation; |
| } |
| |
| /** |
| * 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(@NonNull Locale... list) { |
| if (list.length == 0) { |
| mList = sEmptyList; |
| mStringRepresentation = ""; |
| } else { |
| final Locale[] localeList = new Locale[list.length]; |
| final HashSet<Locale> seenLocales = new HashSet<Locale>(); |
| final StringBuilder sb = new StringBuilder(); |
| for (int i = 0; i < list.length; i++) { |
| final Locale l = list[i]; |
| if (l == null) { |
| throw new NullPointerException("list[" + i + "] is null"); |
| } else if (seenLocales.contains(l)) { |
| throw new IllegalArgumentException("list[" + i + "] is a repetition"); |
| } else { |
| final Locale localeClone = (Locale) l.clone(); |
| localeList[i] = localeClone; |
| sb.append(localeClone.toLanguageTag()); |
| if (i < list.length - 1) { |
| sb.append(','); |
| } |
| seenLocales.add(localeClone); |
| } |
| } |
| mList = localeList; |
| mStringRepresentation = sb.toString(); |
| } |
| } |
| |
| /** |
| * Constructs a locale list, with the topLocale moved to the front if it already is |
| * in otherLocales, or added to the front if it isn't. |
| * |
| * {@hide} |
| */ |
| public LocaleList(@NonNull Locale topLocale, LocaleList otherLocales) { |
| if (topLocale == null) { |
| throw new NullPointerException("topLocale is null"); |
| } |
| |
| final int inputLength = (otherLocales == null) ? 0 : otherLocales.mList.length; |
| int topLocaleIndex = -1; |
| for (int i = 0; i < inputLength; i++) { |
| if (topLocale.equals(otherLocales.mList[i])) { |
| topLocaleIndex = i; |
| break; |
| } |
| } |
| |
| final int outputLength = inputLength + (topLocaleIndex == -1 ? 1 : 0); |
| final Locale[] localeList = new Locale[outputLength]; |
| localeList[0] = (Locale) topLocale.clone(); |
| if (topLocaleIndex == -1) { |
| // topLocale was not in otherLocales |
| for (int i = 0; i < inputLength; i++) { |
| localeList[i + 1] = (Locale) otherLocales.mList[i].clone(); |
| } |
| } else { |
| for (int i = 0; i < topLocaleIndex; i++) { |
| localeList[i + 1] = (Locale) otherLocales.mList[i].clone(); |
| } |
| for (int i = topLocaleIndex + 1; i < inputLength; i++) { |
| localeList[i] = (Locale) otherLocales.mList[i].clone(); |
| } |
| } |
| |
| final StringBuilder sb = new StringBuilder(); |
| for (int i = 0; i < outputLength; i++) { |
| sb.append(localeList[i].toLanguageTag()); |
| if (i < outputLength - 1) { |
| sb.append(','); |
| } |
| } |
| |
| mList = localeList; |
| mStringRepresentation = sb.toString(); |
| } |
| |
| public static final @android.annotation.NonNull Parcelable.Creator<LocaleList> CREATOR |
| = new Parcelable.Creator<LocaleList>() { |
| @Override |
| public LocaleList createFromParcel(Parcel source) { |
| return LocaleList.forLanguageTags(source.readString()); |
| } |
| |
| @Override |
| public LocaleList[] newArray(int size) { |
| return new LocaleList[size]; |
| } |
| }; |
| |
| /** |
| * 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("")) { |
| return getEmptyLocaleList(); |
| } else { |
| final String[] tags = list.split(","); |
| final Locale[] localeArray = new Locale[tags.length]; |
| for (int i = 0; i < localeArray.length; i++) { |
| localeArray[i] = Locale.forLanguageTag(tags[i]); |
| } |
| return new LocaleList(localeArray); |
| } |
| } |
| |
| private static String getLikelyScript(Locale locale) { |
| final String script = locale.getScript(); |
| if (!script.isEmpty()) { |
| return script; |
| } else { |
| // TODO: Cache the results if this proves to be too slow |
| return ULocale.addLikelySubtags(ULocale.forLocale(locale)).getScript(); |
| } |
| } |
| |
| private static final String STRING_EN_XA = "en-XA"; |
| private static final String STRING_AR_XB = "ar-XB"; |
| private static final Locale LOCALE_EN_XA = new Locale("en", "XA"); |
| private static final Locale LOCALE_AR_XB = new Locale("ar", "XB"); |
| private static final int NUM_PSEUDO_LOCALES = 2; |
| |
| private static boolean isPseudoLocale(String locale) { |
| return STRING_EN_XA.equals(locale) || STRING_AR_XB.equals(locale); |
| } |
| |
| /** |
| * Returns true if locale is a pseudo-locale, false otherwise. |
| * {@hide} |
| */ |
| public static boolean isPseudoLocale(Locale locale) { |
| return LOCALE_EN_XA.equals(locale) || LOCALE_AR_XB.equals(locale); |
| } |
| |
| /** |
| * Returns true if locale is a pseudo-locale, false otherwise. |
| */ |
| public static boolean isPseudoLocale(@Nullable ULocale locale) { |
| return isPseudoLocale(locale != null ? locale.toLocale() : null); |
| } |
| |
| @IntRange(from=0, to=1) |
| private static int matchScore(Locale supported, Locale desired) { |
| if (supported.equals(desired)) { |
| return 1; // return early so we don't do unnecessary computation |
| } |
| if (!supported.getLanguage().equals(desired.getLanguage())) { |
| return 0; |
| } |
| if (isPseudoLocale(supported) || isPseudoLocale(desired)) { |
| // The locales are not the same, but the languages are the same, and one of the locales |
| // is a pseudo-locale. So this is not a match. |
| return 0; |
| } |
| final String supportedScr = getLikelyScript(supported); |
| if (supportedScr.isEmpty()) { |
| // If we can't guess a script, we don't know enough about the locales' language to find |
| // if the locales match. So we fall back to old behavior of matching, which considered |
| // locales with different regions different. |
| final String supportedRegion = supported.getCountry(); |
| return (supportedRegion.isEmpty() || |
| supportedRegion.equals(desired.getCountry())) |
| ? 1 : 0; |
| } |
| final String desiredScr = getLikelyScript(desired); |
| // There is no match if the two locales use different scripts. This will most imporantly |
| // take care of traditional vs simplified Chinese. |
| return supportedScr.equals(desiredScr) ? 1 : 0; |
| } |
| |
| private int findFirstMatchIndex(Locale supportedLocale) { |
| for (int idx = 0; idx < mList.length; idx++) { |
| final int score = matchScore(supportedLocale, mList[idx]); |
| if (score > 0) { |
| return idx; |
| } |
| } |
| return Integer.MAX_VALUE; |
| } |
| |
| private static final Locale EN_LATN = Locale.forLanguageTag("en-Latn"); |
| |
| private int computeFirstMatchIndex(Collection<String> supportedLocales, |
| boolean assumeEnglishIsSupported) { |
| if (mList.length == 1) { // just one locale, perhaps the most common scenario |
| return 0; |
| } |
| if (mList.length == 0) { // empty locale list |
| return -1; |
| } |
| |
| int bestIndex = Integer.MAX_VALUE; |
| // Try English first, so we can return early if it's in the LocaleList |
| if (assumeEnglishIsSupported) { |
| final int idx = findFirstMatchIndex(EN_LATN); |
| if (idx == 0) { // We have a match on the first locale, which is good enough |
| return 0; |
| } else if (idx < bestIndex) { |
| bestIndex = idx; |
| } |
| } |
| for (String languageTag : supportedLocales) { |
| final Locale supportedLocale = Locale.forLanguageTag(languageTag); |
| // We expect the average length of locale lists used for locale resolution to be |
| // smaller than three, so it's OK to do this as an O(mn) algorithm. |
| final int idx = findFirstMatchIndex(supportedLocale); |
| if (idx == 0) { // We have a match on the first locale, which is good enough |
| return 0; |
| } else if (idx < bestIndex) { |
| bestIndex = idx; |
| } |
| } |
| if (bestIndex == Integer.MAX_VALUE) { |
| // no match was found, so we fall back to the first locale in the locale list |
| return 0; |
| } else { |
| return bestIndex; |
| } |
| } |
| |
| private Locale computeFirstMatch(Collection<String> supportedLocales, |
| boolean assumeEnglishIsSupported) { |
| int bestIndex = computeFirstMatchIndex(supportedLocales, assumeEnglishIsSupported); |
| return bestIndex == -1 ? null : mList[bestIndex]; |
| } |
| |
| /** |
| * Returns the first match in the locale list given an unordered array of supported locales |
| * in BCP 47 format. |
| * |
| * @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) { |
| return computeFirstMatch(Arrays.asList(supportedLocales), |
| false /* assume English is not supported */); |
| } |
| |
| /** |
| * {@hide} |
| */ |
| public int getFirstMatchIndex(String[] supportedLocales) { |
| return computeFirstMatchIndex(Arrays.asList(supportedLocales), |
| false /* assume English is not supported */); |
| } |
| |
| /** |
| * Same as getFirstMatch(), but with English assumed to be supported, even if it's not. |
| * {@hide} |
| */ |
| @Nullable |
| public Locale getFirstMatchWithEnglishSupported(String[] supportedLocales) { |
| return computeFirstMatch(Arrays.asList(supportedLocales), |
| true /* assume English is supported */); |
| } |
| |
| /** |
| * {@hide} |
| */ |
| public int getFirstMatchIndexWithEnglishSupported(Collection<String> supportedLocales) { |
| return computeFirstMatchIndex(supportedLocales, true /* assume English is supported */); |
| } |
| |
| /** |
| * {@hide} |
| */ |
| public int getFirstMatchIndexWithEnglishSupported(String[] supportedLocales) { |
| return getFirstMatchIndexWithEnglishSupported(Arrays.asList(supportedLocales)); |
| } |
| |
| /** |
| * Returns true if the collection of locale tags only contains empty locales and pseudolocales. |
| * Assumes that there is no repetition in the input. |
| * {@hide} |
| */ |
| public static boolean isPseudoLocalesOnly(@Nullable String[] supportedLocales) { |
| if (supportedLocales == null) { |
| return true; |
| } |
| |
| if (supportedLocales.length > NUM_PSEUDO_LOCALES + 1) { |
| // This is for optimization. Since there's no repetition in the input, if we have more |
| // than the number of pseudo-locales plus one for the empty string, it's guaranteed |
| // that we have some meaninful locale in the collection, so the list is not "practically |
| // empty". |
| return false; |
| } |
| for (String locale : supportedLocales) { |
| if (!locale.isEmpty() && !isPseudoLocale(locale)) { |
| return false; |
| } |
| } |
| return true; |
| } |
| |
| private final static Object sLock = new Object(); |
| |
| @GuardedBy("sLock") |
| private static LocaleList sLastExplicitlySetLocaleList = null; |
| @GuardedBy("sLock") |
| private static LocaleList sDefaultLocaleList = null; |
| @GuardedBy("sLock") |
| private static LocaleList sDefaultAdjustedLocaleList = null; |
| @GuardedBy("sLock") |
| private static Locale sLastDefaultLocale = null; |
| |
| /** |
| * The result is guaranteed to include the default Locale returned by Locale.getDefault(), but |
| * not necessarily at the top of the list. The default locale not being at the top of the list |
| * is an indication that the system has set the default locale to one of the user's other |
| * preferred locales, having concluded that the primary preference is not supported but a |
| * secondary preference is. |
| * |
| * <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() { |
| final Locale defaultLocale = Locale.getDefault(); |
| synchronized (sLock) { |
| if (!defaultLocale.equals(sLastDefaultLocale)) { |
| sLastDefaultLocale = defaultLocale; |
| // It's either the first time someone has asked for the default locale list, or |
| // someone has called Locale.setDefault() since we last set or adjusted the default |
| // locale list. So let's recalculate the locale list. |
| if (sDefaultLocaleList != null |
| && defaultLocale.equals(sDefaultLocaleList.get(0))) { |
| // The default Locale has changed, but it happens to be the first locale in the |
| // default locale list, so we don't need to construct a new locale list. |
| return sDefaultLocaleList; |
| } |
| sDefaultLocaleList = new LocaleList(defaultLocale, sLastExplicitlySetLocaleList); |
| sDefaultAdjustedLocaleList = sDefaultLocaleList; |
| } |
| // sDefaultLocaleList can't be null, since it can't be set to null by |
| // LocaleList.setDefault(), and if getDefault() is called before a call to |
| // setDefault(), sLastDefaultLocale would be null and the check above would set |
| // sDefaultLocaleList. |
| return sDefaultLocaleList; |
| } |
| } |
| |
| /** |
| * Returns the default locale list, adjusted by moving the default locale to its first |
| * position. |
| */ |
| @NonNull @Size(min=1) |
| public static LocaleList getAdjustedDefault() { |
| getDefault(); // to recalculate the default locale list, if necessary |
| synchronized (sLock) { |
| return sDefaultAdjustedLocaleList; |
| } |
| } |
| |
| /** |
| * Also sets the default locale by calling Locale.setDefault() with the first locale in the |
| * list. |
| * |
| * @throws NullPointerException if the input is <code>null</code>. |
| * @throws IllegalArgumentException if the input is empty. |
| */ |
| public static void setDefault(@NonNull @Size(min=1) LocaleList locales) { |
| setDefault(locales, 0); |
| } |
| |
| /** |
| * This may be used directly by system processes to set the default locale list for apps. For |
| * such uses, the default locale list would always come from the user preferences, but the |
| * default locale may have been chosen to be a locale other than the first locale in the locale |
| * list (based on the locales the app supports). |
| * |
| * {@hide} |
| */ |
| @UnsupportedAppUsage |
| public static void setDefault(@NonNull @Size(min=1) LocaleList locales, int localeIndex) { |
| if (locales == null) { |
| throw new NullPointerException("locales is null"); |
| } |
| if (locales.isEmpty()) { |
| throw new IllegalArgumentException("locales is empty"); |
| } |
| synchronized (sLock) { |
| sLastDefaultLocale = locales.get(localeIndex); |
| Locale.setDefault(sLastDefaultLocale); |
| sLastExplicitlySetLocaleList = locales; |
| sDefaultLocaleList = locales; |
| if (localeIndex == 0) { |
| sDefaultAdjustedLocaleList = sDefaultLocaleList; |
| } else { |
| sDefaultAdjustedLocaleList = new LocaleList( |
| sLastDefaultLocale, sDefaultLocaleList); |
| } |
| } |
| } |
| } |