Package com.lokalized

Class Range<T>

java.lang.Object
com.lokalized.Range<T>
All Implemented Interfaces:
Iterable<T>, Collection<T>
@Immutable public class Range<T> extends Object implements Collection<T>
Represents a concrete range of values.

This class is not designed to hold large or "infinite" ranges; it is not stream-based. Instead, you might supply a small representative range of values and specify the range is "infinite" if it is understood that the value pattern repeats indefinitely.

For example, you might generate an infinite powers-of-ten range with the 4 values 1, 10, 100, 1_000.

Ranges are constructed via static methods.

Examples:

  • Range.ofFiniteValues("a", "b", "c")
  • Range.ofInfiniteValues(1, 10, 100, 1_000, 10_000)
  • Range.emptyFiniteRange()
  • Range.emptyInfiniteRange()
Author:
Mark Allen

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(T t)
    Deprecated.
    Unsupported operation; this type is immutable.
    boolean
    addAll(Collection<? extends T> c)
    Deprecated.
    Unsupported operation; this type is immutable.
    void
    clear()
    Deprecated.
    Unsupported operation; this type is immutable.
    boolean
    contains(Object value)
    Returns true if this range contains the specified value.
    boolean
    containsAll(Collection<?> c)
    Returns true if this range contains all of the elements of the specified collection.
    static <T> Range<T>
    emptyFiniteRange()
    Gets the empty finite range.
    static <T> Range<T>
    emptyInfiniteRange()
    Gets the empty infinite range.
    boolean
    equals(Object other)
    Checks if this object is equal to another one.
    Boolean
    getInfinite()
    Gets whether this range is infinite.
    List<T>
    getValues()
    Gets the values that comprise this range.
    int
    hashCode()
    A hash code for this object.
    boolean
    isEmpty()
    Returns true if this range contains no elements.
    Iterator<T>
    iterator()
    Returns an iterator over the values in this range in proper sequence.
    static <T> Range<T>
    ofFiniteValues(Collection<T> values)
    Provides a finite range for the given values.
    static <T> Range<T>
    ofFiniteValues(T... values)
    Provides a finite range for the given values.
    static <T> Range<T>
    ofInfiniteValues(Collection<T> values)
    Provides an infinite range for the given values.
    static <T> Range<T>
    ofInfiniteValues(T... values)
    Provides an infinite range for the given values.
    boolean
    remove(Object o)
    Deprecated.
    Unsupported operation; this type is immutable.
    boolean
    removeAll(Collection<?> c)
    Deprecated.
    Unsupported operation; this type is immutable.
    boolean
    retainAll(Collection<?> c)
    Deprecated.
    Unsupported operation; this type is immutable.
    int
    size()
    Returns the number of elements in this range.
    Object[]
    toArray()
    Returns an array containing all of the values in this range in proper sequence (from first to last value).
    <T1> T1[]
    toArray(T1[] a)
    Returns an array containing all of the values in this range in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array.
    String
    toString()
    Generates a String representation of this object.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.util.Collection

    parallelStream, removeIf, spliterator, stream, toArray

    Methods inherited from interface java.lang.Iterable

    forEach

  • Method Details

    • ofInfiniteValues

      @Nonnull public static <T> Range<T> ofInfiniteValues(@Nonnull Collection<T> values)
      Provides an infinite range for the given values.
      Type Parameters:
      T - the type of values contained in the range
      Parameters:
      values - the values of the range, not null
      Returns:
      an infinite range, not null

    • ofInfiniteValues

      @Nonnull public static <T> Range<T> ofInfiniteValues(@Nullable T... values)
      Provides an infinite range for the given values.
      Type Parameters:
      T - the type of values contained in the range
      Parameters:
      values - the values of the range, may be null
      Returns:
      an infinite range, not null

    • ofFiniteValues

      @Nonnull public static <T> Range<T> ofFiniteValues(@Nonnull Collection<T> values)
      Provides a finite range for the given values.
      Type Parameters:
      T - the type of values contained in the range
      Parameters:
      values - the values of the range, not null
      Returns:
      a finite range, not null

    • ofFiniteValues

      @Nonnull public static <T> Range<T> ofFiniteValues(@Nullable T... values)
      Provides a finite range for the given values.
      Type Parameters:
      T - the type of values contained in the range
      Parameters:
      values - the values of the range, may be null
      Returns:
      a finite range, not null

    • emptyFiniteRange

      public static <T> Range<T> emptyFiniteRange()
      Gets the empty finite range.
      Type Parameters:
      T - the type of values contained in the range
      Returns:
      the empty finite range, not null

    • emptyInfiniteRange

      public static <T> Range<T> emptyInfiniteRange()
      Gets the empty infinite range.
      Type Parameters:
      T - the type of values contained in the range
      Returns:
      the empty infinite range, not null

    • size

      public int size()
      Returns the number of elements in this range.
      Specified by:
      size in interface Collection<T>
      Returns:
      the number of elements in this range

    • isEmpty

      public boolean isEmpty()
      Returns true if this range contains no elements.
      Specified by:
      isEmpty in interface Collection<T>
      Returns:
      true if this range contains no elements

    • contains

      public boolean contains(@Nullable Object value)
      Returns true if this range contains the specified value.

      More formally, returns true if and only if this range contains at least one value v such that (o==null ? v==null : o.equals(v)).

      Specified by:
      contains in interface Collection<T>
      Parameters:
      value - value whose presence in this range is to be tested
      Returns:
      true if this range contains the specified value

    • iterator

      @Nonnull public Iterator<T> iterator()
      Returns an iterator over the values in this range in proper sequence.

      The returned iterator is fail-fast.

      Specified by:
      iterator in interface Collection<T>
      Specified by:
      iterator in interface Iterable<T>
      Returns:
      an iterator over the values in this range in proper sequence, not null

    • toArray

      @Nonnull public Object[] toArray()
      Returns an array containing all of the values in this range in proper sequence (from first to last value).

      The returned array will be "safe" in that no references to it are maintained by this range. (In other words, this method must allocate a new array). The caller is thus free to modify the returned array.

      This method acts as bridge between array-based and collection-based APIs.

      Specified by:
      toArray in interface Collection<T>
      Returns:
      an array containing all of the values in this range in proper sequence, not null

    • toArray

      @Nonnull public <T1> T1[] toArray(@Nonnull T1[] a)
      Returns an array containing all of the values in this range in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array. If the range fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this range.

      If the range fits in the specified array with room to spare (i.e., the array has more elements than the range), the element in the array immediately following the end of the collection is set to null. (This is useful in determining the length of the range only if the caller knows that the range does not contain any null elements.)

      Specified by:
      toArray in interface Collection<T>
      Type Parameters:
      T1 - the runtime type of the array to contain the collection
      Parameters:
      a - the array into which the values of the range are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose. not null
      Returns:
      an array containing the values of the range, not null

    • add

      @Deprecated public boolean add(@Nullable T t)
      Deprecated.
      Unsupported operation; this type is immutable.
      Guaranteed to throw an exception and leave the range unmodified.
      Specified by:
      add in interface Collection<T>
      Parameters:
      t - the value to add, ignored
      Returns:
      no return value; this method always throws UnsupportedOperationException
      Throws:
      UnsupportedOperationException - always

    • remove

      @Deprecated public boolean remove(@Nullable Object o)
      Deprecated.
      Unsupported operation; this type is immutable.
      Guaranteed to throw an exception and leave the range unmodified.
      Specified by:
      remove in interface Collection<T>
      Parameters:
      o - the value to remove, ignored
      Returns:
      no return value; this method always throws UnsupportedOperationException
      Throws:
      UnsupportedOperationException - always

    • containsAll

      public boolean containsAll(@Nonnull Collection<?> c)
      Returns true if this range contains all of the elements of the specified collection.
      Specified by:
      containsAll in interface Collection<T>
      Parameters:
      c - collection to be checked for containment in this range, not null
      Returns:
      true if this range contains all of the elements of the specified collection

    • addAll

      @Deprecated public boolean addAll(@Nullable Collection<? extends T> c)
      Deprecated.
      Unsupported operation; this type is immutable.
      Guaranteed to throw an exception and leave the range unmodified.
      Specified by:
      addAll in interface Collection<T>
      Parameters:
      c - collection containing elements to be added to this range, ignored
      Returns:
      no return value; this method always throws UnsupportedOperationException
      Throws:
      UnsupportedOperationException - always

    • removeAll

      @Deprecated public boolean removeAll(@Nullable Collection<?> c)
      Deprecated.
      Unsupported operation; this type is immutable.
      Guaranteed to throw an exception and leave the range unmodified.
      Specified by:
      removeAll in interface Collection<T>
      Parameters:
      c - collection containing elements to be removed from this range, ignored
      Returns:
      no return value; this method always throws UnsupportedOperationException
      Throws:
      UnsupportedOperationException - always

    • retainAll

      public boolean retainAll(@Nullable Collection<?> c)
      Deprecated.
      Unsupported operation; this type is immutable.
      Guaranteed to throw an exception and leave the range unmodified.
      Specified by:
      retainAll in interface Collection<T>
      Parameters:
      c - collection containing elements to be retained in this range, ignored
      Returns:
      no return value; this method always throws UnsupportedOperationException
      Throws:
      UnsupportedOperationException - always

    • clear

      @Deprecated public void clear()
      Deprecated.
      Unsupported operation; this type is immutable.
      Guaranteed to throw an exception and leave the range unmodified.
      Specified by:
      clear in interface Collection<T>
      Throws:
      UnsupportedOperationException - always

    • toString

      @Nonnull public 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.
      Specified by:
      equals in interface Collection<T>
      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.
      Specified by:
      hashCode in interface Collection<T>
      Overrides:
      hashCode in class Object
      Returns:
      a suitable hash code

    • getValues

      @Nonnull public List<T> getValues()
      Gets the values that comprise this range.
      Returns:
      the values that comprise this range, not null

    • getInfinite

      @Nonnull public Boolean getInfinite()
      Gets whether this range is infinite.
      Returns:
      whether this range is infinite - that is, whether the range's pattern repeats indefinitely, not null