---

NSEnumerator

Class at a Glance

An abstract class whose instances enumerate collections of other objects, such as arrays and dictionaries.

Principal Attributes

• A set of objects to enumerate

• The next object in the enumeration

Creation

All creation methods are defined in the collection classes such as NSArray and NSDictionary. These methods contain the word “Enumerator,” as in NSArray’s objectEnumerator method or NSDictionary’s keyEnumerator method.

Commonly Used Methods

nextElement

Returns the next object in the collection being enumerated.

Overview

NSEnumerator is a simple abstract class whose subclasses enumerate collections of other objects. Collection objects—such as arrays, sets, and dictionaries—provide special NSEnumerator objects with which to enumerate their contents. You send nextElement repeatedly to a newly created NSEnumerator object to have it return the next object in the original collection. When the collection is exhausted, null is returned. You can’t “reset” an enumerator after it’s exhausted its collection. To enumerate a collection again, you need a new enumerator.

Collection classes such as NSArray, NSSet, and NSDictionary include methods that return an enumerator appropriate to the type of collection. For instance, NSArray has two methods that return an NSEnumerator object: objectEnumerator and reverseObjectEnumerator. NSDictionary also has two methods that return an NSEnumerator object: keyEnumerator and objectEnumerator. These methods let you enumerate the contents of an NSDictionary by key or by value, respectively.

The enumerator subclasses used by NSArray, NSDictionary, and NSSet retain the collection during enumeration. When the enumeration is exhausted, the collection is released.

Tasks

Getting the Objects

• nextElement

Querying Enumerators

• getObjCEnumerator
• hasMoreElements

Instance Methods

getObjCEnumerator

Returns an integer value identifying the underlying Objective-C enumerator.

public int getObjCEnumerator()

hasMoreElements

Returns a Boolean value that indicates whether there are more elements in the collection that can be enumerated by the receiver.

public boolean hasMoreElements()

nextElement

Returns the next object from the collection being enumerated.

public Object nextElement()

Discussion

When nextElement returns null, all objects have been enumerated.

---