Overview

OSCollectionIterator defines a consistent mechanism to iterate through the objects of an OSCollection. It expands on the basic interface of OSIterator to allow association of an iterator with a specific collection.

To use an OSCollectionIterator, you create it with the collection to be iterated, then call OSIterator as long as it returns an object:

<pre> OSCollectionIterator * iterator = OSCollectionIterator::withCollection(myCollection); OSObject * object; while (object = iterator->getNextObject()) { // do something with object } // optional if (!iterator->isValid()) { // report that collection changed during iteration } iterator->release(); </pre>

Note that when iterating associative collections, the objects returned by getNextObject are keys; if you want to work with the associated values, simply look them up in the collection with the keys.

Use Restrictions

With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.

OSCollectionIterator provides no concurrency protection.

Functions

free

Releases or deallocates any resources used by the OSCollectionIterator object.

getNextObject

Advances to and returns the next object in the iteration.

initWithCollection

Initializes an OSCollectionIterator for the provided collection object.

isValid

Checks that the collection hasn't been modified during iteration.

reset

Resets the iterator to the beginning of the collection, as if it had just been created.

withCollection

Creates and initializes an OSCollectionIterator for the provided collection object.

Releases or deallocates any resources used by the OSCollectionIterator object.

public

virtual void free(); 

Discussion

This function should not be called directly; use release instead.

Advances to and returns the next object in the iteration.

public

virtual OSObject * getNextObject(); 

Return Value

The next object in the iteration context, NULL if there is no next object or if the iterator is no longer valid.

Discussion

This function first calls isValid and returns NULL if that function returns false.

Subclasses must implement this pure virtual function to check for validity with isValid, and then to advance the iteration context to the next object (if any) and return that next object, or NULL if there is none.

Initializes an OSCollectionIterator for the provided collection object.

public

virtual bool initWithCollection(
    const OSCollection *inColl); 

Parameters

Return Value

true if the initialization was successful, or false on failure.

Discussion

Not for general use. Use the static instance creation method withCollection instead.

Checks that the collection hasn't been modified during iteration.

public

virtual bool isValid(); 

Return Value

true if the iterator is valid for continued use, false otherwise (typically because the iteration context has been modified).

Resets the iterator to the beginning of the collection, as if it had just been created.

public

virtual void reset(); 

Creates and initializes an OSCollectionIterator for the provided collection object.

public

static OSCollectionIterator * withCollection(
    const OSCollection *inColl); 

Parameters

Return Value

A new instance of OSCollectionIterator, or NULL on failure.

Last Updated: 2010-07-29