601 lines
22 KiB
Java
601 lines
22 KiB
Java
/*
|
|
* 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.SuppressLint;
|
|
import android.compat.annotation.UnsupportedAppUsage;
|
|
import android.icu.util.ULocale;
|
|
|
|
import com.android.internal.annotations.GuardedBy;
|
|
|
|
import java.util.ArrayList;
|
|
import java.util.Arrays;
|
|
import java.util.Collection;
|
|
import java.util.HashSet;
|
|
import java.util.List;
|
|
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(@Nullable 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.writeString8(mStringRepresentation);
|
|
}
|
|
|
|
/**
|
|
* Retrieves a String representation of the language tags in this list.
|
|
*/
|
|
@NonNull
|
|
public String toLanguageTags() {
|
|
return mStringRepresentation;
|
|
}
|
|
|
|
/**
|
|
* Find the intersection between this LocaleList and another
|
|
* @return an array of the Locales in both LocaleLists
|
|
* {@hide}
|
|
*/
|
|
@NonNull
|
|
public Locale[] getIntersection(@NonNull LocaleList other) {
|
|
List<Locale> intersection = new ArrayList<>();
|
|
for (Locale l1 : mList) {
|
|
for (Locale l2 : other.mList) {
|
|
if (matchesLanguageAndScript(l2, l1)) {
|
|
intersection.add(l1);
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
return intersection.toArray(new Locale[0]);
|
|
}
|
|
|
|
/**
|
|
* Creates a new {@link LocaleList}.
|
|
*
|
|
* If two or more same locales are passed, the repeated locales will be dropped.
|
|
* <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>.
|
|
*/
|
|
public LocaleList(@NonNull Locale... list) {
|
|
if (list.length == 0) {
|
|
mList = sEmptyList;
|
|
mStringRepresentation = "";
|
|
} else {
|
|
final ArrayList<Locale> localeList = new ArrayList<>();
|
|
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)) {
|
|
// Dropping duplicated locale entries.
|
|
} else {
|
|
final Locale localeClone = (Locale) l.clone();
|
|
localeList.add(localeClone);
|
|
sb.append(localeClone.toLanguageTag());
|
|
if (i < list.length - 1) {
|
|
sb.append(',');
|
|
}
|
|
seenLocales.add(localeClone);
|
|
}
|
|
}
|
|
mList = localeList.toArray(new Locale[localeList.size()]);
|
|
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.readString8());
|
|
}
|
|
|
|
@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);
|
|
}
|
|
|
|
/**
|
|
* Determine whether two locales are considered a match, even if they are not exactly equal.
|
|
* They are considered as a match when both of their languages and scripts
|
|
* (explicit or inferred) are identical. This means that a user would be able to understand
|
|
* the content written in the supported locale even if they say they prefer the desired locale.
|
|
*
|
|
* E.g. [zh-HK] matches [zh-Hant]; [en-US] matches [en-CA]
|
|
*
|
|
* @param supported The supported {@link Locale} to be compared.
|
|
* @param desired The desired {@link Locale} to be compared.
|
|
* @return True if they match, false otherwise.
|
|
*/
|
|
public static boolean matchesLanguageAndScript(@SuppressLint("UseIcu") @NonNull
|
|
Locale supported, @SuppressLint("UseIcu") @NonNull Locale desired) {
|
|
if (supported.equals(desired)) {
|
|
return true; // return early so we don't do unnecessary computation
|
|
}
|
|
if (!supported.getLanguage().equals(desired.getLanguage())) {
|
|
return false;
|
|
}
|
|
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 false;
|
|
}
|
|
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());
|
|
}
|
|
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);
|
|
}
|
|
|
|
private int findFirstMatchIndex(Locale supportedLocale) {
|
|
for (int idx = 0; idx < mList.length; idx++) {
|
|
if (matchesLanguageAndScript(supportedLocale, mList[idx])) {
|
|
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(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
|
|
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);
|
|
}
|
|
}
|
|
}
|
|
}
|