NSFastEnumeration Protocol Reference

Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.5 and later.
Declared in
NSEnumerator.h

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

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. (required)

- (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, so you can recast the passed in state structure to one more suitable for your iteration.

Availability
  • Available in 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 OS X v10.5 and later.
Declared In
NSEnumerator.h