---

NSIndexSet Class Reference

Overview

The NSIndexSet class represents an immutable collection of unique unsigned integers, known as indexes because of the way they are used. This collection is referred to as a index set.

You use index sets in your code to store indexes into some other data structure. For example, given an NSArray object, you could use an index set to identify a subset of objects in that array.

Each index value can appear only once in the index set. This is an important concept to understand and is why you would not use index sets to store an arbitrary collection of integer values. To illustrate how this works, if you created an NSIndexSet object with the values 4, 5, 2, and 5, the resulting set would only have the values 4, 5, and 2 in it. Because index values are always maintained in sorted order, the actual order of the values when you created the set would be 2, 4, and then 5.

In most cases, using an index set is more efficient than storing a collection of individual integers. Internally, the NSIndexSet class represents indexes using ranges. For maximum performance and efficiency, overlapping ranges in an index set are automatically coalesced—that is, ranges merge rather than overlap. Thus, the more contiguous the indexes in the set, the fewer ranges are required to specify those indexes.

The designated initializers of the NSIndexSet class are: initWithIndexesInRange: and initWithIndexSet:.

You must not subclass the NSIndexSet class.

The mutable subclass of NSIndexSet is NSMutableIndexSet.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

• – mutableCopyWithZone:

Tasks

Creating Index Sets

• + indexSet
• + indexSetWithIndex:
• + indexSetWithIndexesInRange:
• – init
• – initWithIndex:
• – initWithIndexesInRange:
• – initWithIndexSet:

Querying Index Sets

• – containsIndex:
• – containsIndexes:
• – containsIndexesInRange:
• – intersectsIndexesInRange:
• – count
• – countOfIndexesInRange:

Comparing Index Sets

• – isEqualToIndexSet:

Getting Indexes

• – firstIndex
• – lastIndex
• – indexLessThanIndex:
• – indexLessThanOrEqualToIndex:
• – indexGreaterThanOrEqualToIndex:
• – indexGreaterThanIndex:
• – getIndexes:maxCount:inIndexRange:

Class Methods

indexSet

Creates an empty index set.

+ (id)indexSet

Return Value

NSIndexSet object with no members.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – init

Related Sample Code

• Core Data HTML Store

Declared In

NSIndexSet.h

indexSetWithIndex:

Creates an index set with an index.

+ (id)indexSetWithIndex:(NSUInteger)index

Parameters

index

An index.

Return Value

NSIndexSet object containing index.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – initWithIndex:

Related Sample Code

• AutoSample
• IdentitySample
• PDFKitLinker2

Declared In

NSIndexSet.h

indexSetWithIndexesInRange:

Creates an index set with an index range.

+ (id)indexSetWithIndexesInRange:(NSRange)indexRange

Parameters

indexRange

An index range.

Return Value

NSIndexSet object containing indexRange.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – initWithIndexesInRange:

Related Sample Code

• iSpend

Declared In

NSIndexSet.h

Instance Methods

containsIndex:

Indicates whether the receiver contains a specific index.

- (BOOL)containsIndex:(NSUInteger)index

Parameters

index

Index being inquired about.

Return Value

YES when the receiver contains index, NO otherwise.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – containsIndexes:
• – containsIndexesInRange:

Declared In

NSIndexSet.h

containsIndexes:

Indicates whether the receiver contains a superset of the indexes in another index set.

- (BOOL)containsIndexes:(NSIndexSet *)indexSet

Parameters

indexSet

Index set being inquired about.

Return Value

YES when the receiver contains a superset of the indexes in indexSet, NO otherwise.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – containsIndex:
• – containsIndexesInRange:

Declared In

NSIndexSet.h

containsIndexesInRange:

Indicates whether the receiver contains the indexes represented by an index range.

- (BOOL)containsIndexesInRange:(NSRange)indexRange

Parameters

indexRange

The index range being inquired about.

Return Value

YES when the receiver contains the indexes in indexRange, NO otherwise.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – containsIndex:
• – containsIndexes:
• – intersectsIndexesInRange:

Declared In

NSIndexSet.h

count

Returns the number of indexes in the receiver.

- (NSUInteger)count

Return Value

Number of indexes in the receiver.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – countOfIndexesInRange:

Declared In

NSIndexSet.h

countOfIndexesInRange:

Returns the number of indexes in the receiver that are members of a given range.

- (NSUInteger)countOfIndexesInRange:(NSRange)indexRange

Parameters

indexRange

Index range being inquired about.

Return Value

Number of indexes in the receiver that are members of indexRange.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – count

Declared In

NSIndexSet.h

firstIndex

Returns either the first index in the receiver or the not-found indicator.

- (NSUInteger)firstIndex

Return Value

First index in the receiver or NSNotFound when the receiver is empty.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – lastIndex

Related Sample Code

• AutomatorHandsOn
• iSpend

Declared In

NSIndexSet.h

getIndexes:maxCount:inIndexRange:

The receiver fills an index buffer with the indexes contained both in the receiver and in an index range, returning the number of indexes copied.

- (NSUInteger)getIndexes:(NSUInteger *)indexBuffer maxCount:(NSUInteger)bufferSize inIndexRange:(NSRangePointer)indexRangePointer

Parameters

indexBuffer

Index buffer to fill.

bufferSize

Maximum size of indexBuffer.

indexRange

