NSIndexSet Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
NSIndexSet.h
Related sample code

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 an index set. Indexes must be in the range 0 .. NSNotFound - 1.

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.

You should not use index sets to store an arbitrary collection of integer values because index sets store indexes as sorted ranges. This makes them more efficient than storing a collection of individual integers. It also means that each index value can only appear once in the index set.

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

You must not subclass the NSIndexSet class.

The mutable subclass of NSIndexSet is NSMutableIndexSet.

Tasks

Creating Index Sets

Querying Index Sets

Enumerating Index Set Content

Comparing Index Sets

Getting Indexes

Enumerating Indexes

Class Methods

indexSet

Creates an empty index set.

+ (instancetype)indexSet
Return Value

NSIndexSet object with no members.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSIndexSet.h

indexSetWithIndex:

Creates an index set with an index.

+ (instancetype)indexSetWithIndex:(NSUInteger)index
Parameters
index

An index. Must be in the range 0 .. NSNotFound - 1.

Return Value

NSIndexSet object containing index.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

indexSetWithIndexesInRange:

Creates an index set with an index range.

+ (instancetype)indexSetWithIndexesInRange:(NSRange)indexRange
Parameters
indexRange

An index range. Must be in the range 0 .. NSNotFound - 1.

Return Value

NSIndexSet object containing indexRange.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSIndexSet.h

Instance Methods

containsIndex:

Indicates whether the index set contains a specific index.

- (BOOL)containsIndex:(NSUInteger)index
Parameters
index

Index being inquired about.

Return Value

YES when the index set contains index, NO otherwise.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSIndexSet.h

containsIndexes:

Indicates whether the receiving index set 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 receiving index set contains a superset of the indexes in indexSet, NO otherwise.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

containsIndexesInRange:

Indicates whether the index set 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 index set contains the indexes in indexRange, NO otherwise.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

count

Returns the number of indexes in the index set.

- (NSUInteger)count
Return Value

Number of indexes in the index set.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

countOfIndexesInRange:

Returns the number of indexes in the index set 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 index set that are members of indexRange.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSIndexSet.h

enumerateIndexesInRange:options:usingBlock:

Executes a given Block using the indexes in the specified range, using the specified enumeration options.

- (void)enumerateIndexesInRange:(NSRange)range options:(NSEnumerationOptions)opts usingBlock:(void (^)(NSUInteger idx, BOOL *stop))block
Parameters
range

The range to enumerate.

opts

A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). See NSEnumerationOptions for the supported values.

block

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion

This method executes synchronously.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

enumerateIndexesUsingBlock:

Executes a given Block using each object in the index set.

- (void)enumerateIndexesUsingBlock:(void (^)(NSUInteger idx, BOOL *stop))block
Parameters
block

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion

This method executes synchronously.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

enumerateIndexesWithOptions:usingBlock:

Executes a given Block over the index set’s indexes, using the specified enumeration options.

- (void)enumerateIndexesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(NSUInteger idx, BOOL *stop))block
Parameters
opts

A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). See NSEnumerationOptions for the supported values.

block

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion

This method executes synchronously.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

enumerateRangesInRange:options:usingBlock:

Enumerates over the ranges in the range of objects using the block

- (void)enumerateRangesInRange:(NSRange)range options:(NSEnumerationOptions)opts usingBlock:(void (^)(NSRange range, BOOL *stop))block
Parameters
range

The range of items to enumerate. If the range intersects a range of the receiver's indexes, then that intersection will be passed to the block.

opts

A bitmask that specifies the NSEnumerationOptions for the enumeration.

block

The block to apply to elements in the index set.

The block takes two arguments:

range

The range of elements.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion

By default, the enumeration starts with the first object and continues serially through the indexed set range to the last object in the range. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

This method executes synchronously.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSIndexSet.h

enumerateRangesUsingBlock:

Executes a given block using each object in the index set, in the specified ranges.

- (void)enumerateRangesUsingBlock:(void (^)(NSRange range, BOOL *stop))block
Parameters
block

The block to apply to elements in the index set.

The block takes two arguments:

range

The range of objects of the elements in the index set.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion

If the Block parameter is nil this method will raise an exception.

This method executes synchronously.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSIndexSet.h

enumerateRangesWithOptions:usingBlock:

Executes a given block using each object in the index set, in the specified ranges.

- (void)enumerateRangesWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(NSRange range, BOOL *stop))block
Parameters
opts

A bitmask that specifies the NSEnumerationOptions for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

block

The block to apply to elements in the index set.

The block takes two arguments:

range

The range of objects of the elements in the index set.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion

By default, the enumeration starts with the first object and continues serially through the indexed set range to the last object in the range. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

This method executes synchronously.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSIndexSet.h

firstIndex

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

- (NSUInteger)firstIndex
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSIndexSet.h

getIndexes:maxCount:inIndexRange:

The index set fills an index buffer with the indexes contained both in the index set 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 index set; nil represents all the indexes in the index set. Indexes in the index range and in the index set 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 iOS 2.0 and later.
Declared In
NSIndexSet.h

