Package edu.rit.util

Class LongRange

java.lang.Object
edu.rit.util.LongRange
All Implemented Interfaces:
Externalizable, Serializable
public class LongRange extends Object implements Externalizable
Class LongRange provides a range of type long. 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: 

     LongRange range = new LongRange (0, N-1);
     long lb = range.lb();
     long ub = range.ub();
     for (long 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: 

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

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    LongRange
    chunk(long N1, long N2)
    Slice off a chunk of this range and return the chunk.
    boolean
    contains(long value)
    Determine if this range contains the given value.
    boolean
    contains(LongRange 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.
    long
    lb()
    Returns this range's lower bound.
    long
    length()
    Returns this range's length.
    void
    readExternal(ObjectInput in)
    Read this range from the given object input stream.
    long
    stride()
    Returns this range's stride.
    LongRange
    subrange(int size, int rank)
    Partition this range and return one subrange.
    LongRange[]
    subranges(int size)
    Partition this range and return all the subranges.
    String
    toString()
    Returns a string version of this range.
    long
    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

    • LongRange

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

    • LongRange

      public LongRange(long lb, long 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.

    • LongRange

      public LongRange(long lb, long ub, long 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.

    • LongRange

      public LongRange(LongRange 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 long lb()
      Returns this range's lower bound.
      Returns:
      Lower bound.

    • ub

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

    • stride

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

    • length

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

    • contains

      public boolean contains(long 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(LongRange 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 LongRange 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 LongRange[] 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 LongRange chunk(long N1, long 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.