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)
         . . .
 

See Also:

Serialized Form

Constructor Summary

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

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 Detail

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 Detail

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

Parameters:

obj - Object to test.

Returns:

True if this range is equal to obj, false otherwise.

hashCode

public int hashCode()

Returns a hash code for this range.

Overrides:

hashCode in class Object

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

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Write this range to the given object output stream.

Specified by:

writeExternal in interface Externalizable

Parameters:

out - Object output stream.

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

Parameters:

in - Object input stream.

Throws:

IOException - Thrown if an I/O error occurred.