Package com.norconex.commons.lang

# Class CircularRange<T>

java.lang.Object
com.norconex.commons.lang.CircularRange<T>

Type Parameters:
  `T` - the range type

All Implemented Interfaces:
  `Serializable`

public final class CircularRange<T> extends Object implements Serializable

A range from a possible set of values that rolls over when defined circular start or end is reached. Because the range is circular, there is no concept of before and after and maximum range can be smaller than minimum. This class is otherwise similar to Apache Commons Lang `Range` class.

Even though this class implements `Serializable`, it makes no guarantee about supplied arguments. If serialization is important to you, make sure supplied arguments are serializable.

Since:
  1.14.0
See Also:
  - Serialized Form

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T extends Comparable<T>>
  CircularRange<T>`
  `between(T fromInclusive, T toInclusive)`
  Obtains a range with the specified minimum and maximum values also serving as circular start and end (all inclusive).
  `static <T> CircularRange<T>`
  `between(T fromInclusive, T toInclusive, Comparator<T> comparator)`
  Obtains a range with the specified minimum and maximum values also serving as circular start and end (all inclusive).
  `static <T extends Comparable<T>>
  CircularRange<T>`
  `between(T circleStartInclusive, T circleEndInclusive, T rangeFromInclusive, T rangeToInclusive)`
  Obtains a range with the specified minimum and maximum values and circular start and end values (all inclusive).
  `static <T> CircularRange<T>`
  `between(T circleStartInclusive, T circleEndInclusive, T rangeFromInclusive, T rangeToInclusive, Comparator<T> comparator)`
  Obtains a range with the specified minimum and maximum values and circular start and end values (all inclusive).
  `boolean`
  `contains(T element)`
  Checks whether the specified element occurs within this range.
  `boolean`
  `containsRange(CircularRange<T> otherRange)`
  Checks whether this range contains all the elements of the specified range.
  `boolean`
  `equals(Object o)`
  `T`
  `getCircleEnd()`
  Gets the end value of this circular range.
  `T`
  `getCircleStart()`
  Gets the start value of this circular range.
  `Comparator<T>`
  `getComparator()`
  Gets the comparator being used to determine if objects are within the range.
  `T`
  `getMaximum()`
  Gets the maximum value in this range.
  `T`
  `getMinimum()`
  Gets the minimum value in this range.
  `int`
  `hashCode()`
  `static <T extends Comparable<T>>
  CircularRange<T>`
  `is(T element)`
  Obtains a range using the specified element as both the minimum and maximum in this range and as both circular start and end.
  `static <T> CircularRange<T>`
  `is(T element, Comparator<T> comparator)`
  Obtains a range using the specified element as both the minimum and maximum in this range and as both circular start and end.
  `boolean`
  `isEndedBy(T element)`
  Checks whether this range ends with the specified element.
  `boolean`
  `isNaturalOrdering()`
  Whether or not the CircularRange is using the natural ordering of the elements.
  `boolean`
  `isOverlappedBy(CircularRange<T> otherRange)`
  Checks whether this range is overlapped by the specified range.
  `boolean`
  `isRolling()`
  Whether or not the range rolls over the circular end.
  `boolean`
  `isStartedBy(T element)`
  Checks whether this range starts with the specified element.
  `String`
  `toString()`
  Gets the range as a `String`.
  `String`
  `toString(String format)`
  Formats the receiver using the given format.
  `CircularRange<T>`
  `withCircularBoundaries(T circleStartInclusive, T circleEndInclusive)`
  Obtains a new range with the specified circular start and end values (both inclusive).
  `CircularRange<T>`
  `withRange(T rangeFromInclusive, T rangeToInclusive)`
  Obtains a new range with the specified minimum and maximum range values (both inclusive).

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### is

    public static <T extends Comparable<T>> CircularRange<T> is(T element)

    Obtains a range using the specified element as both the minimum and maximum in this range and as both circular start and end.

    The range uses the natural ordering of the elements to determine where values lie in the range.

    Type Parameters:
      `T` - the type of the elements in this range
    Parameters:
      `element` - the value to use for this range, not null
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if the element is null
      `ClassCastException` - if the element is not `Comparable`

  - ### is

    public static <T> CircularRange<T> is(T element, Comparator<T> comparator)

    Obtains a range using the specified element as both the minimum and maximum in this range and as both circular start and end.

    The range uses the specified `Comparator` to determine where values lie in the range.

    Type Parameters:
      `T` - the type of the elements in this range
    Parameters:
      `element` - the value to use for this range, must not be `null`
      `comparator` - the comparator to be used, null for natural ordering
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if the element is null
      `ClassCastException` - if using natural ordering and the elements are not `Comparable`

  - ### between

    public static <T extends Comparable<T>> CircularRange<T> between(T fromInclusive, T toInclusive)

    Obtains a range with the specified minimum and maximum values also serving as circular start and end (all inclusive).

    The range uses the natural ordering of the elements to determine where values lie in the range.

    The arguments must be passed in order (min,max).

    Type Parameters:
      `T` - the type of the elements in this range
    Parameters:
      `fromInclusive` - the first value that defines the edge of the range, inclusive
      `toInclusive` - the second value that defines the edge of the range, inclusive
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if either element is null or not in order
      `ClassCastException` - if the elements are not `Comparable`

  - ### between

    public static <T> CircularRange<T> between(T fromInclusive, T toInclusive, Comparator<T> comparator)

    Obtains a range with the specified minimum and maximum values also serving as circular start and end (all inclusive).

    The range uses the specified `Comparator` to determine where values lie in the range.

    The arguments must be passed in order (min,max).

    Type Parameters:
      `T` - the type of the elements in this range
    Parameters:
      `fromInclusive` - the first value that defines the edge of the range, inclusive
      `toInclusive` - the second value that defines the edge of the range, inclusive
      `comparator` - the comparator to be used, null for natural ordering
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if either element is null
      `ClassCastException` - if using natural ordering and the elements are not `Comparable`

  - ### between

    public static <T extends Comparable<T>> CircularRange<T> between(T circleStartInclusive, T circleEndInclusive, T rangeFromInclusive, T rangeToInclusive)

    Obtains a range with the specified minimum and maximum values and circular start and end values (all inclusive).

    The range uses the natural ordering of the elements to determine where values lie in the range.

    The circle arguments must be passed in order (min,max). The range arguments can be passed in any order (min,max or max,min). The order will be respected.

    Type Parameters:
      `T` - the type of the elements in this range
    Parameters:
      `circleStartInclusive` - the value that defines the circular start, inclusive
      `circleEndInclusive` - the value that defines the circular end, inclusive
      `rangeFromInclusive` - the first value that defines the edge of the range, inclusive
      `rangeToInclusive` - the second value that defines the edge of the range, inclusive
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if either element is null or not in order
      `ClassCastException` - if the elements are not `Comparable`

  - ### between

    public static <T> CircularRange<T> between(T circleStartInclusive, T circleEndInclusive, T rangeFromInclusive, T rangeToInclusive, Comparator<T> comparator)

    Obtains a range with the specified minimum and maximum values and circular start and end values (all inclusive).

    The range uses the specified `Comparator` to determine where values lie in the range.

    The circle arguments must be passed in order (min,max). The range arguments can be passed in any order (min,max or max,min). The order will be respected.

    Type Parameters:
      `T` - the type of the elements in this range
    Parameters:
      `circleStartInclusive` - the value that defines the circular start, inclusive
      `circleEndInclusive` - the value that defines the circular end, inclusive
      `rangeFromInclusive` - the first value that defines the edge of the range, inclusive
      `rangeToInclusive` - the second value that defines the edge of the range, inclusive
      `comparator` - the comparator to be used, null for natural ordering
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if either element is null
      `ClassCastException` - if using natural ordering and the elements are not `Comparable`

  - ### withCircularBoundaries

    public CircularRange<T> withCircularBoundaries(T circleStartInclusive, T circleEndInclusive)

    Obtains a new range with the specified circular start and end values (both inclusive). The range values and comparator are the same.

    Parameters:
      `circleStartInclusive` - the value that defines the circular start, inclusive
      `circleEndInclusive` - the value that defines the circular end, inclusive
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if either element is null

  - ### withRange

    public CircularRange<T> withRange(T rangeFromInclusive, T rangeToInclusive)

    Obtains a new range with the specified minimum and maximum range values (both inclusive). The circular start and end are the same.

    Parameters:
      `rangeFromInclusive` - the first value that defines the edge of the range, inclusive
      `rangeToInclusive` - the second value that defines the edge of the range, inclusive
    Returns:
      the range object, not null
    Throws:
      `IllegalArgumentException` - if either element is null

  - ### getMinimum

    public T getMinimum()

    Gets the minimum value in this range.

    Returns:
      the minimum value in this range, not null

  - ### getMaximum

    public T getMaximum()

    Gets the maximum value in this range.

    Returns:
      the maximum value in this range, not null

  - ### getCircleStart

    public T getCircleStart()

    Gets the start value of this circular range.

    Returns:
      the start value of this circular range, not null

  - ### getCircleEnd

    public T getCircleEnd()

    Gets the end value of this circular range.

    Returns:
      the end value of this circular range, not null

  - ### getComparator

    public Comparator<T> getComparator()

    Gets the comparator being used to determine if objects are within the range.

    Natural ordering uses an internal comparator implementation, thus this method never returns null. See `isNaturalOrdering()`.

    Returns:
      the comparator being used, not null

  - ### isNaturalOrdering

    public boolean isNaturalOrdering()

    Whether or not the CircularRange is using the natural ordering of the elements.

    Natural ordering uses an internal comparator implementation, thus this method is the only way to check if a null comparator was specified.

    Returns:
      true if using natural ordering

  - ### isRolling

    public boolean isRolling()

    Whether or not the range rolls over the circular end. Basically, if the range maximum is smaller than the minimum.

    Returns:
      `true` if rolling over

  - ### contains

    public boolean contains(T element)

    Checks whether the specified element occurs within this range.

    Parameters:
      `element` - the element to check for, null returns false
    Returns:
      true if the specified element occurs within this range

  - ### isStartedBy

    public boolean isStartedBy(T element)

    Checks whether this range starts with the specified element.

    Parameters:
      `element` - the element to check for, null returns false
    Returns:
      true if the specified element occurs within this range

  - ### isEndedBy

    public boolean isEndedBy(T element)

    Checks whether this range ends with the specified element.

    Parameters:
      `element` - the element to check for, null returns false
    Returns:
      true if the specified element occurs within this range

  - ### containsRange

    public boolean containsRange(CircularRange<T> otherRange)

    Checks whether this range contains all the elements of the specified range.

    This method may fail if the ranges have two different comparators or element types.

    Parameters:
      `otherRange` - the range to check, null returns false
    Returns:
      true if this range contains the specified range
    Throws:
      `RuntimeException` - if ranges cannot be compared

  - ### isOverlappedBy

    public boolean isOverlappedBy(CircularRange<T> otherRange)

    Checks whether this range is overlapped by the specified range.

    Two ranges overlap if there is at least one element in common.

    This method may fail if the ranges have two different comparators or element types.

    Parameters:
      `otherRange` - the range to test, null returns false
    Returns:
      true if the specified range overlaps with this range; otherwise, `false`
    Throws:
      `RuntimeException` - if ranges cannot be compared

  - ### toString

    public String toString()

    Gets the range as a `String`.

    The format of the String is '[min..max](start..end)'.

    Overrides:
      `toString` in class `Object`
    Returns:
      the `String` representation of this range

  - ### toString

    public String toString(String format)

    Formats the receiver using the given format.

    This uses `Formattable` to perform the formatting. Five variables may be used to embed the minimum, maximum, circular start, circular end and comparator. Use `%1$s` for the minimum element, `%2$s` for the maximum element, `%3$s` for the circular start, `%4$s` for the circular end, and `%5$s` for the comparator. The default format used by `toString()` is `[%1$s..%2$s](%3$s..%4$s)`.

    Parameters:
      `format` - the format string, optionally containing `%1$s`, `%2$s`, `%3$s`, `%4$s` and `%3$s`, not null
    Returns:
      the formatted string, not null

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`