Package com.lokalized

Class 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 Detail

      • 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
      • 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
      • 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
      • getValues

        @Nonnull
        public List<TgetValues()
        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