Index range to compare with indexes in the receiver; nil represents all the indexes in the receiver. Indexes in the index range and in the receiver are copied to indexBuffer. On output, the range of indexes not copied to indexBuffer.

Return Value

Number of indexes placed in indexBuffer.

Discussion

You are responsible for allocating the memory required for indexBuffer and for releasing it later.

Suppose you have an index set with contiguous indexes from 1 to 100. If you use this method to request a range of (1, 100)—which represents the set of indexes 1 through 100—and specify a buffer size of 20, this method returns 20 indexes—1 through 20—in indexBuffer and sets indexRange to (21, 80)—which represents the indexes 21 through 100.

Use this method to retrieve entries quickly and efficiently from an index set. You can call this method repeatedly to retrieve blocks of index values and then process them. When doing so, use the return value and indexRange to determine when you have finished processing the desired indexes. When the return value is less than bufferSize, you have reached the end of the range.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSIndexSet.h

indexGreaterThanIndex:

Returns either the closest index in the receiver that is greater than a specific index or the not-found indicator.

- (NSUInteger)indexGreaterThanIndex:(NSUInteger)index

Parameters

index

Index being inquired about.

Return Value

Closest index in the receiver greater than index; NSNotFound when the receiver contains no qualifying index.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – indexLessThanIndex:
• – indexGreaterThanOrEqualToIndex:
• – indexLessThanOrEqualToIndex:

Related Sample Code

• AutomatorHandsOn
• Core Data HTML Store
• QTKitMovieShuffler

Declared In

NSIndexSet.h

indexGreaterThanOrEqualToIndex:

Returns either the closest index in the receiver that is greater than or equal to a specific index or the not-found indicator.

- (NSUInteger)indexGreaterThanOrEqualToIndex:(NSUInteger)index

Parameters

index

Index being inquired about.

Return Value

Closest index in the receiver greater than or equal to index; NSNotFound when the receiver contains no qualifying index.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – indexGreaterThanIndex:
• – indexLessThanIndex:
• – indexLessThanOrEqualToIndex:

Declared In

NSIndexSet.h

indexLessThanIndex:

Returns either the closest index in the receiver that is less than a specific index or the not-found indicator.

- (NSUInteger)indexLessThanIndex:(NSUInteger)index

Parameters

index

Index being inquired about.

Return Value

Closest index in the receiver less than index; NSNotFound when the receiver contains no qualifying index.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – indexGreaterThanIndex:
• – indexGreaterThanOrEqualToIndex:
• – indexLessThanOrEqualToIndex:

Related Sample Code

• ImageBrowser

Declared In

NSIndexSet.h

indexLessThanOrEqualToIndex:

Returns either the closest index in the receiver that is less than or equal to a specific index or the not-found indicator.

- (NSUInteger)indexLessThanOrEqualToIndex:(NSUInteger)index

Parameters

index

Index being inquired about.

Return Value

Closest index in the receiver less than or equal to index; NSNotFound when the receiver contains no qualifying index.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – indexGreaterThanIndex:
• – indexLessThanIndex:
• – indexGreaterThanOrEqualToIndex:

Declared In

NSIndexSet.h

init

Initializes an allocated NSIndexSet object.

- (id)init

Return Value

Initialized, empty NSIndexSet object.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + indexSet

Declared In

NSIndexSet.h

initWithIndex:

Initializes an allocated NSIndexSet object with an index.

- (id)initWithIndex:(NSUInteger)index

Parameters

index

An index.

Return Value

Initialized NSIndexSet object with index.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + indexSetWithIndex:

Declared In

NSIndexSet.h

initWithIndexesInRange:

Initializes an allocated NSIndexSet object with an index range.

- (id)initWithIndexesInRange:(NSRange)indexRange

Parameters

indexRange

An index range. Must include only indexes representable as unsigned integers.

Return Value

Initialized NSIndexSet object with indexRange.

Discussion

This method raises an NSRangeException when indexRange would add an index that exceeds the maximum allowed value for unsigned integers.

This method is a designated initializer for NSIndexSet.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + indexSetWithIndexesInRange:

Declared In

NSIndexSet.h

initWithIndexSet:

Initializes an allocated NSIndexSet object with an index set.

- (id)initWithIndexSet:(NSIndexSet *)indexSet

Parameters

indexSet

An index set.

Return Value

Initialized NSIndexSet object with indexSet.

Discussion

This method is a designated initializer for NSIndexSet.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSIndexSet.h

intersectsIndexesInRange:

Indicates whether the receiver contains any of the indexes in a range.

- (BOOL)intersectsIndexesInRange:(NSRange)indexRange

Parameters

indexRange

Index range being inquired about.

Return Value

YES when the receiver contains one or more of the indexes in indexRange, NO otherwise.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – containsIndexesInRange:

Declared In

NSIndexSet.h

isEqualToIndexSet:

Indicates whether the indexes in the receiver are the same indeces contained in another index set.

- (BOOL)isEqualToIndexSet:(NSIndexSet *)indexSet

Parameters

indexSet

Index set being inquired about.

Return Value

YES when the indexes in the receiver are the same indexes indexSet contains, NO otherwise.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSIndexSet.h

lastIndex

Returns either the last index in the receiver or the not-found indicator.

- (NSUInteger)lastIndex

Return Value

Last index in the receiver or NSNotFound when the receiver is empty.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – firstIndex

Related Sample Code

• IdentitySample
• iSpend

Declared In

NSIndexSet.h

---