Enum Cardinality

java.lang.Object

java.lang.Enum<Cardinality>

com.lokalized.Cardinality

All Implemented Interfaces:

LanguageForm, Serializable, Comparable<Cardinality>, Constable

public enum Cardinality
extends Enum<Cardinality>
implements LanguageForm

Language plural cardinality forms.

For example, English has two: 1 dog, 2 dogs, while Welsh has many: 0 cŵn, 1 ci, 2 gi, 3 chi, 4 ci.

See the Unicode Common Locale Data Repository and its Language Plural Rules for details.

Per the CLDR:

These categories are only mnemonics -- the names don't necessarily imply the exact contents of the category. For example, for both English and French the number 1 has the category one (singular).

In English, every other number has a plural form, and is given the category other. French is similar, except that the number 0 also has the category one and not other or zero, because the form of units qualified by 0 is also singular.

This is worth emphasizing: A common mistake is to think that "one" is only for only the number 1. Instead, "one" is a category for any number that behaves like 1. So in some languages, for example, one → numbers that end in "1" (like 1, 21, 151) but that don't end in 11 (like "11, 111, 10311).

Author:

Mark Allen

Nested Class Summary

Nested classes/interfaces inherited from class Enum

Enum.EnumDesc<E>

Enum Constant Summary

Enum Constants

Enum Constant	Description
FEW	The form that falls between TWO and MANY.
MANY	The form that falls between FEW and OTHER.
ONE	The form used with 1.
OTHER	General "catchall" form which comprises any cases not handled by the other forms.
TWO	Normally the form used with 2, if it is limited to numbers whose integer values end with 2.
ZERO	Normally the form used with 0, if it is limited to numbers whose integer values end with 0.

Method Summary

