Package net.algart.math

Class IRange

java.lang.Object
net.algart.math.IRange
public final class IRange extends Object

Numeric inclusive integer range: a set of long numbers min()<=x<=max(). An advanced analog of org.apache.commons.lang.math.LongRange.

The minimum number (min()) is never greater than the maximum number (max()), both minimal and maximum numbers min() and (max()) are always in range -Long.MAX_VALUE+1..Long.MAX_VALUE-1, and their difference is always less than Long.MAX_VALUE. In other words, "max()-min()+1" expression, returned by size() method, and also "min()-1", "min()-2" and "max()+1" expressions are always calculated without overflow.

Please draw attention to the important effect of the requirement above. If a..b is an allowed range (a=min(), b=max()), then 0..b−a and a−b..0 are also allowed ranges. Really, they have the same difference max()-min()=b−a=diff, and so far as this difference diff<Long.MAX_VALUE, both new bounds b−a=diff and a−b=−diff are also inside the required range -Long.MAX_VALUE+1..Long.MAX_VALUE-1.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:
Daniel Alievsky
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    contains(long value)
    Returns true if and only if min()<=value<=max().
    boolean
    contains(IRange range)
    Returns true if and only if min()<=range.min() and range.max()<=max().
    long
    cut(long value)
    Returns value<min()?min():value>max()?max():value.
    boolean
    equals(Object obj)
    Indicates whether some other range is equal to this instance.
    IRange
    expand(long value)
    Returns an instance of this class describing the range Math.min(this.min(),value) <= x <= Math.max(this.max(),value).
    int
    hashCode()
    Returns the hash code of this range.
    boolean
    intersects(IRange range)
    Returns true if and only if min()<=range.max() and range.min()<=max().
    static boolean
    isAllowedRange(long min, long max)
    Returns true if and only if the arguments min and max are allowed min()/max() bounds for some instance of this class.
    long
    max()
    Returns the maximum number in the range, inclusive.
    long
    min()
    Returns the minimum number in the range, inclusive.
    static IRange
    roundOf(Range range)
    Returns an instance of this class describing the same range as the given real range, with bounds, rounded to the nearest integers.
    long
    size()
    Returns max()-min()+1.
    Range
    toRange()
    Equivalent to Range.valueOf(thisInstance).
    String
    toString()
    Returns a brief string description of this object.
    static IRange
    valueOf(long min, long max)
    Returns an instance of this class describing the range min<=x<=max.
    static IRange
    valueOf(Range range)
    Returns an instance of this class describing the same range as the given real range, with bounds, truncated to integers by Java typecast (long)doubleValue.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • valueOf

      public static IRange valueOf(long min, long max)
      Returns an instance of this class describing the range min<=x<=max. The min value must not be greater than max, both values must be in range -Long.MAX_VALUE+1..Long.MAX_VALUE-1, and the difference max-min must be less than Long.MAX_VALUE.
      Parameters:
      min - the minimum number in the range, inclusive.
      max - the maximum number in the range, inclusive.
      Returns:
      the new range.
      Throws:
      IllegalArgumentException - if min > max, or if max-min >= Long.MAX_VALUE (more precisely, if the Java expression max-min+1 is nonpositive due to integer overflow), or if min<=-Long.MAX_VALUE, or if max==Long.MAX_VALUE.

    • valueOf

      public static IRange valueOf(Range range)
      Returns an instance of this class describing the same range as the given real range, with bounds, truncated to integers by Java typecast (long)doubleValue. Equivalent to 
      valueOf((long)range.min(), (long)range.max())
      Parameters:
      range - the real range.
      Returns:
      the integer range with same (cast) bounds.
      Throws:
      NullPointerException - if the passed range is null.
      IllegalArgumentException - if the desired range does not match requirements of valueOf(long, long) method.

    • roundOf

      public static IRange roundOf(Range range)
      Returns an instance of this class describing the same range as the given real range, with bounds, rounded to the nearest integers. Equivalent to 
      valueOf(StrictMath.round(range.min()), StrictMath.round(range.max()))
      Parameters:
      range - the real range.
      Returns:
      the integer range with same (rounded) bounds.
      Throws:
      NullPointerException - if the passed range is null.
      IllegalArgumentException - if the desired range does not match requirements of valueOf(long, long) method.

    • isAllowedRange

      public static boolean isAllowedRange(long min, long max)
      Returns true if and only if the arguments min and max are allowed min()/max() bounds for some instance of this class. In other words, this method returns false in the same situations, when valueOf(long min, long max) method, called with the same arguments, throws IllegalArgumentException.

      Equivalent to the following check: 

           min <= max && min > -Long.MAX_VALUE &&
         max != Long.MAX_VALUE && max - min + 1L > 0L
      Parameters:
      min - the minimum number in some range, inclusive.
      max - the maximum number in some range, inclusive.
      Returns:
      whether these bounds are allowed minimum and maximum for some instance of this class.

    • min

      public long min()
      Returns the minimum number in the range, inclusive.
      Returns:
      the minimum number in the range.

    • max

      public long max()
      Returns the maximum number in the range, inclusive.
      Returns:
      the maximum number in the range.

    • size

      public long size()
      Returns max()-min()+1.
      Returns:
      max()-min()+1.

    • cut

      public long cut(long value)
      Returns value<min()?min():value>max()?max():value. In other words, returns the passed number if it is in this range or the nearest range bound in other cases.
      Parameters:
      value - some number.
      Returns:
      the passed number if it is in this range or the nearest range bound in other cases.

    • contains

      public boolean contains(long value)
      Returns true if and only if min()<=value<=max().
      Parameters:
      value - the checked value.
      Returns:
      true if the value is in this range.

    • contains

      public boolean contains(IRange range)
      Returns true if and only if min()<=range.min() and range.max()<=max().
      Parameters:
      range - the checked range.
      Returns:
      true if the checked range is a subset of this range.

    • intersects

      public boolean intersects(IRange range)
      Returns true if and only if min()<=range.max() and range.min()<=max().
      Parameters:
      range - the checked range.
      Returns:
      true if the checked range overlaps with this range.

    • expand

      public IRange expand(long value)
      Returns an instance of this class describing the range Math.min(this.min(),value) <= x <= Math.max(this.max(),value). In other words, expands the current range to include the given value.
      Parameters:
      value - some value that should belong to the new range.
      Returns:
      the expanded range.
      Throws:
      IllegalArgumentException - if value==Long.MAX_VALUE, value<=-Long.MAX_VALUE or if in the resulting range max-min >= Long.MAX_VALUE.

    • toRange

      public Range toRange()
      Equivalent to Range.valueOf(thisInstance).
      Returns:
      the equivalent real range.

    • toString

      public String toString()
      Returns a brief string description of this object.

      The result of this method may depend on implementation and usually contains the minimum and maximum numbers in this range.

      Overrides:
      toString in class Object
      Returns:
      a brief string description of this object.

    • hashCode

      public int hashCode()
      Returns the hash code of this range.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this range.

    • equals

      public boolean equals(Object obj)
      Indicates whether some other range is equal to this instance. Returns true if and only if obj instanceof IRange, ((IRange)obj).min()==this.min() and ((IRange)obj).max==this.max.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to be compared for equality with this instance.
      Returns:
      true if the specified object is a range equal to this one.