---

NSIndexPath Class Reference

Overview

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.

NSIndexPath objects are uniqued and shared. If an index path containing the specified index or indexes already exists, that object is returned instead of a new instance.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

Tasks

Creating Index Paths

• + indexPathWithIndex:
• + indexPathWithIndexes:length:
• – initWithIndex:
• – initWithIndexes:length:

Querying Index Paths

• – getIndexes:
• – indexAtPosition:
• – indexPathByAddingIndex:
• – indexPathByRemovingLastIndex
• – length

Comparing Index Paths

• – compare:

Class Methods

indexPathWithIndex:

Creates an one-node index path.

+ (id)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 Mac OS X v10.4 and later.

See Also

• – initWithIndex:

Declared In

NSIndexPath.h

indexPathWithIndexes:length:

Creates an index path with one or more nodes.

+ (id)indexPathWithIndexes:(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 Mac OS X v10.4 and later.

See Also

• – initWithIndexes:length:

Declared In

NSIndexPath.h

Instance Methods

compare:

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

- (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 and may change in future versions of Mac OS X.

Return Value

The depth-first traversal ordering of the receiver and indexPath.

• NSOrderedAscending: The receiver comes before indexPath.

• NSOrderedDescending: The receiver comes after indexPath.

• NSOrderedSame: The receiver and indexPath are the same index path.

Availability

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

Declared In

NSIndexPath.h

getIndexes:

Provides a reference to the receiver’s indexes.

- (void)getIndexes:(NSUInteger *)indexes

Parameters

indexes

Pointer to an unsigned integer array. On return, the receiver indexes.

Availability

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

Declared In

NSIndexPath.h

indexAtPosition:

Provides the index at a particular node in the receiver.

- (NSUInteger)indexAtPosition:(NSUInteger)node

Parameters

node

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

Return Value

Index value at node.

Availability

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

Declared In

NSIndexPath.h

indexPathByAddingIndex:

Provides an index path containing the indexes in the receiver and another index.

- (NSIndexPath *)indexPathByAddingIndex:(NSUInteger)index

Parameters

index

Index to append to the receiver’s indexes.

Return Value

New NSIndexPath object containing the receiver’s indexes and index.

Availability

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

See Also

• – indexPathByRemovingLastIndex

Declared In

NSIndexPath.h

indexPathByRemovingLastIndex

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

- (NSIndexPath *)indexPathByRemovingLastIndex

Return Value

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

Discussion

Returns an empty NSIndexPath instance if the receiver’s length is 1 or less.

Special Considerations

On Mac OS X 10.4 and earlier this method returns nil when the length of the receiver is 1 or less. On Mac OS X 10.5 and later this method will never return nil.

Availability

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

See Also

• – indexPathByAddingIndex:

Declared In

NSIndexPath.h

initWithIndex:

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

- (id)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 Mac OS X v10.4 and later.

See Also

• + indexPathWithIndex:

Declared In

NSIndexPath.h

initWithIndexes:length:

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

- (id)initWithIndexes:(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.

Availability

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

See Also

• + indexPathWithIndexes:length:

Declared In

NSIndexPath.h

length

Provides the number of indexes in the receiver.

- (NSUInteger)length

Return Value

Number of indexes in the receiver.

Availability

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

Declared In

NSIndexPath.h

---