Mac Developer Library

Developer

Foundation Framework Reference NSIndexPath Class Reference

Options
Deployment Target:

On This Page
Language:

NSIndexPath

The NSIndexPath class represents the path to a specific node in a tree of nested array collections. This path is known as an index path.

Each index in an index path represents the index into an array of children from one node in the tree to another, deeper, node. For example, the index path 1.4.3.2 specifies the path shown in Figure 1.

Figure 1Index path 1.4.3.2 image: ../Art/indexpath.gif
  • Creates an one-node index path.

    Declaration

    Objective-C

    + (instancetype)indexPathWithIndex:(NSUInteger)index

    Parameters

    index

    Index of the item in node 0 to point to.

    Return Value

    One-node index path with index.

    Availability

    Available in OS X v10.4 and later.

  • Creates an index path with one or more nodes.

    Declaration

    Objective-C

    + (instancetype)indexPathWithIndexes:(const NSUInteger [])indexes length:(NSUInteger)length

    Parameters

    indexes

    Array of indexes to make up the index path.

    length

    Number of nodes to include in the index path.

    Return Value

    Index path with indexes up to length.

    Availability

    Available in OS X v10.4 and later.

  • Returns an index-path object initialized with the indexes of a specific item and section in a collection view.

    Declaration

    Swift

    init(forItem item: Int, inSection section: Int)

    Objective-C

    + (NSIndexPath *)indexPathForItem:(NSInteger)item inSection:(NSInteger)section

    Parameters

    item

    An index number identifying an item in a UICollectionView object in a section identified by the section parameter.

    section

    An index number identifying a section in a UICollectionView object.

    Return Value

    An NSIndexPath object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.11 and later.

  • Initializes an allocated NSIndexPath object with a one-node index path.

    Declaration

    Swift

    convenience init(index index: Int)

    Objective-C

    - (instancetype)initWithIndex:(NSUInteger)index

    Parameters

    index

    Index of the item in node 0 to point to.

    Return Value

    Initialized NSIndexPath object representing a one-node index path with index.

    Availability

    Available in OS X v10.4 and later.

  • Initializes an allocated NSIndexPath object with an index path of a specific length.

    Declaration

    Swift

    init(indexes indexes: UnsafePointer<Int>, length length: Int)

    Objective-C

    - (instancetype)initWithIndexes:(const NSUInteger [])indexes length:(NSUInteger)length

    Parameters

    indexes

    Array of indexes to make up the index path.

    length

    Number of nodes to include in the index path.

    Return Value

    Initialized NSIndexPath object with indexes up to length.

    Discussion

    This method is a designated initializer of NSIndexPath.

    Availability

    Available in OS X v10.4 and later.

  • - init Available in OS X v10.9 through OS X v10.9

    Initializes an allocated NSIndexPath object.

    Declaration

    Objective-C

    - (instancetype)init

    Return Value

    Initialized NSIndexPath object.

    Discussion

    This method is a designated initializer for NSIndexPath.

    Availability

    Available in OS X v10.9 through OS X v10.9.

  • Provides the index at a particular node in the index path.

    Declaration

    Swift

    func indexAtPosition(_ position: Int) -> Int

    Objective-C

    - (NSUInteger)indexAtPosition:(NSUInteger)node

    Parameters

    node

    Index value of the desired node. Node numbering starts at zero.

    Return Value

    The index value at node or NSNotFound if the node is outside the range of the index path.

    Availability

    Available in OS X v10.4 and later.

  • Provides an index path containing the indexes in the receiving index path and another index.

    Declaration

    Swift

    func indexPathByAddingIndex(_ index: Int) -> NSIndexPath

    Objective-C

    - (NSIndexPath *)indexPathByAddingIndex:(NSUInteger)index

    Parameters

    index

    Index to append to the index path’s indexes.

    Return Value

    New NSIndexPath object containing the receiving index path’s indexes and index.

    Availability

    Available in OS X v10.4 and later.

  • Provides an index path with the indexes in the receiving index path, excluding the last one.

    Declaration

    Swift

    func indexPathByRemovingLastIndex() -> NSIndexPath

    Objective-C

    - (NSIndexPath *)indexPathByRemovingLastIndex

    Return Value

    New index path with the receiving index path’s indexes, excluding the last one.

    Discussion

    Returns an empty NSIndexPath instance if the receiving index path’s length is 1 or less.

    Special Considerations

    On OS X v10.4 this method returns nil when the length of the receiving index path is 1 or less. On iOS and OS X v10.5 and later this method never returns nil.

    Availability

    Available in OS X v10.4 and later.

  • The number of indexes in the index path. (read-only)

    Declaration

    Swift

    var length: Int { get }

    Objective-C

    @property(readonly) NSUInteger length

    Availability

    Available in OS X v10.4 and later.

  • Copies the indexes stored in the index path from the positions specified by the position range into the specified indexes.

    Declaration

    Swift

    func getIndexes(_ indexes: UnsafeMutablePointer<Int>, range positionRange: NSRange)

    Objective-C

    - (void)getIndexes:(NSUInteger *)indexes range:(NSRange)positionRange

    Parameters

    indexes

    Pointer to a C array of at least as many NSUInteger objects as specified by the length of positionRange. On return, the array holds the index path's indexes.

    positionRange

    A range of valid positions within the index path. If the location plus the length of positionRange is greater than the length of the index path, this method raises an NSRangeException.

    Discussion

    It is the developer’s responsibility to allocate the memory for the C array.

    Availability

    Available in OS X v10.9 and later.

  • Copies the objects contained in the index path into indexes.

    Deprecation Statement

    Use getIndexes:range: instead.

    Declaration

    Swift

    func getIndexes(_ indexes: UnsafeMutablePointer<Int>)

    Objective-C

    - (void)getIndexes:(NSUInteger *)indexes

    Parameters

    indexes

    Pointer to a C array of objects of size at least the length of the index path. On return, the index path’s indexes.

    Discussion

    It is the developer’s responsibility to allocate the memory for the C array.

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.11.

  • An index number identifying a section in a table view or collection view. (read-only)

    Declaration

    Swift

    var section: Int { get }

    Objective-C

    @property(readonly) NSInteger section

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.11 and later.

  • item item Property

    An index number identifying an item in a section of a collection view. (read-only)

    Declaration

    Swift

    var item: Int { get }

    Objective-C

    @property(readonly) NSInteger item

    Discussion

    The section the item is in is identified by the value of section.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.11 and later.

  • Indicates the depth-first traversal order of the receiving index path and another index path.

    Declaration

    Swift

    func compare(_ otherObject: NSIndexPath) -> NSComparisonResult

    Objective-C

    - (NSComparisonResult)compare:(NSIndexPath *)indexPath

    Parameters

    indexPath

    Index path to compare.

    This value must not be nil. If the value is nil, the behavior is undefined.

    Return Value

    The depth-first traversal ordering of the receiving index path and indexPath.

    Availability

    Available in OS X v10.4 and later.