Package com.lokalized

Enum Class 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 java.lang.Enum

Enum.EnumDesc<E extends Enum<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 SortedMap<Cardinality,Range<BigDecimal>>	exampleDecimalValuesForLocale(Locale locale)	Gets a mapping of cardinalities to example decimal values for the given locale.
static SortedMap<Cardinality,Range<Integer>>	exampleIntegerValuesForLocale(Locale locale)	Gets a mapping of cardinalities to example integer values for the given locale.
static Cardinality	forNumber(Number number, Integer visibleDecimalPlaces, Locale locale)	Gets an appropriate plural cardinality for the given number, visible decimal places, and locale.
static Cardinality	forNumber(Number number, Locale locale)	Gets an appropriate plural cardinality for the given number and locale.
static Cardinality	forRange(Cardinality start, Cardinality end, Locale locale)	Gets an appropriate plural cardinality for the given range (start, end) and locale.
static SortedSet<String>	getSupportedLanguageCodes()	Gets the ISO 639 language codes for which cardinality operations are supported.
static SortedSet<Cardinality>	supportedCardinalitiesForLocale(Locale locale)	Gets the set of cardinalities supported for the given locale.
static Cardinality	valueOf(String name)	Returns the enum constant of this class with the specified name.
static Cardinality[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

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

Methods inherited from class java.lang.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 class, in the order they are declared.

Returns:

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

valueOf

public static Cardinality valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (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 class has no constant with the specified name

NullPointerException - if the argument is null

forNumber

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

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

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.

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

forNumber

@Nonnull
public static 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.

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.

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

forRange

@Nonnull
public static 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

supportedCardinalitiesForLocale

@Nonnull
public static SortedSet<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

exampleIntegerValuesForLocale

@Nonnull
public static SortedMap<Cardinality,Range<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

exampleDecimalValuesForLocale

@Nonnull
public static SortedMap<Cardinality,Range<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

getSupportedLanguageCodes

@Nonnull
public static SortedSet<String> getSupportedLanguageCodes()

Gets the ISO 639 language codes for which cardinality operations are supported.

The set's values are ISO 639 codes and therefore sorted using English collation.

Returns:

the ISO 639 language codes for which cardinality operations are supported, not null