---

NSFastEnumeration Protocol Reference

Overview

The fast enumeration protocol NSFastEnumeration must be adopted and implemented by objects used in conjunction with the for language construct used in conjunction with Cocoa objects.

The abstract class NSEnumerator provides a convenience implementation that uses nextObject to return items one at a time. For more details, see Fast Enumeration.

Tasks

Enumeration

• – countByEnumeratingWithState:objects:count:

Instance Methods

countByEnumeratingWithState:objects:count:

Returns by reference a C array of objects over which the sender should iterate, and as the return value the number of objects in the array.

- (NSUInteger)countByEnumeratingWithState:(NSFastEnumerationState *)state objects:(id *)stackbuf count:(NSUInteger)len

Parameters

state

Context information that is used in the enumeration to, in addition to other possibilities, ensure that the collection has not been mutated.

stackbuf

A C array of objects over which the sender is to iterate.

len

The maximum number of objects to return in stackbuf.

Return Value

The number of objects returned in stackbuf. Returns 0 when the iteration is finished.

Discussion

The state structure is assumed to be of stack local memory and, from a garbage collection perspective, does not require write-barriers on stores, so you can recast the passed in state structure to one more suitable for your iteration.

Availability

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

Declared In

NSEnumerator.h

Constants

NSFastEnumerationState

This defines the structure used as contextual information in the NSFastEnumeration protocol.

typedef struct {
   unsigned long state;
   id *itemsPtr;
   unsigned long *mutationsPtr;
   unsigned long extra[5];
} NSFastEnumerationState;

Fields

state

Arbitrary state information used by the iterator. Typically this is set to 0 at the beginning of the iteration.

itemsPtr

A C array of objects.

mutationsPtr

Arbitrary state information used to detect whether the collection has been mutated.

extra

A C array that you can use to hold returned values.

Discussion

For more information, see countByEnumeratingWithState:objects:count:.

Availability

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

Declared In

NSEnumerator.h

---