---

NSPointerArray Class Reference

Overview

NSPointerArray is a mutable collection modeled after NSArray but it can also hold NULL values, which can be inserted or extracted (and which contribute to the object’s count). Moreover, unlike traditional arrays, you can set the count of the array directly. In a garbage collected environment, if you specify a zeroing weak memory configuration, if an element is collected it is replaced by a NULL value.

The copying and archiving protocols are applicable only when a pointer array is configured for object uses.

The fast fast enumeration protocol (that is, use a pointer array in the for...in language construct—see Fast Enumeration in The Objective-C 2.0 Programming Language) will yield NULL values that are present in the array. It is defined for all types of pointers although the language syntax doesn’t directly support this.

Tasks

Creating and Initializing a New Pointer Array

• – initWithOptions:
• – initWithPointerFunctions:
• + pointerArrayWithOptions:
• + pointerArrayWithPointerFunctions:
• + pointerArrayWithStrongObjects
• + pointerArrayWithWeakObjects

Managing the Collection

• – count
• – setCount:
• – allObjects
• – pointerAtIndex:
• – addPointer:
• – removePointerAtIndex:
• – insertPointer:atIndex:
• – replacePointerAtIndex:withPointer:
• – compact

Getting the Pointer Functions

• – pointerFunctions

Class Methods

pointerArrayWithOptions:

Returns a new pointer array initialized to use the given options.

+ (id)pointerArrayWithOptions:(NSPointerFunctionsOptions)options

Parameters

options

The pointer functions options for the new instance.

Return Value

A new pointer array initialized to use the given options.

Availability

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

See Also

• + pointerArrayWithPointerFunctions:
• + pointerArrayWithStrongObjects
• + pointerArrayWithWeakObjects

Declared In

NSPointerArray.h

pointerArrayWithPointerFunctions:

A new pointer array initialized to use the given functions.

+ (id)pointerArrayWithPointerFunctions:(NSPointerFunctions *)functions

Parameters

functions

The pointer functions for the new instance.

Return Value

A new pointer array initialized to use the given pointer functions.

Availability

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

See Also

• + pointerArrayWithOptions:
• + pointerArrayWithStrongObjects
• + pointerArrayWithWeakObjects

Declared In

NSPointerArray.h

pointerArrayWithStrongObjects

Returns a new pointer array that maintains strong references to its elements.

+ (id)pointerArrayWithStrongObjects

Return Value

A new pointer array that maintains strong references to its elements.

Availability

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

See Also

• + pointerArrayWithWeakObjects
• + pointerArrayWithOptions:
• + pointerArrayWithPointerFunctions:

Declared In

NSPointerArray.h

pointerArrayWithWeakObjects

Returns a new pointer array that maintains weak references to its elements.

+ (id)pointerArrayWithWeakObjects

Return Value

A new pointer array that maintains weak references to its elements.

Availability

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

See Also

• + pointerArrayWithStrongObjects
• + pointerArrayWithOptions:
• + pointerArrayWithPointerFunctions:

Declared In

NSPointerArray.h

Instance Methods

addPointer:

Adds a given pointer to the receiver.

- (void)addPointer:(void *)pointer

Parameters

pointer

The pointer to add. This value may be NULL.

Discussion

pointer is added at index count.

Availability

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

Declared In

NSPointerArray.h

allObjects

Returns an array containing all the objects in the receiver.

- (NSArray *)allObjects

Return Value

An array containing all the object in the receiver.

Availability

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

See Also

• – count

Declared In

NSPointerArray.h

compact

Removes NULL values from the receiver.

- (void)compact

Availability

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

Declared In

NSPointerArray.h

count

Returns the number of elements in the receiver.

- (NSUInteger)count

Return Value

The number of elements in the receiver.

Availability

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

See Also

• – setCount:

Declared In

NSPointerArray.h

initWithOptions:

Initializes the receiver to use the given options.

- (id)initWithOptions:(NSPointerFunctionsOptions)options

Parameters

options

The pointer functions options for the new instance.

Return Value

The receiver, initialized to use the given options.

Availability

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

See Also

• – initWithPointerFunctions:
• + pointerArrayWithOptions:
• + pointerArrayWithPointerFunctions:

Declared In

NSPointerArray.h

initWithPointerFunctions:

Initializes the receiver to use the given functions.

- (id)initWithPointerFunctions:(NSPointerFunctions *)functions

Parameters

functions

The pointer functions for the new instance.

Return Value

The receiver, initialized to use the given functions.

Availability

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

See Also

• – initWithOptions:
• + pointerArrayWithPointerFunctions:
• + pointerArrayWithOptions:

Declared In

NSPointerArray.h

insertPointer:atIndex:

Inserts a pointer at a given index.

- (void)insertPointer:(void *)item atIndex:(NSUInteger)index

Parameters

item

The pointer to add.

index

The index of an element in the receiver. This value must be less than the count of the receiver.

Discussion

Elements at and above index, including NULL values, slide higher.

Availability

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

Declared In

NSPointerArray.h

pointerAtIndex:

Returns the pointer at a given index.

- (void *)pointerAtIndex:(NSUInteger)index

Parameters

index

The index of an element in the receiver. This value must be less than the count of the receiver.

Return Value

The pointer at index.

Discussion

The returned value may be NULL.

Availability

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

Declared In

NSPointerArray.h

pointerFunctions

Returns a new NSPointerFunctions object reflecting the functions in use by the receiver.

- (NSPointerFunctions *)pointerFunctions

Return Value

A new NSPointerFunctions object reflecting the functions in use by the receiver.

Discussion

The returned object is a new NSPointerFunctions object that you can modify and/or use directly to create other pointer collections.

Availability

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

Declared In

NSPointerArray.h

removePointerAtIndex:

Removes the pointer at a given index.

- (void)removePointerAtIndex:(NSUInteger)index

Parameters

index

The index of an element in the receiver. This value must be less than the count of the receiver.

Discussion

Elements above index, including NULL values, slide lower.

Availability

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

Declared In

NSPointerArray.h

replacePointerAtIndex:withPointer:

Replaces the pointer at a given index.

- (void)replacePointerAtIndex:(NSUInteger)index withPointer:(void *)item

Parameters

index

The index of an element in the receiver. This value must be less than the count of the receiver.

item

The item with which to replace the element at index. This value may be NULL.

Availability

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

Declared In

NSPointerArray.h

setCount:

Sets the count for the receiver.

- (void)setCount:(NSUInteger)count

Parameters

count

The count for the receiver.

Availability

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

See Also

• – count

Discussion

If count is greater than the count of the receiver, NULL values are added; if count is less than the count of the receiver, then elements at indexes count and greater are removed from the receiver.

Declared In

NSPointerArray.h

---