Package edu.rit.util

Class Range

java.lang.Object
edu.rit.util.Range
All Implemented Interfaces:
Externalizable, Serializable
public class Range extends Object implements Externalizable
Class Range provides a range of type int. A range object has the following attributes: lower bound L, upper bound U, stride S, and length N. A range object represents the following set of integers: {L, L+S, L+2*S, . . . , L+(N-1)*S}, where U = L+(N-1)*S.

You construct a range object by specifying the lower bound, upper bound, and stride. If the stride is omitted, the default stride is 1. The length is determined automatically. If the lower bound is greater than the upper bound, the range's length is 0 (an empty range).

You can use a range object to control a for loop like this: 

     Range range = new Range (0, N-1);
     int lb = range.lb();
     int ub = range.ub();
     for (int i = lb; i <= ub; ++ i)
         . . .
Note that the range is from lb() to ub() inclusive, so the appropriate test in the for loop is i <= ub. Also note that it usually reduces the running time to call ub() once, store the result in a local variable, and use the local variable in the for loop test, than to call ub() directly in the for loop test.

You can use a range object with a stride greater than 1 to control a for loop like this: 

     Range range = new Range (0, N-1, 2);
     int lb = range.lb();
     int ub = range.ub();
     int stride = range.stride();
     for (int i = lb; i <= ub; i += stride)
         . . .
Version:
30-May-2007
Author:
Alan Kaminsky
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Range()
    Construct a new range object representing an empty range.
    Range(int lb, int ub)
    Construct a new range object with the given lower bound and upper bound.
    Range(int lb, int ub, int stride)
    Construct a new range object with the given lower bound, upper bound, and stride.
    Range(Range range)
    Construct a new range object that is a copy of the given range object.

  • Method Summary

    Modifier and Type
    Method
    Description
    Range
    chunk(int N1, int N2)
    Slice off a chunk of this range and return the chunk.
    boolean
    contains(int value)
    Determine if this range contains the given value.
    boolean
    contains(Range range)
    Determine if this range contains the given range.
    boolean
    equals(Object obj)
    Determine if this range is equal to the given object.
    int
    hashCode()
    Returns a hash code for this range.
    int
    lb()
    Returns this range's lower bound.
    int
    length()
    Returns this range's length.
    void
    readExternal(ObjectInput in)
    Read this range from the given object input stream.
    int
    stride()
    Returns this range's stride.
    Range
    subrange(int size, int rank)
    Partition this range and return one subrange.
    Range[]
    subranges(int size)
    Partition this range and return all the subranges.
    String
    toString()
    Returns a string version of this range.
    int
    ub()
    Returns this range's upper bound.
    void
    writeExternal(ObjectOutput out)
    Write this range to the given object output stream.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Range

      public Range()
      Construct a new range object representing an empty range.

    • Range

      public Range(int lb, int ub)
      Construct a new range object with the given lower bound and upper bound. The stride is 1. The range object represents the following set of integers: {L, L+1, L+2, . . . , U}. The range's length N is U-L+1.

      Note: L > U is allowed and stands for an empty range.

      Parameters:
      lb - Lower bound L.
      ub - Upper bound U.

    • Range

      public Range(int lb, int ub, int stride)
      Construct a new range object with the given lower bound, upper bound, and stride. The stride must be greater than or equal to 1. The range object represents the following set of integers: {L, L+S, L+2*S, . . . , L+(N-1)*S}, where the range's length N is such that L+(N-1)*S is the largest integer less than or equal to U. Note that the actual upper bound of the range, L+(N-1)*S, may not be the same as U.

      Note: L > U is allowed and stands for an empty range.

      Parameters:
      lb - Lower bound L.
      ub - Upper bound U.
      stride - Stride S >= 1.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if S < 1.

    • Range

      public Range(Range range)
      Construct a new range object that is a copy of the given range object.
      Parameters:
      range - Range object to copy.

  • Method Details

    • lb

      public int lb()
      Returns this range's lower bound.
      Returns:
      Lower bound.

    • ub

      public int ub()
      Returns this range's upper bound.
      Returns:
      Upper bound.

    • stride

      public int stride()
      Returns this range's stride.
      Returns:
      Stride.

    • length

      public int length()
      Returns this range's length.
      Returns:
      Length.

    • contains

      public boolean contains(int value)
      Determine if this range contains the given value. This range contains the given value if this.lb() <= val <= this.ub(). (The stride does not affect the outcome.)
      Parameters:
      value - Value to test.
      Returns:
      True if this range contains the given value, false otherwise.

    • contains

      public boolean contains(Range range)
      Determine if this range contains the given range. This range contains the given range if this.lb() <= range.lb() and range.ub() <= this.ub(). (The strides do not affect the outcome.)
      Parameters:
      range - Range to test.
      Returns:
      True if this range contains the given range, false otherwise.

    • subrange

      public Range subrange(int size, int rank)
      Partition this range and return one subrange. This range is split up into subranges; the size argument specifies the number of subranges. This range is divided as equally as possible among the subranges; the lengths of the subranges differ by at most 1. The subranges are numbered 0, 1, . . . size-1. This method returns the subrange whose number is rank.

      Note that if size is greater than the length of this range, the returned subrange may be empty.

      Parameters:
      size - Number of subranges, size >= 1.
      rank - Rank of the desired subrange, 0 <= rank < size.
      Returns:
      Subrange.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if size or rank is out of bounds.

    • subranges

      public Range[] subranges(int size)
      Partition this range and return all the subranges. This range is split up into subranges; the size argument specifies the number of subranges. This range is divided as equally as possible among the subranges; the lengths of the subranges differ by at most 1. The subranges are returned in an array with indexes 0, 1, . . . size-1.

      Note that if size is greater than the length of this range, some of the returned subranges may be empty.

      Parameters:
      size - Number of subranges, size >= 1.
      Returns:
      Array of subranges.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if size is out of bounds.

    • chunk

      public Range chunk(int N1, int N2)
      Slice off a chunk of this range and return the chunk. Considering this range as a set of integers from the lower bound to the upper bound, the first N1 integers are sliced off and discarded, then the next N2 integers are sliced off to form a chunk, and the chunk is returned. If after removing the first N1 integers there are fewer than N2 integers left, a chunk consisting of all the remaining integers is returned; this may be an empty chunk.
      Parameters:
      N1 - Number of integers to discard (must be >= 0).
      N2 - Number of integers to include in the chunk (must be >= 0).
      Returns:
      Chunk.
      Throws:
      IllegalArgumentException - (unchecked exception) Thrown if N1 or N2 is out of bounds.

    • equals

      public boolean equals(Object obj)
      Determine if this range is equal to the given object. Two ranges are equal if they both have the same lower bound, stride, and length.
      Overrides:
      equals in class Object

    • hashCode

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

    • toString

      public String toString()
      Returns a string version of this range. If the stride is 1, the format is "L..U", where L is the lower bound and U is the upper bound. If the stride is greater than 1, the format is "L..U;S", where L is the lower bound, U is the upper bound, and S is the stride.
      Overrides:
      toString in class Object
      Returns:
      a String object.

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Write this range to the given object output stream.
      Specified by:
      writeExternal in interface Externalizable
      Throws:
      IOException - Thrown if an I/O error occurred.

    • readExternal

      public void readExternal(ObjectInput in) throws IOException
      Read this range from the given object input stream.
      Specified by:
      readExternal in interface Externalizable
      Throws:
      IOException - Thrown if an I/O error occurred.