/*
 * TYPEDEF: SE_Iterator
 *
 *   Pointer to an iterator. The definition of an iterator is hidden by the
 *   implementation of this API.  The user of this API simply passes in
 *   and receives back an SE_Iterator for functions that deal with
 *   iterators.
 *
 *   An iterator allows a user to step through a collection of objects
 *   related to the iterator's start object, where the elements of
 *   the collection satisfy the conditions used to initialize the
 *   iterator. (For instance, an iterator may be initialized with a
 *   search filter.)
 *
 *   The relationship of the start object to the objects in the collection
 *   depends on which function was used to initialize the iterator.
 *
 *   Iterators in SEDRIS have the following characteristics:
 *
 *   1. All SEDRIS iterators are external iterators; that is, the user
 *      controls the iterator, and is responsible for freeing anything
 *      retrieved from the iterator.
 *   2. An iterator must be created by an initialize-iterator function
 *      before it is used.
 *   3. An iterator must be freed by SE_FreeIterator() after the
 *      user is done with it.
 *
 *   See the initialize-iterator functions for more details (for example,
 *   SE_InitializeAggregateIterator(), SE_InitializeAssociateIterator(),
 *   SE_InitializeComponentIterator()), as well as SE_GetNextObject(),
 *   SE_GetRemainingObjectsList(), and SE_FreeIterator().
 *
 *   See _Design Patterns: Elements of Reusable Object-Oriented
 *   Software_, by Erich Gamma et. al., Addison-Wesley 1995, 1st
 *   edition for a detailed discussion of the iterator behavioral
 *   pattern and external iterators.
 */