LocaleListCompat

Added in 1.1.0

public final class LocaleListCompat


Helper for accessing features in LocaleList.

Summary

Public methods

static @NonNull LocaleListCompat
create(@NonNull Locale[] localeList)

Creates a new instance of LocaleListCompat from the Locale array.

boolean
equals(Object other)
static @NonNull LocaleListCompat

Generates a new LocaleList with the given language tags.

@Nullable Locale
get(int index)

Retrieves the Locale at the specified index.

static @NonNull @Size(min = 1) LocaleListCompat

Returns the default locale list, adjusted by moving the default locale to its first position.

static @NonNull @Size(min = 1) LocaleListCompat

The result is guaranteed to include the default Locale returned by Locale.getDefault(), but not necessarily at the top of the list.

static @NonNull LocaleListCompat

Retrieve an empty instance of LocaleListCompat.

@Nullable Locale
getFirstMatch(@NonNull String[] supportedLocales)

Returns the first match in the locale list given an unordered array of supported locales in BCP 47 format.

int
@IntRange(from = "-1") int

Searches this LocaleListCompat for the specified Locale and returns the index of the first occurrence.

boolean

Returns whether the LocaleListCompat contains no Locale items.

static boolean
@RequiresApi(value = 21)
matchesLanguageAndScript(
    @NonNull Locale supported,
    @NonNull Locale desired
)

Determine whether two locales are considered a match, even if they are not exactly equal.

@IntRange(from = 0) int

Returns the number of Locale items in this LocaleListCompat.

@NonNull String

Retrieves a String representation of the language tags in this list.

@NonNull String
@Nullable Object

Gets the underlying framework object.

static LocaleListCompat
@RequiresApi(value = 24)
wrap(Object localeList)

This method is deprecated.

Use wrap

static @NonNull LocaleListCompat
@RequiresApi(value = 24)
wrap(@NonNull LocaleList localeList)

Creates a new instance of LocaleListCompat from the Locale list.

Public methods

create

public static @NonNull LocaleListCompat create(@NonNull Locale[] localeList)

Creates a new instance of LocaleListCompat from the Locale array.

equals

public boolean equals(Object other)

forLanguageTags

Added in 1.1.0
public static @NonNull LocaleListCompat forLanguageTags(@Nullable String list)

Generates a new LocaleList with the given language tags.

Note that for API <24 only the first language tag will be used.

Parameters
@Nullable String list

The language tags to be included as a single String separated by commas.

Returns
@NonNull LocaleListCompat

A new instance with the Locale items identified by the given tags.

get

Added in 1.1.0
public @Nullable Locale get(int index)

Retrieves the Locale at the specified index.

Parameters
int index

The position to retrieve.

Returns
@Nullable Locale

The Locale in the given index

getAdjustedDefault

Added in 1.1.0
public static @NonNull @Size(min = 1) LocaleListCompat getAdjustedDefault()

Returns the default locale list, adjusted by moving the default locale to its first position.

getDefault

Added in 1.1.0
public static @NonNull @Size(min = 1) LocaleListCompat getDefault()

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.

Note that for API >= 24 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.

getEmptyLocaleList

Added in 1.1.0
public static @NonNull LocaleListCompat getEmptyLocaleList()

Retrieve an empty instance of LocaleListCompat.

getFirstMatch

Added in 1.1.0
public @Nullable Locale getFirstMatch(@NonNull String[] supportedLocales)

Returns the first match in the locale list given an unordered array of supported locales in BCP 47 format.

Returns
@Nullable Locale

The first Locale from this list that appears in the given array, or null if the LocaleListCompat is empty.

hashCode

public int hashCode()

indexOf

Added in 1.1.0
public @IntRange(from = "-1") int indexOf(@Nullable Locale locale)

Searches this LocaleListCompat for the specified Locale and returns the index of the first occurrence.

Parameters
@Nullable Locale locale

The Locale to search for.

Returns
@IntRange(from = "-1") int

The index of the first occurrence of the Locale or -1 if the item wasn't found

isEmpty

Added in 1.1.0
public boolean isEmpty()

Returns whether the LocaleListCompat contains no Locale items.

Returns
boolean

true if this LocaleListCompat has no Locale items, false otherwise

matchesLanguageAndScript

Added in 1.9.0
@RequiresApi(value = 21)
public static boolean matchesLanguageAndScript(
    @NonNull Locale supported,
    @NonNull Locale desired
)

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].

Parameters
@NonNull Locale supported

The supported Locale to be compared.

@NonNull Locale desired

The desired Locale to be compared.

Returns
boolean

True if they match, false otherwise.

size

Added in 1.1.0
public @IntRange(from = 0) int size()

Returns the number of Locale items in this LocaleListCompat.

toLanguageTags

Added in 1.1.0
public @NonNull String toLanguageTags()

Retrieves a String representation of the language tags in this list.

toString

public @NonNull String toString()

unwrap

Added in 1.1.0
public @Nullable Object unwrap()

Gets the underlying framework object.

Returns
@Nullable Object

an android.os.LocaleList object if API >= 24 , or null if not.

wrap

Added in 1.1.0
Deprecated in 1.1.0
@RequiresApi(value = 24)
public static LocaleListCompat wrap(Object localeList)

wrap

Added in 1.1.0
@RequiresApi(value = 24)
public static @NonNull LocaleListCompat wrap(@NonNull LocaleList localeList)

Creates a new instance of LocaleListCompat from the Locale list.