Documentation Archive Developer
Search
PATH Documentation > WebObjects

Table of Contents

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.

See Also: rangeByIntersectingRange, rangeByUnioningRange



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



© 2001 Apple Computer, Inc. (Last Published April 17, 2001)


Table of Contents