---

d_Iterator.h

Go to the documentation of this file.

//------------------------------------------------------------------------------
#ifndef d_Iterator_h
#define d_Iterator_h 1
//------------------------------------------------------------------------------

#include "oCollBlock.h"
//------------------------------------------------------------------------------

template <class T> class d_Collection;
//------------------------------------------------------------------------------

/**
 * This is the class used for iterating over the elements of a generic collection.
 *
 * LOCATION:
 * d_Iterator.h
 *
 * USAGE:
 * d_Iterator< <type-name> >    <variable-name>;
 * 
 * Where:
 * 
 * <type-name>:         Type to iterate. Can be a literal or a user type
 * <variable-name>:     is the name of d_Iterator object
 *
 * EXAMPLES:
 * d_Varray<d_String>   stringColl;              * Collection
 * d_Iterator<d_String> iter = stringColl.create_iterator();
 * 
 * SEE ALSO:
 * d_Bag, d_Collection, d_Dictionary, d_List, d_Set, d_Varray
 *
 * ODMG:
 * Compliant
 */

template <class T>
class d_Iterator
{
  public:

    /**
     * Default Constructor.
     *
     * ODMG    :        Compliant
     */
    d_Iterator ();

    /**
     * Copy Constructor.
     *
     * Current iterator object and <iSource> are totally independent, thus
     * they can browse the same collection with no conflict.
     *
     * ODMG    :        Compliant
     */
    d_Iterator (const d_Iterator<T>& iSource);

    /**
     * Create a d_Iterator object by a collection.
     *
     * The new iterator point at the first element of collection.
     *
     * SEE ALSO:        d_Collection::create_iterator()
     * ODMG    :        Extension
     */
    d_Iterator (d_Collection<T>* iColl);

    /**
     * Destructor.
     *
     * ODMG    :        Compliant
     */
    ~d_Iterator();

    /**
     * Replaces current element.
     *
     * Replaces the value of the current element pointed by the iterator with
     * <iValue>. This method can be used only with d_List and d_Varray
     * collections.
     *
     * ODMG    :        Compliant
     */
    void replace_element (const T &iValue);

    /**
     * Removes the current element pointed by the iterator.
     *
     * ODMG    :        Compliant
     */
    void remove_element ();

    /**
     * Returns the value of current element.
     *
     * SEE ALSO:  get_element()
     * ODMG    :        Compliant
     */
    T operator * ();

    /**
     * Returns the value of current element.
     *
     * SEE ALSO:  operator*()
     * ODMG    :        Compliant
     */
    T get_element ();

    /**
     * Returns true if the iteration is not completed and there are some
     * elements to visit.
     *
     * Call this method to determine whether iteration is complete (usually
     * in a loop).
     *
     * ODMG    :        Compliant
     */
    d_Boolean not_done ();

    /**
     * Advances the iterator to the next element of collection.
     *
     * Use it without specifying <current> parameter (default = false).
     *
     * SEE ALSO:  operator ++(), next()
     * ODMG    :        Compliant
     */
    void advance (d_Boolean current = d_False);

    /**
     * This is the prefix increment operator.
     *
     * It advances to the next element in the collection and returns it. If
     * this method is called after that the iterator has reached the end of
     * iteration, a d_Error_IteratorExhausted exception is thrown.
     *
     * SEE ALSO:  advance(), next()
     * ODMG    :        Compliant
     */
    d_Iterator<T>& operator ++ ();

    /**
     * This is the postfix increment operator.
     *
     * It advances to the next element in the collection and returns the
     * element pointed by iterator before the advancing. If this method is
     * called after that the iterator has reached the end of iteration, a
     * d_Error_IteratorExhausted exception is thrown.
     *
     * SEE ALSO:  advance(), next()
     * ODMG    :        Compliant
     */
    d_Iterator<T> operator ++ (const int iStep);

    /**
     * Checks the end of iteration and returns current value.
     *
     * It returns false if the iterator is positioned past the last element of
     * iteration, otherwise assigns current value to <iValue> parameter,
     * advances the iterator, and returns true.
     *
     * SEE ALSO:  advance(), operator ++()
     * ODMG    :        Compliant
     */
    d_Boolean next (T& iValue);


    // Internal.
    void assign (const d_Collection<T>* iColl, d_Ref<oCollBlock<T> >& iBlock, const oUInt2 iPos);

    // Internal.
    d_Collection<T> *collection;
    // Internal.
    d_Ref<oCollBlock< T > > currBlock;

  private:
    // Internal.
    d_UShort posInBlock;
};
//------------------------------------------------------------------------------

#include "d_Iterator.cti"
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#endif

---