WebObjects 5.2

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
MethodDescription
lengthreturns the length of this NSRange from its starting location
locationreturns 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.
Overrides:
clone in class Object
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.
Overrides:
equals in class Object
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.
Overrides:
hashCode in class Object
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.
Overrides:
toString in class Object
Returns:
string corresponding this NSRange
See Also:
fromString(java.lang.String)

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.