Modifier and Type	Method	Description
static @NonNull SortedMap<@NonNull Cardinality, @NonNull Range<@NonNull BigDecimal>>	exampleDecimalValuesForLocale(@NonNull Locale locale)	Gets a mapping of cardinalities to example decimal values for the given locale.
static @NonNull SortedMap<@NonNull Cardinality, @NonNull Range<@NonNull Integer>>	exampleIntegerValuesForLocale(@NonNull Locale locale)	Gets a mapping of cardinalities to example integer values for the given locale.
static @NonNull Cardinality	forNumber(@NonNull Number number, @Nullable Integer visibleDecimalPlaces, @NonNull Locale locale)	Gets an appropriate plural cardinality for the given number, visible decimal places, and locale.
static @NonNull Cardinality	forNumber(@NonNull Number number, @NonNull Locale locale)	Gets an appropriate plural cardinality for the given number and locale.
static @NonNull Cardinality	forOperands(@NonNull PluralOperands operands, @NonNull Locale locale)	Gets an appropriate plural cardinality for the given CLDR plural operands and locale.
static @NonNull Cardinality	forRange(@NonNull Cardinality start, @NonNull Cardinality end, @NonNull Locale locale)	Gets an appropriate plural cardinality for the given range (start, end) and locale.
static @NonNull SortedSet<@NonNull String>	getSupportedLocaleTags()	Gets the BCP 47 locale tags represented directly in the generated CLDR cardinality-rule data.
static @NonNull SortedSet<@NonNull Cardinality>	supportedCardinalitiesForLocale(@NonNull Locale locale)	Gets the set of cardinalities supported for the given locale.
static Cardinality	valueOf(String name)	Returns the enum constant of this type with the specified name.
static Cardinality[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class Enum

compareTo, describeConstable, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

ZERO

public static final Cardinality ZERO

Normally the form used with 0, if it is limited to numbers whose integer values end with 0.

For example: the Welsh 0 cŵn, 0 cathod means 0 dogs, 0 cats in English.

ONE

public static final Cardinality ONE

The form used with 1.

For example: the Welsh 1 ci, 1 gath means 1 dog, 1 cat in English.

TWO

public static final Cardinality TWO

Normally the form used with 2, if it is limited to numbers whose integer values end with 2.

For example: the Welsh 2 gi, 2 gath means 2 dogs, 2 cats in English.

FEW

public static final Cardinality FEW

The form that falls between TWO and MANY.

For example: the Welsh 3 chi, 3 cath means 3 dogs, 3 cats in English.

MANY

public static final Cardinality MANY

The form that falls between FEW and OTHER.

For example: the Welsh 6 chi, 6 chath means 6 dogs, 6 cats in English.

OTHER

public static final Cardinality OTHER

General "catchall" form which comprises any cases not handled by the other forms.

For example: the Welsh 4 ci, 4 cath means 4 dogs, 4 cats in English.

Method Details

values

public static Cardinality[] values()

Returns an array containing the constants of this enum type, in the order they are declared.

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Cardinality valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

forNumber

public static @NonNull Cardinality forNumber(@NonNull Number number,
 @NonNull Locale locale)

Gets an appropriate plural cardinality for the given number and locale.

Negative numbers are evaluated using their absolute value.

When determining cardinality, the decimal places of number will be computed and used. Note that if trailing zeroes are important, e.g. 1.00 instead of 1, you must either specify a BigDecimal with appropriate scale or supply a non-null visibleDecimalPlaces value.

If you do not provide a BigDecimal and wish to manually specify the number of visible decimals, use forNumber(Number, Integer, Locale) instead. Supported Number implementations and their conversion semantics are documented by PluralOperands.forNumber(Number). This convenience method uses TranslationRuntimeLimits.defaults(). To apply different limits, construct PluralOperands with PluralOperands.Builder.runtimeLimits(TranslationRuntimeLimits) and call forOperands(PluralOperands, Locale).

See the CLDR Language Plural Rules for further details.

Parameters:

number - the number that drives pluralization, not null

locale - the locale that drives pluralization, not null

Returns:

an appropriate plural cardinality, not null

Throws:

UnsupportedLocaleException - if the locale is not supported

IllegalArgumentException - if the locale is malformed, the number implementation is unsupported, the number is non-finite, or the number exceeds the safety limits documented by PluralOperands

forNumber

public static @NonNull Cardinality forNumber(@NonNull Number number,
 @Nullable Integer visibleDecimalPlaces,
 @NonNull Locale locale)

Gets an appropriate plural cardinality for the given number, visible decimal places, and locale.

Negative numbers are evaluated using their absolute value.

If visibleDecimalPlaces is null, then the decimal places of number will be computed and used. Note that if trailing zeroes are important, e.g. 1.00 instead of 1, you must either specify a BigDecimal with appropriate scale or supply a non-null visibleDecimalPlaces value. Reducing the number's scale does not round implicitly; callers must supply an already-rounded value. Supported Number implementations and their conversion semantics are documented by PluralOperands.forNumber(Number). This convenience method uses TranslationRuntimeLimits.defaults(). To apply different limits, construct PluralOperands with PluralOperands.Builder.runtimeLimits(TranslationRuntimeLimits) and call forOperands(PluralOperands, Locale).

See the CLDR Language Plural Rules for further details.

Parameters:

number - the number that drives pluralization, not null

visibleDecimalPlaces - the number of decimal places that will ultimately be displayed, may be null

locale - the locale that drives pluralization, not null

Returns:

an appropriate plural cardinality, not null

Throws:

UnsupportedLocaleException - if the locale is not supported

ArithmeticException - if the requested visible decimal places would require rounding

IllegalArgumentException - if the locale is malformed, the number implementation is unsupported, the number is non-finite, or the number or visible decimal places exceeds the safety limits documented by PluralOperands

forOperands

public static @NonNull Cardinality forOperands(@NonNull PluralOperands operands,
 @NonNull Locale locale)

Gets an appropriate plural cardinality for the given CLDR plural operands and locale.

Most applications should use forNumber(Number, Locale). Use this overload when the displayed number has details that are not fully represented by the Java Number, such as a compact-decimal exponent.

See the CLDR Language Plural Rules for further details.

Parameters:

operands - the CLDR plural operands that drive pluralization, not null

locale - the locale that drives pluralization, not null

Returns:

an appropriate plural cardinality, not null

Throws:

UnsupportedLocaleException - if the locale is not supported

IllegalArgumentException - if the locale is malformed

Since:

3.0.0

forRange

public static @NonNull Cardinality forRange(@NonNull Cardinality start,
 @NonNull Cardinality end,
 @NonNull Locale locale)

Gets an appropriate plural cardinality for the given range (start, end) and locale.

For example, a range might be "1-3 hours".

Note that the cardinality of the end of the range does not necessarily determine the range's cardinality. In English, we say "0–1 days" - the value 1 is CARDINALITY_ONE but the range is CARDINALITY_OTHER.

See the CLDR Language Plural Rules for further details.

Parameters:

start - the cardinality for the start of the range, not null

end - the cardinality for the end of the range, not null

locale - the locale that drives pluralization, not null

Returns:

an appropriate plural cardinality for the range, not null

Throws:

UnsupportedLocaleException - if the locale is not supported

IllegalArgumentException - if the locale is malformed

supportedCardinalitiesForLocale

public static @NonNull SortedSet<@NonNull Cardinality> supportedCardinalitiesForLocale(@NonNull Locale locale)

Gets the set of cardinalities supported for the given locale.

The empty set will be returned if the locale is not supported.

The set's values are sorted by the natural ordering of the Cardinality enumeration.

Parameters:

locale - the locale to use for lookup, not null

Returns:

the cardinalities supported by the given locale, not null

Throws:

IllegalArgumentException - if the locale is malformed

exampleIntegerValuesForLocale

public static @NonNull SortedMap<@NonNull Cardinality, @NonNull Range<@NonNull Integer>> exampleIntegerValuesForLocale(@NonNull Locale locale)

Gets a mapping of cardinalities to example integer values for the given locale.

The empty map will be returned if the locale is not supported or if no example values are available.

The map's keys are sorted by the natural ordering of the Cardinality enumeration.

Parameters:

locale - the locale to use for lookup, not null

Returns:

a mapping of cardinalities to example integer values, not null

Throws:

IllegalArgumentException - if the locale is malformed

exampleDecimalValuesForLocale

public static @NonNull SortedMap<@NonNull Cardinality, @NonNull Range<@NonNull BigDecimal>> exampleDecimalValuesForLocale(@NonNull Locale locale)

Gets a mapping of cardinalities to example decimal values for the given locale.

The empty map will be returned if the locale is not supported or if no example values are available.

The map's keys are sorted by the natural ordering of the Cardinality enumeration.

Parameters:

locale - the locale to use for lookup, not null

Returns:

a mapping of cardinalities to example decimal values, not null

Throws:

IllegalArgumentException - if the locale is malformed

getSupportedLocaleTags

public static @NonNull SortedSet<@NonNull String> getSupportedLocaleTags()

Gets the BCP 47 locale tags represented directly in the generated CLDR cardinality-rule data.

This is not an exhaustive list of concrete locale tags accepted by cardinality operations. A locale with additional region or script subtags may be supported through fallback to a less-specific rule tag. Use supportedCardinalitiesForLocale(Locale) to check a concrete locale.

The set's values are sorted by natural string ordering.

Returns:

the BCP 47 locale tags represented directly in the generated CLDR cardinality-rule data, not null

Since:

3.0.0