com.webobjects.foundation
Class NSRange

java.lang.Object
  com.webobjects.foundation.NSRange

All Implemented Interfaces:

Cloneable, Serializable

Direct Known Subclasses:

NSMutableRange

public class NSRange

extends Object

implements Serializable, Cloneable

An NSRange represents a range, a measurement of a segment of something linear, such as a byte stream. An NSRange has two primary values, a location and a length. The methods of NSRange give access to these values, convert between NSRanges and their string representations, test and compare ranges, and create ranges based on operations involving the union, intersection, and subtraction of two ranges.

The NSRange methods described below provide the basis for all NSRange's other methods; that is, all other methods are implemented in terms of these two. If you create a subclass of NSRange, you need only ensure that these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly.

NSRange's Base API

Method	Description
length	returns the length of this NSRange from its starting location
location	returns the starting location of this NSRange

See Also:

length(), location(), Serialized Form

Field Summary

static NSRange

ZeroRange An NSRange set to zero in location and length.

Constructor Summary

NSRange()
Creates an NSRange with zero location and length.

NSRange(int location, int length)
Creates a NSRange with the range elements of location and length.

NSRange(NSRange range)
Creates an NSRange with the location and length values of range.

Method Summary

Object	clone() Simply returns this NSRange.
boolean	containsLocation(int location) Indicates whether a location falls within the limits specified by this NSRange.
boolean	equals(Object object) Indicates whether an object is an NSRange whose location and length are equal to this range's location and length.
static NSRange	fromString(String string) Creates an NSRange from a string.
int	hashCode() Provides an appropriate hash code useful for storing this NSRange in a hash-based data structure.
boolean	intersectsRange(NSRange otherRange) Indicates whether the range otherRange intersects this NSRange.
boolean	isEmpty()
boolean	isEqualToRange(NSRange otherRange) Indicates whether the range's location and length are equal to this NSRange's location and length.
boolean	isSubrangeOfRange(NSRange otherRange) Indicates whether this NSRange's end points match or fall within those of another range.
int	length()
int	location()
boolean	locationInRange(int location) Deprecated. Use containsLocation(int)
int	maxRange() Returns the extent of this NSRange (its starting location plus its length).
NSRange	rangeByIntersectingRange(NSRange otherRange) Returns an NSRange that is the intersection of a range and this NSRange.
NSRange	rangeByUnioningRange(NSRange otherRange) Returns an NSRange that is the union of a range and this NSRange (a range constructed from the lowest starting location and the highest ending location of both NSRanges).
void	subtractRange(NSRange otherRange, NSMutableRange resultRange1, NSMutableRange resultRange2) Subtracts a range from this NSRange and stores the result in one or two NSMutableRanges.
String	toString() Returns a string representing this NSRange.

Methods inherited from class java.lang.Object

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

Field Detail

ZeroRange

public static final NSRange ZeroRange

An NSRange set to zero in location and length.

Constructor Detail

NSRange

public NSRange()

Creates an NSRange with zero location and length. For better performance, use the ZeroRange shared instance.

NSRange

public NSRange(int location,
               int length)

Creates a NSRange with the range elements of location and length.

Parameters:

location - location of the current range

length - length of the current range

Throws:

a - java.lang.IllegalArgumentException if either location or length of the range is negative

NSRange

public NSRange(NSRange range)

Creates an NSRange with the location and length values of range.

Parameters:

range - measurement of the linear stream segment

Method Detail

clone

public Object clone()

Simply returns this NSRange. Since NSRange objects are immutable, there's no need to make an actual clone.

Returns:

this NSRange

containsLocation

public boolean containsLocation(int location)

Indicates whether a location falls within the limits specified by this NSRange.

Parameters:

location - location of the linear stream segment

Returns:

true if location is in the range specified by this NSRange

See Also:

intersectsRange(com.webobjects.foundation.NSRange), location()

equals

public boolean equals(Object object)

Indicates whether an object is an NSRange whose location and length are equal to this range's location and length.

Parameters:

object - the range being compared to this NSRange

Returns:

true if the ranges are identical

See Also:

isEqualToRange(com.webobjects.foundation.NSRange), isSubrangeOfRange(com.webobjects.foundation.NSRange)

