NSMutableRange

Inherits from:
NSRange : Object

Implements:
Cloneable

Package:
com.webobjects.foundation

Class Description

An NSMutableRange is an object representing a range that can be changed. A range is a measurement of a segment of something linear, such as a byte stream. You can change an NSMutableRange's two primary values, its location and its length. The methods of NSMutableRange also enable you to alter an NSMutableRange based on its union or intersection with another NSRange object.

The main purpose for NSMutableRange is to provide a way for methods to return range values in an "out" parameter. A client creates and passes in one or more NSMutableRanges to a method and gets back changed objects when the method returns. NSMutableRanges are also useful for performance reasons; instead of creating multiple NSRanges in a loop, you can create just one NSMutableRange and reuse it.

Table 0-10 describes the NSMutableRange methods that provide the basis for all NSMutableRange's other methods; that is, all other methods are implemented in terms of these four. If you create a subclass of NSMutableRange, 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-10 NSMutableRange's Base API**
Method	Description
location	Returns the starting location of the receiver. Inherited from NSRange.
length	Returns the length of the receiver from its starting location. Inherited from NSRange.
setLength	Sets the length of the receiver.
setLocation	Sets the starting location of the receiver.

Interfaces Implemented

Cloneable

clone

Method Types

Constructors

NSMutableRange

Accessing and setting range elements

setLength
setLocation

Transforming ranges

intersectRange
unionRange

Methods inherited from Object

clone

Constructors

NSMutableRange

public NSMutableRange()

Creates and returns an empty NSMutableRange.

public NSMutableRange(NSRange aRange)

Creates a new NSMutableRange with the location and length values of aRange. This constructor is used in cloning the receiver.

public NSMutableRange( int location, int length)

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

Instance Methods

clone

public Object clone()

Returns a copy (a NSMutableRange object) of the receiver.

intersectRange

public void intersectRange(NSRange aRange)

Changes the receiver to the range resulting from the intersection of aRange and the receiver before the operation. Sets the receiver to an empty range if they do not intersect.

See Also: unionRange

setLength

public void setLength(int newLength)

Sets the length of the receiver to newLength. Throws an IllegalArgumentException if newLength is a negative value.

See Also: setLocation

setLocation

public void setLocation(int newLocation)

Sets the starting location of the receiver to newLocation. Throws an IllegalArgumentException if newLocation is a negative value.

See Also: setLength

unionRange

public void unionRange(NSRange aRange)

Changes the receiver to the range resulting from the union of aRange and the receiver before the operation. This is the lowest starting location and the highest ending location of the two NSRanges.

See Also: intersectRange