[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/vutil/iterator.hh

Go to the documentation of this file.

/*

    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001-2003 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <http://www.interreality.org>
*/

#ifndef _VUTIL_ITERATOR_HH_
#define _VUTIL_ITERATOR_HH_

#include <iostream>
#include <deque>
#include <stdexcept>
#include <vector>

/** @file
    Defines VOS iterator base class
*/
namespace VUtil {
    /** @ingroup libvutil
        Used by the Iterator template to free the elements of the
        iterator.  Must be specialized for each subclass of Iterator.
     */
    template<class T> inline void iteratorReleaseItem(T*)
    {
    }

    /** @class Iterator iterator.hh vos/vos/iterator.hh
        @ingroup libvutil

        Template base class for iterators in VOS.  Subclasses dervived
        from Iterator are returned by various methods in VOS.  Unlike
        some iterator patterns (such as STL iterators), this Iterator
        class does not iterate over the data structure directly.
        Instead it copies the data of interest (using operator=) into
        a temporary std::vector of elements.  The reason for doing
        this is to avoid concurrency conditions: another thread
        changing the underlying data structure does not invalidate the
        iterator, nor is the calling thread required to lock the
        underlying data structure for any longer than the time
        required to make a copy.  Conversely this means that an
        iterator can be out of date, so an iterator should not be
        stored for extended periods.

        The underlying std::vector is reference counted and may be
        shared among iterators so an iterator may be efficiently
        copied using the copy constructor or Iterator::operator=().
        Please also note that the iterator class itself is not
        threadsafe!  If you must share it with another thread, make a
        copy.

        Typical iterator usage looks like this:
        @code
        for(ChildListIterator cli = getChildren(); cli.hasMore(); cli++)
        {
          std::cout << (*cli)->getChild()->getURLst() << std::endl;
        }
        @endcode
    */
    template<class T> class Iterator
    {
    protected:
        std::vector<T>* items;
        typedef typename std::vector<T>::size_type size_type;
        size_type pos;
        int* refcount;

    public:
        /** Constructor.  Produces an empty iterator. */
        Iterator() {
            pos = 0;
            items = new std::vector<T>();
            refcount = new int;
            *refcount = 1;
        }

        /** Constructor.  Copies the state of the iterator.  The
            underlying std::vector is shared and reference counted, so
            this an efficient operation.
        */
        Iterator(const Iterator& b) : items(b.items),
                                      pos(b.pos),
                                      refcount(b.refcount)
            {
                (*refcount)++;
            }

        /** Destructor. Destroys the underlying std::vector if we're
            the last ones to be using it.
         */
        ~Iterator() {
            if(--(*refcount) == 0) {
                for(size_type i = 0; i < (*items).size(); i++) {
                    iteratorReleaseItem<T>(&((*items)[i]));
                }
                delete refcount;
                delete items;
                refcount = 0;
            }
        }

        /** Increment our current position */
        void operator++() { if(pos < items->size()) pos++; }

        /** Decrement our current position */
        void operator--() { if(pos > 0) pos--; }

        /** Increment our current position */
        void operator++(int) { if(pos < items->size()) pos++; }

        /** Decrement our current position */
        void operator--(int) { if(pos > 0) pos--; }

        /** Copies the state of the iterator.  The underlying
            std::vector is shared and reference counted, so this an
            efficient operation.
        */
        void operator=(const Iterator<T>& i) {
            if(--(*refcount) == 0) {
                for(size_type i = 0; i < (*items).size(); i++) {
                    iteratorReleaseItem<T>(&((*items)[i]));
                }
                delete refcount;
                delete items;
                refcount = 0;
            }

            refcount = i.refcount;
            pos = i.pos;
            items = i.items;
            (*refcount)++;
        }

        /** @return true if there are valid elements remaining in the
            iterator (including the current one)
        */
        bool hasMore() { return (pos < items->size()); }

        /** @return true if the iterator is at the starting position  */
        bool atStart() { return (pos == 0); }

        /** sets the iterator to the starting position  */
        void reset() { pos = 0; }

        /** @return total number of elements in the iterator */
        size_type size() { return items->size(); }

        /** @return number of elements still left, including the
            current element
        */
        size_type remaining() { return (items->size() - pos); };

        /** Set the position of the iterator */
        void setPos(size_type p) {
                if(p > items->size()) {
                        if(items->size() == 0) p = 0;
                        else p = items->size() - 1;
                }
                pos = p;
        }

        /** @return true if the supplied element exists in the list,
            as tested using operator==.  This is a simple linear
            search.
        */
        bool hasItem(T i) {
            for(size_type n = 0; n < items->size(); n++) {
                if((*items)[n] == i) return true;
            }
            return false;
        }
    };
}

#endif