Package edu.rit.util
Class LongRange
java.lang.Object
edu.rit.util.LongRange
- All Implemented Interfaces:
Externalizable
,Serializable
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
ConstructorDescriptionConstruct 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.Construct a new range object that is a copy of the given range object. -
Method Summary
Modifier and TypeMethodDescriptionchunk
(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
Determine if this range contains the given range.boolean
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
Read this range from the given object input stream.long
stride()
Returns this range's stride.subrange
(int size, int rank) Partition this range and return one subrange.subranges
(int size) Partition this range and return all the subranges.toString()
Returns a string version of this range.long
ub()
Returns this range's upper bound.void
Write this range to the given object output stream.
-
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
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 ifthis.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
Determine if this range contains the given range. This range contains the given range ifthis.lb()
<=range.lb()
andrange.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
Partition this range and return one subrange. This range is split up into subranges; thesize
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 isrank
.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 ifsize
orrank
is out of bounds.
-
subranges
Partition this range and return all the subranges. This range is split up into subranges; thesize
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 ifsize
is out of bounds.
-
chunk
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 firstN1
integers are sliced off and discarded, then the nextN2
integers are sliced off to form a chunk, and the chunk is returned. If after removing the firstN1
integers there are fewer thanN2
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 ifN1
orN2
is out of bounds.
-
equals
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. -
hashCode
public int hashCode()Returns a hash code for this range. -
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. -
writeExternal
Write this range to the given object output stream.- Specified by:
writeExternal
in interfaceExternalizable
- Throws:
IOException
- Thrown if an I/O error occurred.
-
readExternal
Read this range from the given object input stream.- Specified by:
readExternal
in interfaceExternalizable
- Throws:
IOException
- Thrown if an I/O error occurred.
-