cvrDebugIterator.h

Go to the documentation of this file.

/*
 * Copyright (C) 2006
 * Peter Doerfler
 *
 *
 * This file is part of the Computer Vision and Robotics Library (CVR-Lib)
 *
 * The CVR-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the BSD License.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the authors nor the names of its contributors may be
 *    used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */



/**
 * \file   cvrDebugIterator.h
 *         Contains a generic implementation of debug iterators (used in debug
 *         builds) for cvr::containers
 * \author Peter Doerfler
 * \date   13.08.2006
 *
 * $Id: cvrDebugIterator.h,v 1.1 2006/08/24 14:56:56 doerfler Exp $
 */

#ifndef _CVR_DEBUG_ITERATOR_H_
#define _CVR_DEBUG_ITERATOR_H_

#include "cvrMetaProgrammingTools.h"
#include <iterator>

namespace cvr {

  namespace internal {


    // the general class declaration which is not needed
    //
    // without this trick it is not possible that Container is a friend of
    // debugIterator, as it is not clear that Container is indeed a
    // class. However, in the specialization below ContainerBase<T> is sure to
    // be a class and is exactly the type the generalVector and generalMatrix
    // classes have.
    template <typename Container, bool constIterator>
    class debugIterator {};

    /**
     * A generic debugging iterator for classes genericVector and
     * genericMatrix. See those classes for usage examples.
     *
     * This iterator is compatible with those found in the STL and can thus be
     * used with all of its functions. Specifically, this iterator is also
     * compatible with a simple pointer which is used as a the iterator of the
     * above containers in release mode.
     *
     * Template parameters:
     * - \p Container that has the data, e.g. genericVector<T>. It must
     * provide \p value_type.
     * - \p constIterator: if true a const_iterator is generated, otherwise an
     * iterator
     */
    template <template <class> class ContainerBase,
              typename T, bool constIterator>
    class debugIterator<ContainerBase<T>, constIterator>
      : public std::iterator<
      std::random_access_iterator_tag,
      typename if_t<constIterator,
                    const typename ContainerBase<T>::value_type,
                    typename ContainerBase<T>::value_type>::type> {
    private:
      // the actual container type
      typedef ContainerBase<T> Container;

      // the std::iterator<> type
      // could have used T, but probably better style like this
      typedef std::iterator<
        std::random_access_iterator_tag,
        typename if_t<constIterator,
                      const typename Container::value_type,
                      typename Container::value_type>::type> base_type;
    public:
      typedef typename base_type::iterator_category iterator_category;
      typedef typename base_type::value_type        value_type;
      typedef typename base_type::difference_type   difference_type;
      typedef typename base_type::reference         reference;
      typedef typename base_type::pointer           pointer;

    private:
      // needed for special ctor that initializes the pointers
      friend class ContainerBase<T>;
      // needed for construction of a const_iterator from an iterator
      friend class debugIterator<Container, !constIterator>;

      /**
       * Pointer to the current element
       */
      pointer ptr_;

      /**
       * Pointer to the first element of the container
       */
      pointer begin_;

      /**
       * Pointer behind the last element of the container
       */
      pointer end_;

      /**
       * Protected constructor (for internal use only)
       * NEVER USE THIS CONSTRUCTOR EXPLICITLY, OR YOUR CODE WILL NOT
       * COMPILE IN THE RELEASE VERSION!
       *
       * This constructor is used in the Container to initialize the internal
       * pointers.
       *
       * @param ptr pointer to the position the iterator will point to
       * @param begin pointer to the first element of the Container
       * @param end pointer behind the last element of the Container
       */
      inline explicit debugIterator(pointer ptr, pointer begin, pointer end);

    public:

      /**
       * Default constructor
       */
      inline debugIterator();

      /**
       * Copy constructor
       */
      inline debugIterator(const debugIterator& other);

      /**
       * Copy constructor. Construct a debugIterator with \p constIterator ==
       * true from \p other with \p constIterator == false and with the same
       * Container.
       */
      template <bool b>
      inline debugIterator(const debugIterator<
                           typename enable_if<Container,
                           constIterator&&!b>::type, b>& other);

      /**
       * Advance to next item
       */
      inline debugIterator& operator++();   // prefix

      /**
       * Advance to next item
       */
      inline debugIterator operator++(int); // postfix

      /**
       * Recede to previous item
       */
      inline debugIterator& operator--();   // prefix

      /**
       * Recede to previous item
       */
      inline debugIterator operator--(int); // postfix

      /**
       * Advance (skip) some elements.
       *
       * Use this operator with care! Note that you can skip the end of
       * the Container, and read (or even worse: write!) out of bounds!
       */
      inline debugIterator& operator+=(const difference_type& n);

      /**
       * Recede (skip) some elements.
       *
       * Use this operator with care! Note that you can skip the beginning of
       * the Container, and read (or even worse: write!) out of bounds!
       */
      inline debugIterator& operator-=(const difference_type& n);

      /**
       * Advance (skip) some elements.
       *
       * Use this operator with care! Note that you can skip the end of
       * the Container, and read (or even worse: write!) out of bounds!
       */
      inline debugIterator operator+(const difference_type& n);

      /**
       * Recede (skip) some elements.
       *
       * Use this operator with care! Note that you can skip the beginning of
       * the Container, and read (or even worse: write!) out of bounds!
       */
      inline debugIterator operator-(const difference_type& n);

      /**
       * Get pointed data
       */
      inline reference operator*() const;

      /**
       * Get pointer to data
       */
      inline pointer operator->() const;

      /**
       * Access the elements relative to the debugIterator position
       */
      inline reference operator[](const difference_type& n) const;

      /**
       * Compare if the pointed position of \p other is the same as that of
       * this.
       */
      template<bool constOther>
      inline bool
      operator==(const debugIterator<Container, constOther>& other) const;

      /**
       * Compare if the pointed position of \p other is different from that of
       * this.
       */
      template<bool constOther>
      inline bool
      operator!=(const debugIterator<Container, constOther>& other) const;

      /**
       * Compare if the position to by this is smaller than the position
       * pointed to by \p other.
       */
      template<bool constOther>
      inline bool
      operator<(const debugIterator<Container, constOther>& other) const;

      /**
       * Compare if the position to by this is greater than the position
       * pointed to by \p other.
       */
      template<bool constOther>
      inline bool
      operator>(const debugIterator<Container, constOther>& other) const;

      /**
       * Compare if the position to by this is smaller or equal than the
       * position pointed to by \p other.
       */
      template<bool constOther>
      inline bool
      operator<=(const debugIterator<Container, constOther>& other) const;

      /**
       * Compare if the position to by this is greater or equal than the
       * position pointed to by \p other.
       */
      template<bool constOther>
      inline bool
      operator>=(const debugIterator<Container, constOther>& other) const;

      /**
       * Difference between this and the \p other debugIterator.
       */
      template<bool constOther>
      inline difference_type
      operator-(const debugIterator<Container, constOther>& other) const;
    };

  } // namespace internal

} // namespace cvr

#include "cvrDebugIterator_inline.h"

#endif