Package com.google.mu.util

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