NSIndexSet Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in OS X v10.3 and later. |
| Companion guide | |
| Declared in | NSIndexSet.h |
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.
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: initWithIndexesInRange: and initWithIndexSet:.
You must not subclass the NSIndexSet class.
The mutable subclass of NSIndexSet is NSMutableIndexSet.
Tasks
Creating Index Sets
-
+ indexSet -
+ indexSetWithIndex: -
+ indexSetWithIndexesInRange: -
– init -
– initWithIndex: -
– initWithIndexesInRange: -
– initWithIndexSet:
Querying Index Sets
-
– containsIndex: -
– containsIndexes: -
– containsIndexesInRange: -
– intersectsIndexesInRange: -
– count -
– countOfIndexesInRange: -
– indexPassingTest: -
– indexesPassingTest: -
– indexWithOptions:passingTest: -
– indexesWithOptions:passingTest: -
– indexInRange:options:passingTest: -
– indexesInRange:options:passingTest:
Enumerating Index Set Content
-
– enumerateRangesInRange:options:usingBlock: -
– enumerateRangesUsingBlock: -
– enumerateRangesWithOptions:usingBlock:
Comparing Index Sets
Getting Indexes
-
– firstIndex -
– lastIndex -
– indexLessThanIndex: -
– indexLessThanOrEqualToIndex: -
– indexGreaterThanOrEqualToIndex: -
– indexGreaterThanIndex: -
– getIndexes:maxCount:inIndexRange:
Enumerating Indexes
Class Methods
indexSet
Creates an empty index set.
Return Value
NSIndexSet object with no members.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hindexSetWithIndex:
Creates an index set with an index.
Parameters
- index
An index.
Return Value
NSIndexSet object containing index.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hindexSetWithIndexesInRange:
Creates an index set with an index range.
Parameters
- indexRange
An index range.
Return Value
NSIndexSet object containing indexRange.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hInstance Methods
containsIndex:
Indicates whether the index set contains a specific index.
Parameters
- index
Index being inquired about.
Return Value
YES when the index set contains index, NO otherwise.
Availability
- Available in OS X v10.3 and later.
Declared In
NSIndexSet.hcontainsIndexes:
Indicates whether the receiving index set contains a superset of the indexes in another index set.
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 OS X v10.3 and later.
Declared In
NSIndexSet.hcontainsIndexesInRange:
Indicates whether the index set contains the indexes represented by an index range.
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 OS X v10.3 and later.
Declared In
NSIndexSet.hcount
Returns the number of indexes in the index set.
Return Value
Number of indexes in the index set.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hcountOfIndexesInRange:
Returns the number of indexes in the index set that are members of a given range.
Parameters
- indexRange
Index range being inquired about.
Return Value
Number of indexes in the index set that are members of indexRange.
Availability
- Available in OS X v10.5 and later.
See Also
Declared In
NSIndexSet.henumerateIndexesInRange:options:usingBlock:
Executes a given Block using the indexes in the specified range, using the specified enumeration options.
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
NSEnumerationOptionsfor 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
YESto stop further processing of the set. Thestopargument is an out-only argument. You should only ever set this Boolean to YES within the Block.
Availability
- Available in OS X v10.6 and later.
Declared In
NSIndexSet.henumerateIndexesUsingBlock:
Executes a given Block using each object in the index set.
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
YESto stop further processing of the set. Thestopargument is an out-only argument. You should only ever set this Boolean to YES within the Block.
Availability
- Available in OS X v10.6 and later.
Declared In
NSIndexSet.henumerateIndexesWithOptions:usingBlock:
Executes a given Block over the index set’s indexes, using the specified enumeration options.
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
NSEnumerationOptionsfor 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
YESto stop further processing of the set. Thestopargument is an out-only argument. You should only ever set this Boolean to YES within the Block.
Availability
- Available in OS X v10.6 and later.
Declared In
NSIndexSet.henumerateRangesInRange:options:usingBlock:
Enumerates over the ranges in the range of objects using the 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
NSEnumerationOptionsfor 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
YESto stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean toYESwithin 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.
Availability
- Available in OS X v10.7 and later.
Declared In
NSIndexSet.henumerateRangesUsingBlock:
Executes a given block using each object in the index set, in the specified ranges.
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
YESto stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean toYESwithin the Block.
Discussion
If the Block parameter is nil this method will raise an exception.
Availability
- Available in OS X v10.7 and later.
Declared In
NSIndexSet.henumerateRangesWithOptions:usingBlock:
Executes a given block using each object in the index set, in the specified ranges.
Parameters
- opts
A bitmask that specifies the
NSEnumerationOptionsfor 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
YESto stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean toYESwithin 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.
Availability
- Available in OS X v10.7 and later.
Declared In
NSIndexSet.hfirstIndex
Returns either the first index in the index set or the not-found indicator.
Return Value
First index in the index set or NSNotFound when the index set is empty.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hgetIndexes: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.
Parameters
- indexBuffer
Index buffer to fill.
- bufferSize
Maximum size of indexBuffer.
- indexRange
Index range to compare with indexes in the index set;
nilrepresents 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 OS X v10.3 and later.
Declared In
NSIndexSet.hindexesInRange:options:passingTest:
Returns an NSIndexSet containing the receiving index set’s objects in the specified range that pass the Block test.
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
NSEnumerationOptionsfor 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
YESto stop further processing of the set. Thestopargument 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 OS X v10.6 and later.
Declared In
NSIndexSet.hindexesPassingTest:
Returns an NSIndexSet containing the receiving index set’s objects that pass the Block test.
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
YESto stop further processing of the set. Thestopargument 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 OS X v10.6 and later.
Declared In
NSIndexSet.hindexesWithOptions:passingTest:
Returns an NSIndexSet containing the receiving index set’s objects that pass the Block test using the specified enumeration options.
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
NSEnumerationOptionsfor 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
YESto stop further processing of the set. Thestopargument 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 OS X v10.6 and later.
Declared In
NSIndexSet.hindexGreaterThanIndex:
Returns either the closest index in the index set that is greater than a specific index or the not-found indicator.
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 OS X v10.3 and later.
Declared In
NSIndexSet.hindexGreaterThanOrEqualToIndex:
Returns either the closest index in the index set that is greater than or equal to a specific index or the not-found indicator.
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 OS X v10.3 and later.
Declared In
NSIndexSet.hindexInRange:options:passingTest:
Returns the index of the first object in the specified range that passes the predicate Block test.
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
NSEnumerationOptionsfor 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
YESto stop further processing of the set. Thestopargument 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 OS X v10.6 and later.
Declared In
NSIndexSet.hindexLessThanIndex:
Returns either the closest index in the index set that is less than a specific index or the not-found indicator.
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 OS X v10.3 and later.
Declared In
NSIndexSet.hindexLessThanOrEqualToIndex:
Returns either the closest index in the index set that is less than or equal to a specific index or the not-found indicator.
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 OS X v10.3 and later.
Declared In
NSIndexSet.hindexPassingTest:
Returns the index of the first object that passes the predicate Block test.
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
YESto stop further processing of the set. Thestopargument 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 OS X v10.6 and later.
Declared In
NSIndexSet.hindexWithOptions:passingTest:
Returns the index of the first object that passes the predicate Block test using the specified enumeration options.
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
NSEnumerationOptionsfor 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
YESto stop further processing of the set. Thestopargument 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 OS X v10.6 and later.
Declared In
NSIndexSet.hinit
Initializes an allocated NSIndexSet object.
Return Value
Initialized, empty NSIndexSet object.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hinitWithIndex:
Initializes an allocated NSIndexSet object with an index.
Parameters
- index
An index.
Return Value
Initialized NSIndexSet object with index.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hinitWithIndexesInRange:
Initializes an allocated NSIndexSet object with an index range.
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 OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hinitWithIndexSet:
Initializes an allocated NSIndexSet object with an index set.
Parameters
- indexSet
An index set.
Return Value
Initialized NSIndexSet object with indexSet.
Discussion
This method is a designated initializer for NSIndexSet.
Availability
- Available in OS X v10.3 and later.
Declared In
NSIndexSet.hintersectsIndexesInRange:
Indicates whether the index set contains any of the indexes in a range.
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 OS X v10.3 and later.
See Also
Declared In
NSIndexSet.hisEqualToIndexSet:
Indicates whether the indexes in the receiving index set are the same indexes contained in another index set.
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 OS X v10.3 and later.
Declared In
NSIndexSet.hlastIndex
Returns either the last index in the index set or the not-found indicator.
Return Value
Last index in the index set or NSNotFound when the index set is empty.
Availability
- Available in OS X v10.3 and later.
See Also
Declared In
NSIndexSet.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)