indexesInRange:options:passingTest:

Returns an NSIndexSet containing the receiving index set’s objects in the specified range that pass the Block test.

- (NSIndexSet *)indexesInRange:(NSRange)range options:(NSEnumerationOptions)opts passingTest:(BOOL (^)(NSUInteger idx, BOOL *stop))predicate
Parameters
range

The range of indexes to test.

opts

A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). See NSEnumerationOptions for the supported values.

predicate

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

The Block returns a Boolean value that indicates whether obj passed the test.

Return Value

An NSIndexSet containing the indexes of the receiving index set that passed the predicate Block test.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

indexesPassingTest:

Returns an NSIndexSet containing the receiving index set’s objects that pass the Block test.

- (NSIndexSet *)indexesPassingTest:(BOOL (^)(NSUInteger idx, BOOL *stop))predicate
Parameters
predicate

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

The Block returns a Boolean value that indicates whether obj passed the test.

Return Value

An NSIndexSet containing the indexes of the receiving index set that passed the predicate Block test.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

indexesWithOptions:passingTest:

Returns an NSIndexSet containing the receiving index set’s objects that pass the Block test using the specified enumeration options.

- (NSIndexSet *)indexesWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^)(NSUInteger idx, BOOL *stop))predicate
Parameters
opts

A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). See NSEnumerationOptions for the supported values.

predicate

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

The Block returns a Boolean value that indicates whether obj passed the test.

Return Value

An NSIndexSet containing the indexes of the receiving index set that passed the predicate Block test.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

indexGreaterThanIndex:

Returns either the closest index in the index set 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 index set greater than index; NSNotFound when the index set contains no qualifying index.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSIndexSet.h

indexGreaterThanOrEqualToIndex:

Returns either the closest index in the index set 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 index set greater than or equal to index; NSNotFound when the index set contains no qualifying index.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

indexInRange:options:passingTest:

Returns the index of the first object in the specified range that passes the predicate Block test.

- (NSUInteger)indexInRange:(NSRange)range options:(NSEnumerationOptions)opts passingTest:(BOOL (^)(NSUInteger idx, BOOL *stop))predicate
Parameters
range

The range of indexes to test.

opts

A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). See NSEnumerationOptions for the supported values.

predicate

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

The Block returns a Boolean value that indicates whether obj passed the test.

Return Value

The index of the first object that passes the predicate test.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

indexLessThanIndex:

Returns either the closest index in the index set 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 index set less than index; NSNotFound when the index set contains no qualifying index.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

indexLessThanOrEqualToIndex:

Returns either the closest index in the index set 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 index set less than or equal to index; NSNotFound when the index set contains no qualifying index.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

indexPassingTest:

Returns the index of the first object that passes the predicate Block test.

- (NSUInteger)indexPassingTest:(BOOL (^)(NSUInteger idx, BOOL *stop))predicate
Parameters
predicate

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

The Block returns a Boolean value that indicates whether obj passed the test.

Return Value

The index of the first object that passes the predicate test.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

indexWithOptions:passingTest:

Returns the index of the first object that passes the predicate Block test using the specified enumeration options.

- (NSUInteger)indexWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^)(NSUInteger idx, BOOL *stop))predicate
Parameters
opts

A bitmask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order). See NSEnumerationOptions for the supported values.

predicate

The Block to apply to elements in the set.

The Block takes two arguments:

idx

The index of the object.

stop

A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

The Block returns a Boolean value that indicates whether obj passed the test.

Return Value

The index of the first object that passes the predicate test.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSIndexSet.h

init

Initializes an allocated NSIndexSet object.

- (instancetype)init
Return Value

Initialized, empty NSIndexSet object.

Discussion

This method is a designated initializer for NSIndexSet.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSIndexSet.h

initWithIndex:

Initializes an allocated NSIndexSet object with an index.

- (instancetype)initWithIndex:(NSUInteger)index
Parameters
index

An index. Must be in the range 0 .. NSNotFound - 1.

Return Value

Initialized NSIndexSet object with index.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

initWithIndexesInRange:

Initializes an allocated NSIndexSet object with an index range.

- (instancetype)initWithIndexesInRange:(NSRange)indexRange
Parameters
indexRange

An index range. Must be in the range 0 .. NSNotFound - 1..

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 iOS 2.0 and later.
Declared In
NSIndexSet.h

initWithIndexSet:

Initializes an allocated NSIndexSet object with an index set.

- (instancetype)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 iOS 2.0 and later.
Declared In
NSIndexSet.h

intersectsIndexesInRange:

Indicates whether the index set contains any of the indexes in a range.

- (BOOL)intersectsIndexesInRange:(NSRange)indexRange
Parameters
indexRange

Index range being inquired about.

Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

isEqualToIndexSet:

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

- (BOOL)isEqualToIndexSet:(NSIndexSet *)indexSet
Parameters
indexSet

Index set being inquired about.

Return Value

YES when the indexes in the receiving index set are the same indexes indexSet contains, NO otherwise.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h

lastIndex

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

- (NSUInteger)lastIndex
Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSIndexSet.h