com.webobjects.foundation
Class NSMutableRange

java.lang.Object
  |
  +--com.webobjects.foundation.NSRange
        |
        +--com.webobjects.foundation.NSMutableRange

All Implemented Interfaces:

Cloneable, Serializable

public class NSMutableRange

extends NSRange

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. The two primary values an NSMutableRange can be changed, its location and its length. The methods of NSMutableRange also enables 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, just one NSMutableRange can be created and reuseed.

The NSMutableRange methods that provide the basis for all NSMutableRange's other methods are described below. 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.

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.

See Also:

setLength(int newLength), setLocation(int newLocation), NSRange, NSRange.location(), NSRange.length(), Serialized Form

Fields inherited from class com.webobjects.foundation.NSRange

ZeroRange

Constructor Summary

NSMutableRange()
Creates and returns an empty NSMutableRange.

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

NSMutableRange(NSRange range)
Creates a new NSMutableRange with the location and length values of range.

Method Summary

Object	clone() Simply returns this NSRange.
void	intersectRange(NSRange otherRange) Changes the receiver to the range resulting from the intersection of otherRange and the receiver before the operation.
void	setLength(int length) Sets the length of the receiver to length.
void	setLocation(int location) Sets the starting location of the receiver to location.
void	unionRange(NSRange otherRange) Changes the receiver to the range resulting from the union of otherRange and the receiver before the operation.

Methods inherited from class com.webobjects.foundation.NSRange

containsLocation, equals, fromString, hashCode, intersectsRange, isEmpty, isEqualToRange, isSubrangeOfRange, length, location, locationInRange, maxRange, rangeByIntersectingRange, rangeByUnioningRange, subtractRange, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

NSMutableRange

public NSMutableRange()

Creates and returns an empty NSMutableRange.

NSMutableRange

public NSMutableRange(int location,
                      int length)

Creates a new NSMutableRange with the range elements of location and length.

Parameters:

location - location of the changeable range

length - length of the changeable range

Throws:

IllegalArgumentException - when any of the inputs are negative

NSMutableRange

public NSMutableRange(NSRange range)

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

Parameters:

range - name of the array of range

Method Detail

clone

public Object clone()

Description copied from class: NSRange

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

Overrides:

clone in class NSRange

Returns:

a copy (an NSMutableRange object) of the receiver

intersectRange

public void intersectRange(NSRange otherRange)

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

Parameters:

otherRange - the common range of the current and the receiver ranges

See Also:

unionRange(NSRange aRange)

setLength

public void setLength(int length)

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

Parameters:

length - the input length

Throws:

IllegalArgumentException - if the input is negative

See Also:

setLocation(int location)

setLocation

public void setLocation(int location)

Sets the starting location of the receiver to location.

Parameters:

location - Location of the receiver.

Throws:

IllegalArgumentException - if location is a negative value

See Also:

setLength(int length)

unionRange

public void unionRange(NSRange otherRange)

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

Parameters:

otherRange - sum of the ranges of the current and the receiver range

See Also:

intersectRange(NSRange aRange)