NSRange

Inherits from:
Object

Implements:
Cloneable
Serializable

Package:
com.webobjects.foundation

Class Description

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.

Table 0-12 describes the NSRange methods that 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.

**Table 0-12 NSRange's Base API**
Method	Description
length	Returns the length of the receiver from its starting location.
location	Returns the starting location of the receiver.

Constants

NSRange provides the following constant as a convenience; you can use it to compare values returned by some NSRange methods:

Constant	Type	Description
`ZeroRange`	NSRange	An NSRange set to zero in location and length.

Interfaces Implemented

Cloneable

clone

Method Types

Constructors

NSRange

Accessing range elements

length
location

Manipulating ranges

rangeByIntersectingRange
rangeByUnioningRange
subtractRange

Testing ranges

containsLocation
intersectsRange
isEmpty
isEqualToRange
isSubrangeOfRange
locationInRange
maxRange

Methods inherited from Object

equals
hashCode
toString

Converting Strings to NSRanges

fromString

Constructors

NSRange

public NSRange()

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

public NSRange(NSRange aRange)

Creates a new NSRange with the location and length values of aRange.

public NSRange( int location, int length)

Creates a new NSRange with the range elements of location and length. Throws an IllegalArgumentException if either integer is negative.

Static Methods

fromString

public static NSRange fromString(String rangeAsString)

Creates an NSRange from the string rangeAsString. The string must be of the form "{loc,len}" where loc is a number representing the starting location of the range and len is the range's length. Throws an IllegalArgumentException if the string is improperly formatted.

See Also: toString

Instance Methods

clone

public Object clone()

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

containsLocation

public boolean containsLocation(int aLocation)

Returns whether the location aLocation falls within the limits specified by the receiver.

See Also: intersectsRange, location

equals

public boolean equals(Object otherObject)

Returns whether otherObject is an NSRange and is equal in location and length to the receiver.

See Also: isEqualToRange, isSubrangeOfRange

hashCode

public int hashCode()

Provide an appropriate hash code useful for storing the receiver in a hash-based data structure.

intersectsRange

public boolean intersectsRange(NSRange aRange)

Returns whether the range aRange intersects the receiver.

See Also: rangeByIntersectingRange

isEmpty

public boolean isEmpty()

Returns whether the length of the receiver is zero.

See Also: maxRange

isEqualToRange

public boolean isEqualToRange(NSRange aRange)

Returns whether the range aRange is equal in both location and length to the receiver.

See Also: equals, isSubrangeOfRange

isSubrangeOfRange

public boolean isSubrangeOfRange(NSRange aRange)

Returns whether the receiver's end points match or fall within those of range aRange.

See Also: intersectsRange

length

public int length()

Returns the length of the receiver from its starting location.

See Also: location

location

public int location()

Returns the starting location of the receiver.

See Also: length

locationInRange

public boolean locationInRange(int aLocation)

This method is deprecated. Use containsLocation instead.

maxRange

public int maxRange()

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

See Also: isEmpty, length, location

rangeByIntersectingRange

public NSRange rangeByIntersectingRange(NSRange aRange)

Returns an NSRange that is the intersection of aRange and the receiver. If the ranges do not intersect, returns an empty range (see isEmpty).

See Also: rangeByUnioningRange, subtractRange

rangeByUnioningRange

public NSRange rangeByUnioningRange(NSRange aRange)

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

See Also: rangeByIntersectingRange, subtractRange

subtractRange

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

Returns the ranges resulting from the subtraction of otherRange from the receiver by modifying the mutable ranges resultRange1 and resultRange2 (provided by the caller). Either or both of the the result ranges might be empty when this method returns.

toString

public String toString()

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

See Also: fromString