* 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) * . . . ** * @author Alan Kaminsky * @version 30-May-2007 */ public class LongRange implements Externalizable { // Hidden data members. private static final long serialVersionUID = 9196521188817114486L; long lb; long stride; long length; long ub; // Exported constructors. /** * Construct a new range object representing an empty range. */ public LongRange() { this.lb = 0; this.stride = 1; this.length = 0; setUb(); } /** * 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. * * @param lb Lower bound L. * @param ub Upper bound U. */ public LongRange (long lb, long ub) { this.lb = lb; this.stride = 1; this.length = Math.max (ub-lb+1, 0); setUb(); } /** * 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. * * @param lb Lower bound L. * @param ub Upper bound U. * @param stride Stride S >= 1. * * @exception IllegalArgumentException * (unchecked exception) Thrown if S < 1. */ public LongRange (long lb, long ub, long stride) { if (stride < 1) { throw new IllegalArgumentException ("LongRange(): stride = " + stride + " illegal"); } this.lb = lb; this.stride = stride; this.length = Math.max ((ub-lb+stride)/stride, 0); setUb(); } /** * Construct a new range object that is a copy of the given range object. * * @param range Range object to copy. */ public LongRange (LongRange range) { this.lb = range.lb; this.stride = range.stride; this.length = range.length; this.ub = range.ub; } // Exported operations. /** * Returns this range's lower bound. * * @return Lower bound. */ public long lb() { return lb; } /** * Returns this range's upper bound. * * @return Upper bound. */ public long ub() { return ub; } /** * Returns this range's stride. * * @return Stride. */ public long stride() { return stride; } /** * Returns this range's length. * * @return Length. */ public long length() { return length; } /** * 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.) * * @param value Value to test. * * @return True if this range contains the given value, false * otherwise. */ public boolean contains (long value) { return this.lb <= value && value <= this.ub; } /** * 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.) * * @param range Range to test. * * @return True if this range contains the given range, false * otherwise. */ public boolean contains (LongRange range) { return this.lb <= range.lb && range.ub <= this.ub; } /** * 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. * * @param size Number of subranges, size >= 1. * @param rank Rank of the desired subrange, 0 <= rank < * size. * * @return Subrange. * * @exception IllegalArgumentException * (unchecked exception) Thrown if size or rank is out * of bounds. */ public LongRange subrange (int size, int rank) { // Verify preconditions. if (size < 1) { throw new IllegalArgumentException ("LongRange.subrange(): size = " + size + " illegal"); } if (0 > rank || rank >= size) { throw new IllegalArgumentException ("LongRange.subrange(): rank = " + rank + " illegal"); } // Split this range. LongRange result = new LongRange(); long sublen = this.length / size; int subrem = (int) (this.length % size); if (rank < subrem) { ++ sublen; result.lb = this.lb + (rank * sublen) * this.stride; } else { result.lb = this.lb + (subrem + rank * sublen) * this.stride; } result.stride = this.stride; result.length = sublen; result.setUb(); return result; } /** * 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.
*
* @param size Number of subranges, size >= 1.
*
* @return Array of subranges.
*
* @exception IllegalArgumentException
* (unchecked exception) Thrown if size is out of bounds.
*/
public LongRange[] subranges
(int size)
{
// Verify preconditions.
if (size < 1)
{
throw new IllegalArgumentException
("LongRange.subranges(): size = " + size + " illegal");
}
// Allocate storage for subranges.
LongRange[] result = new LongRange [size];
// Compute subranges.
long sublen = this.length / size;
int subrem = (int) (this.length % size);
long x = this.lb;
++ sublen;
for (int i = 0; i < subrem; ++ i)
{
LongRange result_i = new LongRange();
result_i.lb = x;
x += sublen * this.stride;
result_i.stride = this.stride;
result_i.length = sublen;
result_i.setUb();
result[i] = result_i;
}
-- sublen;
for (int i = subrem; i < size; ++ i)
{
LongRange result_i = new LongRange();
result_i.lb = x;
x += sublen * this.stride;
result_i.stride = this.stride;
result_i.length = sublen;
result_i.setUb();
result[i] = result_i;
}
return result;
}
/**
* 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.
*
* @param N1 Number of integers to discard (must be >= 0).
* @param N2 Number of integers to include in the chunk (must be >= 0).
*
* @return Chunk.
*
* @exception IllegalArgumentException
* (unchecked exception) Thrown if N1 or N2 is out of
* bounds.
*/
public LongRange chunk
(long N1,
long N2)
{
// Verify preconditions.
if (N1 < 0)
{
throw new IllegalArgumentException
("LongRange.chunk(): N1 = " + N1 + " illegal");
}
if (N2 < 0)
{
throw new IllegalArgumentException
("LongRange.chunk(): N2 = " + N2 + " illegal");
}
LongRange result = new LongRange();
result.lb = this.lb + N1 * this.stride;
result.stride = this.stride;
result.length = Math.min (N2, Math.max (0, this.length - N1));
result.setUb();
return result;
}
/**
* 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.
*
* @param obj Object to test.
*
* @return True if this range is equal to obj, false otherwise.
*/
public boolean equals
(Object obj)
{
return
obj instanceof LongRange &&
this.lb == ((LongRange) obj).lb &&
this.stride == ((LongRange) obj).stride &&
this.length == ((LongRange) obj).length;
}
/**
* Returns a hash code for this range.
*/
public int hashCode()
{
return (int) ((((this.lb << 10) + this.stride) << 10) + this.length);
}
/**
* 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.
*/
public String toString()
{
StringBuilder b = new StringBuilder();
b.append (lb);
b.append ("..");
b.append (ub);
if (stride > 1)
{
b.append (';');
b.append (stride);
}
return b.toString();
}
/**
* Write this range to the given object output stream.
*
* @param out Object output stream.
*
* @exception IOException
* Thrown if an I/O error occurred.
*/
public void writeExternal
(ObjectOutput out)
throws IOException
{
out.writeLong (lb);
out.writeLong (stride);
out.writeLong (length);
}
/**
* Read this range from the given object input stream.
*
* @param in Object input stream.
*
* @exception IOException
* Thrown if an I/O error occurred.
*/
public void readExternal
(ObjectInput in)
throws IOException
{
lb = in.readLong();
stride = in.readLong();
length = in.readLong();
setUb();
}
// Hidden operations.
/**
* Set the upper bound of this range based on the lower bound, stride, and
* length.
*/
private void setUb()
{
ub = lb + (length - 1) * stride;
}
// Unit test main program.
// /**
// * Unit test main program.
// */
// public static void main
// (String[] args)
// {
// if (args.length != 4)
// {
// System.err.println ("Usage: edu.rit.util.LongRange