Class Ordinal

java.lang.Object

com.google.mu.util.Ordinal

All Implemented Interfaces:

Comparable<Ordinal>

public final class Ordinal
extends Object
implements Comparable<Ordinal>

This class provides type-safe transition between 1-based Ordinal and 0-based indexes that are commonly used to index arrays and lists. This is useful especially to translate between end-user friendly numbers and machine-friendly index numbers, like for example, to report error messages.

Users should immediately wrap 1-based numbers as Ordinal instances to take advantage of the static type safety, to avoid 1-off errors and to use the extra utilities in this class.

Small ordinal numbers are pre-cached to avoid incurring allocation cost.

Since:

4.6

Field Summary

Fields

Modifier and Type	Field	Description
static final Ordinal	MAX_VALUE	The maximum ordinal.

Method Summary

Modifier and Type	Method	Description
int	compareTo(Ordinal that)	Compares to that according to natural order.
boolean	equals(Object obj)
static Ordinal	first()	Returns the first ordinal.
static Ordinal	fromIndex(int zeroBased)	Returns instance corresponding to the zeroBased index.
int	hashCode()
int	minus(Ordinal that)	Returns the distance between this and that.
static Stream<Ordinal>	natural()	Returns the infinite stream of natural ordinals starting from "1st".
Ordinal	next()	Returns the next ordinal.
static Ordinal	of(int oneBased)	Returns instance corresponding to the oneBased number.
static Ordinal	of(Enum<?> e)	Returns instance corresponding to the ordinal of the Enum object e.
Ordinal	previous()	Returns the previous ordinal.
static Ordinal	second()	Returns the second ordinal.
int	toIndex()	Returns the 0-based index, such that "1st" will map to 0, thus can be used to read and write elements in arrays and lists.
String	toString()	Returns the string representation of this ordinal.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

MAX_VALUE

public static final Ordinal MAX_VALUE

The maximum ordinal.

Since:

7.0

Method Details

first

public static Ordinal first()

Returns the first ordinal.

second

public static Ordinal second()

Returns the second ordinal.

Since:

7.0

natural

public static Stream<Ordinal> natural()

Returns the infinite stream of natural ordinals starting from "1st".

of

public static Ordinal of(int oneBased)

Returns instance corresponding to the oneBased number. Small integer numbers in the range of [1, 100] are cached.

Throws:

IllegalArgumentException - if num is not positive.

of

public static Ordinal of(Enum<?> e)

Returns instance corresponding to the ordinal of the Enum object e.

Note that given Enum.ordinal is 0-based, an enum with ordinal() == 0 maps to first(), or of(1).

Since:

7.0

fromIndex

public static Ordinal fromIndex(int zeroBased)

Returns instance corresponding to the zeroBased index. That is: index 0 corresponds to "1st" and index 1 for "2nd" etc.

Throws:

IllegalArgumentException - if num is negative.

toIndex

public int toIndex()

Returns the 0-based index, such that "1st" will map to 0, thus can be used to read and write elements in arrays and lists.

next

public Ordinal next()

Returns the next ordinal. Overflows to first().

previous

public Ordinal previous()

Returns the previous ordinal. Underflows to MAX_VALUE.

Since:

7.0

minus

public int minus(Ordinal that)

Returns the distance between this and that.

Some examples:

   1st.minus(2nd) => -1
   5th.minus(2nd) => 3
 

Since:

7.0

compareTo

public int compareTo(Ordinal that)

Compares to that according to natural order.

Specified by:

compareTo in interface Comparable<Ordinal>

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Returns the string representation of this ordinal. For example, Ordinal.of(1).toString() returns "1st".

Overrides:

toString in class Object