Class PluralOperands

java.lang.Object

com.lokalized.PluralOperands

@Immutable
public final class PluralOperands
extends Object

Unicode CLDR plural operands for cardinality and ordinality evaluation.

Most applications should use Cardinality.forNumber(Number, java.util.Locale) or Ordinality.forNumber(Number, java.util.Locale). Use this type when the displayed number has details that are not fully represented by the Java Number, such as an explicitly visible decimal count or a compact-decimal exponent.

CLDR plural-category evaluation uses the absolute numeric value exposed by getNumber(). When an instance is used in an alternative expression's ordinary numeric comparison, Lokalized instead preserves the sign of the source number supplied to forNumber(Number).

Supported number implementations are BigDecimal, BigInteger, the boxed JDK numeric types (Byte, Short, Integer, Long, Float, and Double), and the JDK atomic numeric types (AtomicInteger, AtomicLong, LongAdder, DoubleAdder, LongAccumulator, and DoubleAccumulator). Atomic values are sampled once when PluralOperands.Builder.build() executes. Integral values are converted exactly. Float and Double values use their canonical decimal representation rather than the exact binary floating-point value. Non-finite floating-point values and unlisted Number implementations are rejected; callers with another numeric representation should convert it to a BigDecimal explicitly. Builders use TranslationRuntimeLimits.defaults() unless PluralOperands.Builder.runtimeLimits(TranslationRuntimeLimits) supplies different limits. This is also how callers opt up from the defaults to the hard ceilings exposed below.

Since:

3.0.0

Author:

Mark Allen

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	PluralOperands.Builder	Builder for PluralOperands.

Field Summary

Fields

Modifier and Type	Field	Description
static final @NonNull Integer	MAXIMUM_ABSOLUTE_NUMBER_SCALE	Hard ceiling for the absolute BigDecimal.scale() accepted for a number used in plural operands or an alternative-expression numeric literal: 4,096.
static final @NonNull Integer	MAXIMUM_COMPACT_EXPONENT	Hard ceiling for compact-decimal exponents accepted by PluralOperands.Builder.compactExponent(Integer): 4,096.
static final @NonNull Integer	MAXIMUM_NUMBER_PRECISION	Hard precision ceiling for a number used in plural operands or an alternative-expression numeric literal: 4,096.
static final @NonNull Integer	MAXIMUM_VISIBLE_DECIMAL_PLACES	Hard ceiling for explicitly visible decimal places accepted by PluralOperands.Builder.visibleDecimalPlaces(Integer): 4,096.

Method Summary

Modifier and Type	Method	Description
boolean	equals(@Nullable Object other)	Checks if this object is equal to another one.
static @NonNull PluralOperands.Builder	forNumber(@NonNull Number number)	Creates a builder for CLDR plural operands backed by the given number.
@NonNull Integer	getCompactExponent()	Gets the compact-decimal exponent used for the CLDR c and e operands.
@NonNull BigDecimal	getNumber()	Gets the absolute numeric value used for the CLDR n operand.
int	hashCode()	A hash code for this object.
@NonNull String	toString()	Generates a String representation of this object.

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Field Details

MAXIMUM_NUMBER_PRECISION

public static final @NonNull Integer MAXIMUM_NUMBER_PRECISION

Hard precision ceiling for a number used in plural operands or an alternative-expression numeric literal: 4,096.

Since:

3.0.0

MAXIMUM_ABSOLUTE_NUMBER_SCALE

public static final @NonNull Integer MAXIMUM_ABSOLUTE_NUMBER_SCALE

Hard ceiling for the absolute BigDecimal.scale() accepted for a number used in plural operands or an alternative-expression numeric literal: 4,096.

Since:

3.0.0

MAXIMUM_VISIBLE_DECIMAL_PLACES

public static final @NonNull Integer MAXIMUM_VISIBLE_DECIMAL_PLACES

Hard ceiling for explicitly visible decimal places accepted by PluralOperands.Builder.visibleDecimalPlaces(Integer): 4,096.

Since:

3.0.0

MAXIMUM_COMPACT_EXPONENT

public static final @NonNull Integer MAXIMUM_COMPACT_EXPONENT

Hard ceiling for compact-decimal exponents accepted by PluralOperands.Builder.compactExponent(Integer): 4,096.

Since:

3.0.0

Method Details

forNumber

public static @NonNull PluralOperands.Builder forNumber(@NonNull Number number)

Creates a builder for CLDR plural operands backed by the given number.

Negative numbers are evaluated using their absolute value. The supported Number implementations and their conversion semantics are documented by this class.

Parameters:

number - the number that drives pluralization, not null

Returns:

a plural-operands builder, not null

getNumber

public @NonNull BigDecimal getNumber()

Gets the absolute numeric value used for the CLDR n operand.

Returns:

the absolute numeric value, not null

getCompactExponent

public @NonNull Integer getCompactExponent()

Gets the compact-decimal exponent used for the CLDR c and e operands.

Returns:

the compact-decimal exponent, not null

toString

public @NonNull String toString()

Generates a String representation of this object.

Overrides:

toString in class Object

Returns:

a string representation of this object, not null

equals

public boolean equals(@Nullable Object other)

Checks if this object is equal to another one.

Overrides:

equals in class Object

Parameters:

other - the object to check, null returns false

Returns:

true if this is equal to the other object, false otherwise

hashCode

public int hashCode()

A hash code for this object.

Overrides:

hashCode in class Object

Returns:

a suitable hash code