fromString

public static NSRange fromString(String string)

Creates an NSRange from a string. The string must be of the form "{location,length}" where location is a number representing the starting location of the range and length is the range's length.

Parameters:

string - the range definition; must be in the form "{location,length}"

Returns:

new NSRange object, based on string

Throws:

IllegalArgumentException - string is improperly formatted

See Also:

toString()

hashCode

public int hashCode()

Provides an appropriate hash code useful for storing this NSRange in a hash-based data structure.

Returns:

hash code corresponding to this NSRange

intersectsRange

public boolean intersectsRange(NSRange otherRange)

Indicates whether the range otherRange intersects this NSRange.

Parameters:

otherRange - the range to be compared with this NSRange

Returns:

true if the ranges have anything in common

See Also:

rangeByIntersectingRange(com.webobjects.foundation.NSRange)

isEmpty

public boolean isEmpty()

Returns:

true if this NSRange's length is 0

See Also:

maxRange()

isEqualToRange

public boolean isEqualToRange(NSRange otherRange)

Indicates whether the range's location and length are equal to this NSRange's location and length.

Parameters:

otherRange - range to be compared with this NSRange

Returns:

true if the ranges are equal

See Also:

equals(java.lang.Object), isSubrangeOfRange(com.webobjects.foundation.NSRange)

isSubrangeOfRange

public boolean isSubrangeOfRange(NSRange otherRange)

Indicates whether this NSRange's end points match or fall within those of another range.

Parameters:

otherRange - the range to be compared with this NSRange

Returns:

true if otherRange is a subset of this NSRange

See Also:

intersectsRange(com.webobjects.foundation.NSRange)

length

public int length()

Returns:

Length of this NSRange from its starting position

See Also:

location()

location

public int location()

Returns:

the starting location of this NSRange

See Also:

length()

locationInRange

public boolean locationInRange(int location)

Deprecated. Use containsLocation(int)

Parameters:

location - location of the linear stream segment

Returns:

true if location is in this NSRange

maxRange

public int maxRange()

Returns the extent of this NSRange (its starting location plus its length). This number is one greater than the last location in the range.

Returns:

the total length of this NSRange

See Also:

isEmpty(), length(), location()

rangeByIntersectingRange

public NSRange rangeByIntersectingRange(NSRange otherRange)

Returns an NSRange that is the intersection of a range and this NSRange. If the ranges do not intersect, returns an empty range.

Parameters:

otherRange - range to be compared with this NSRange

Returns:

common range of otherRange and this NSRange

See Also:

rangeByUnioningRange(com.webobjects.foundation.NSRange), subtractRange(com.webobjects.foundation.NSRange, com.webobjects.foundation.NSMutableRange, com.webobjects.foundation.NSMutableRange), isEmpty()

rangeByUnioningRange

public NSRange rangeByUnioningRange(NSRange otherRange)

Returns an NSRange that is the union of a range and this NSRange (a range constructed from the lowest starting location and the highest ending location of both NSRanges).

Parameters:

otherRange - range to be united with this NSRange

Returns:

new range: the sum of this NSRange and otherRange

See Also:

rangeByIntersectingRange(com.webobjects.foundation.NSRange), subtractRange(com.webobjects.foundation.NSRange, com.webobjects.foundation.NSMutableRange, com.webobjects.foundation.NSMutableRange)

subtractRange

public void subtractRange(NSRange otherRange,
                          NSMutableRange resultRange1,
                          NSMutableRange resultRange2)

Subtracts a range from this NSRange and stores the result in one or two NSMutableRanges. Either or both of the the result ranges might be empty when this method finishes.

Parameters:

otherRange - range to be subtracted from this NSRange

resultRange1 - mutable range provided by caller

resultRange2 - mutable range provided by caller

See Also:

rangeByIntersectingRange(com.webobjects.foundation.NSRange), rangeByUnioningRange(com.webobjects.foundation.NSRange)

toString

public String toString()

Returns a string representing this NSRange. The string is in the form "{location,length}" where location is the starting location of the range and length is its length.

Returns:

string corresponding this NSRange

See Also:

fromString(java.lang.String)