Aim: Provides an adapter for classical iterators that can iterate through the underlying data structure as in a loop. The increment (resp. decrement) operator encapsulates the validity test and the assignement to the begin (resp. end) iterator of a given range, when the end (resp. beginning) has been reached. For instance, the pre-increment operator does:
More...

#include <DGtal/base/Circulator.h>

Public Types
typedef TIterator	Iterator

typedef Circulator< TIterator >	Self

typedef CirculatorType	Type

typedef boost::iterator_category< TIterator >::type	iterator_category

typedef std::iterator_traits< TIterator >::value_type	value_type

typedef std::iterator_traits< TIterator >::difference_type	difference_type

typedef std::iterator_traits< TIterator >::pointer	pointer

typedef std::iterator_traits< TIterator >::reference	reference

Public Member Functions
	Circulator ()

	Circulator (const Iterator &i, const Iterator &itb, const Iterator &ite)

	~Circulator ()

	Circulator (const Circulator &other)

template<typename other_Iterator >
	Circulator (const Circulator< other_Iterator > &other)

Circulator &	operator= (const Circulator &other)

template<typename other_Iterator >
Circulator &	operator= (const Circulator< other_Iterator > &other)

bool	isValid () const

Iterator	base () const

Iterator	begin () const

Iterator	end () const

reference	operator* () const

pointer	operator-> () const

Self &	operator++ ()

Self	operator++ (int)

Self &	operator-- ()

Self	operator-- (int)

bool	operator== (const Self &other) const

bool	operator!= (const Self &other) const

template<typename OtherIterator >
bool	operator== (const OtherIterator &other) const

template<typename OtherIterator >
bool	operator!= (const OtherIterator &other) const

Self &	operator+= (difference_type d)

Self &	operator-= (difference_type d)

Self	operator+ (difference_type d) const

Self	operator- (difference_type d) const

difference_type	operator- (const Self &c) const

reference	operator[] (difference_type d) const

bool	operator< (const Self &) const

bool	operator<= (const Self &) const

bool	operator> (const Self &c) const

bool	operator>= (const Self &c) const

Protected Attributes
Iterator	myCurrentIt

Iterator	myBeginIt

Iterator	myEndIt

bool	myFlagIsValid

Private Member Functions
	BOOST_STATIC_ASSERT ((boost::is_same< typename IteratorCirculatorTraits< TIterator >::Type, IteratorType >::value))

Detailed Description

template<typename TIterator>
class DGtal::Circulator< TIterator >

Aim: Provides an adapter for classical iterators that can iterate through the underlying data structure as in a loop. The increment (resp. decrement) operator encapsulates the validity test and the assignement to the begin (resp. end) iterator of a given range, when the end (resp. beginning) has been reached. For instance, the pre-increment operator does:

Description of template class 'Circulator'

++myCurrentIt;
if (myCurrentIt == myEndIt) myCurrentIt = myBeginIt;
return *this;

whereas the pre-decrement operator does (if at least bidirectional):

if (myCurrentIt == myBeginIt) myCurrentIt = myEndIt;

--myCurrentIt;

Be aware that random access operators are quite different for circular iterators and classical iterators. Firstly, the difference between two circular iterators c and d is always positive and such that (c-d) + (d-c) is equal to the size of the underlying range. Secondly, comparison operators 'less than' and 'less than or equal to' always return 'true', whereas 'greater than' and 'greater than or equal to' always return 'false'.

Template Parameters

TIterator any forward, bidirectional or random access iterator

Definition at line 85 of file Circulator.h.

Member Typedef Documentation

◆ difference_type

template<typename TIterator >

typedef std::iterator_traits<TIterator>::difference_type DGtal::Circulator< TIterator >::difference_type

Definition at line 104 of file Circulator.h.

◆ Iterator

template<typename TIterator >

typedef TIterator DGtal::Circulator< TIterator >::Iterator

Definition at line 95 of file Circulator.h.

◆ iterator_category

template<typename TIterator >

typedef boost::iterator_category<TIterator>::type DGtal::Circulator< TIterator >::iterator_category

Definition at line 101 of file Circulator.h.

◆ pointer

template<typename TIterator >

typedef std::iterator_traits<TIterator>::pointer DGtal::Circulator< TIterator >::pointer

Definition at line 105 of file Circulator.h.

◆ reference

template<typename TIterator >

typedef std::iterator_traits<TIterator>::reference DGtal::Circulator< TIterator >::reference

Definition at line 106 of file Circulator.h.

◆ Self

template<typename TIterator >

typedef Circulator<TIterator> DGtal::Circulator< TIterator >::Self

Definition at line 96 of file Circulator.h.

◆ Type

template<typename TIterator >

typedef CirculatorType DGtal::Circulator< TIterator >::Type

Definition at line 98 of file Circulator.h.

◆ value_type

template<typename TIterator >

typedef std::iterator_traits<TIterator>::value_type DGtal::Circulator< TIterator >::value_type

Definition at line 103 of file Circulator.h.

Constructor & Destructor Documentation

◆ Circulator() [1/4]

template<typename TIterator >

DGtal::Circulator< TIterator >::Circulator ( )

inline

Default constructor. Default-initializes iterator members NB: not valid

Definition at line 118 of file Circulator.h.

118 : myCurrentIt(), myBeginIt(), myEndIt(), myFlagIsValid(false) {}

DGtal::Circulator::myFlagIsValid

bool myFlagIsValid

Definition: Circulator.h:433

◆ Circulator() [2/4]

template<typename TIterator >

DGtal::Circulator< TIterator >::Circulator	(	const Iterator &	i,
		const Iterator &	itb,
		const Iterator &	ite
	)

inline

Constructor. This object can iterate through the underlying data structure as in a loop, because it knows the begin and end iterator of the range.

Parameters

i	any iterator
itb	begin iterator
ite	end iterator

Definition at line 129 of file Circulator.h.

132 : myCurrentIt(i), myBeginIt(itb), myEndIt(ite), myFlagIsValid(true)

133 { if (myBeginIt == myEndIt) myFlagIsValid = false; }

References DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myEndIt, and DGtal::Circulator< TIterator >::myFlagIsValid.

◆ ~Circulator()

template<typename TIterator >

DGtal::Circulator< TIterator >::~Circulator ( )

inline

Destructor.

Definition at line 138 of file Circulator.h.

138 {}

◆ Circulator() [3/4]

template<typename TIterator >

DGtal::Circulator< TIterator >::Circulator ( const Circulator< TIterator > & other )

inline

Copy constructor.

Parameters

other the object to clone.

Definition at line 144 of file Circulator.h.

     : myCurrentIt(other.myCurrentIt), 
       myBeginIt(other.myBeginIt), myEndIt(other.myEndIt), 
       myFlagIsValid(other.myFlagIsValid)  
     {}

◆ Circulator() [4/4]

template<typename TIterator >

template<typename other_Iterator >

DGtal::Circulator< TIterator >::Circulator ( const Circulator< other_Iterator > & other )

inline

Copy of circulators that adapts other iterator types (not const / const).

Parameters

other the object to clone.

Definition at line 155 of file Circulator.h.

     : myCurrentIt(other.base()), 
       myBeginIt(other.begin()), myEndIt(other.end()), 
       myFlagIsValid(other.isValid())  
     {}

Member Function Documentation

◆ base()

template<typename TIterator >

Iterator DGtal::Circulator< TIterator >::base ( ) const

inline

Returns: member [myCurrentIt], the underlying iterator.

Definition at line 216 of file Circulator.h.

217 { return myCurrentIt; }

References DGtal::Circulator< TIterator >::myCurrentIt.

Referenced by basicForwardTest(), main(), DGtal::Circulator< TIterator >::operator=(), and DGtal::Circulator< TIterator >::operator==().

◆ begin()

template<typename TIterator >

Iterator DGtal::Circulator< TIterator >::begin ( ) const

inline

Returns: member [myBeginIt], begin iterator of the underlying range.

Definition at line 222 of file Circulator.h.

223 { return myBeginIt; }

References DGtal::Circulator< TIterator >::myBeginIt.

Referenced by basicForwardTest(), DGtal::Circulator< TIterator >::operator=(), and DGtal::Circulator< TIterator >::operator==().

◆ BOOST_STATIC_ASSERT()

template<typename TIterator >

DGtal::Circulator< TIterator >::BOOST_STATIC_ASSERT ( (boost::is_same< typename IteratorCirculatorTraits< TIterator >::Type, IteratorType >::value) )

private

◆ end()

template<typename TIterator >

Iterator DGtal::Circulator< TIterator >::end ( ) const

inline

Returns: member [myEndIt], end iterator of the underlying range.

Definition at line 228 of file Circulator.h.

229 { return myEndIt; }

References DGtal::Circulator< TIterator >::myEndIt.

Referenced by basicForwardTest(), DGtal::Circulator< TIterator >::operator=(), and DGtal::Circulator< TIterator >::operator==().

◆ isValid()

template<typename TIterator >

bool DGtal::Circulator< TIterator >::isValid ( ) const

inline

Checks the validity/consistency of the object.

Returns: 'true' if the object is valid, 'false' otherwise.

Definition at line 206 of file Circulator.h.

207 { return myFlagIsValid; }

References DGtal::Circulator< TIterator >::myFlagIsValid.

Referenced by basicForwardTest(), DGtal::Circulator< TIterator >::operator*(), DGtal::Circulator< TIterator >::operator++(), DGtal::Circulator< TIterator >::operator+=(), DGtal::Circulator< TIterator >::operator--(), DGtal::Circulator< TIterator >::operator->(), and DGtal::Circulator< TIterator >::operator==().

◆ operator!=() [1/2]

template<typename TIterator >

template<typename OtherIterator >

bool DGtal::Circulator< TIterator >::operator!= ( const OtherIterator & other ) const

inline

Definition at line 334 of file Circulator.h.

334 { return !(*this == other); }

◆ operator!=() [2/2]

template<typename TIterator >

bool DGtal::Circulator< TIterator >::operator!= ( const Self & other ) const

inline

Definition at line 317 of file Circulator.h.

317 { return !(*this == other); }

◆ operator*()

template<typename TIterator >

reference DGtal::Circulator< TIterator >::operator* ( ) const

inline

Returns: *myCurrentIt.

Definition at line 234 of file Circulator.h.

     { 
      //ASSERT( myCurrentIt != myEndIt ); //myCurrentIt == myEndIt when using reverse iterators on circulators
      ASSERT( isValid() ); 
      return *myCurrentIt; 
     }

References DGtal::Circulator< TIterator >::isValid(), and DGtal::Circulator< TIterator >::myCurrentIt.

◆ operator+()

template<typename TIterator >

Self DGtal::Circulator< TIterator >::operator+ ( difference_type d ) const

inline

Definition at line 377 of file Circulator.h.

     {
         Self tmp = *this;
         return tmp += d;
     }

◆ operator++() [1/2]

template<typename TIterator >

Self& DGtal::Circulator< TIterator >::operator++ ( )

inline

Pre-increment

Definition at line 258 of file Circulator.h.

       {
         ASSERT( isValid() ); 
         ++myCurrentIt;
         if (myCurrentIt == myEndIt) myCurrentIt = myBeginIt;
         return *this;
       }

References DGtal::Circulator< TIterator >::isValid(), DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, and DGtal::Circulator< TIterator >::myEndIt.

Referenced by DGtal::Circulator< TIterator >::operator++().

◆ operator++() [2/2]

template<typename TIterator >

Self DGtal::Circulator< TIterator >::operator++ ( int )

inline

Post-increment

Definition at line 269 of file Circulator.h.

       {
         Self tmp = *this;
         operator++(); 
         return tmp;
       }

References DGtal::Circulator< TIterator >::operator++().

◆ operator+=()

template<typename TIterator >

Self& DGtal::Circulator< TIterator >::operator+= ( difference_type d )

inline

Definition at line 340 of file Circulator.h.

     {
       if ( isValid() )
         {
           //size range
           typename Iterator::difference_type n = myEndIt - myBeginIt;
           ASSERT( n > 0 );
           //difference modulo n
           if ( (d >= n)||(-d >= n) )
             d = d%n; 
           ASSERT( (d < n)&&(-d < n) );
           //position of the current iterator
           typename Iterator::difference_type j = myCurrentIt - myBeginIt;
           ASSERT( (j >= 0) && (j < n) );
           //deviation between the position of the past-the-end value 
           //and the current iterator
           typename Iterator::difference_type e = n - j;
           if (d >= 0)
             { //in case of positive distance
               if (d < e) j += d;
               else j = d - e; 
             }
           else 
             { //in case of negative distance
               if (-d <= j) j += d; 
               else j = j + d + n; 
             }
           ASSERT( (j >= 0) && (j < n) );
           myCurrentIt = myBeginIt + j;
           return *this;
         }
       else
         return *this; 
     }

References DGtal::Circulator< TIterator >::isValid(), DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, and DGtal::Circulator< TIterator >::myEndIt.

Referenced by DGtal::Circulator< TIterator >::operator-=().

◆ operator-() [1/2]

template<typename TIterator >

difference_type DGtal::Circulator< TIterator >::operator- ( const Self & c ) const

inline

Definition at line 389 of file Circulator.h.

     {
         typename Iterator::difference_type d = (myCurrentIt - c.myCurrentIt);
         if (d >= 0)
           return d; 
         else 
           {
             typename Iterator::difference_type n = myEndIt - myBeginIt;
             ASSERT( n > 0 );
             return (n + d); 
           }
     }

References DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, and DGtal::Circulator< TIterator >::myEndIt.

◆ operator-() [2/2]

template<typename TIterator >

Self DGtal::Circulator< TIterator >::operator- ( difference_type d ) const

inline

Definition at line 383 of file Circulator.h.

     {
         Self tmp = *this;
         return tmp += -d;
     }

◆ operator--() [1/2]

template<typename TIterator >

Self& DGtal::Circulator< TIterator >::operator-- ( )

inline

Pre-decrement

Definition at line 280 of file Circulator.h.

       {
         ASSERT( isValid() ); 
         if (myCurrentIt == myBeginIt) myCurrentIt = myEndIt;
         --myCurrentIt;
         return *this;
       }

References DGtal::Circulator< TIterator >::isValid(), DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, and DGtal::Circulator< TIterator >::myEndIt.

Referenced by DGtal::Circulator< TIterator >::operator--().

◆ operator--() [2/2]

template<typename TIterator >

Self DGtal::Circulator< TIterator >::operator-- ( int )

inline

Post-decrement

Definition at line 291 of file Circulator.h.

       {
         Self tmp = *this;
         operator--(); 
         return tmp;
       }

References DGtal::Circulator< TIterator >::operator--().

◆ operator-=()

template<typename TIterator >

Self& DGtal::Circulator< TIterator >::operator-= ( difference_type d )

inline

Definition at line 375 of file Circulator.h.

375 { return operator+=( -d); }

DGtal::Circulator::operator+=

Self & operator+=(difference_type d)

Definition: Circulator.h:340

References DGtal::Circulator< TIterator >::operator+=().

◆ operator->()

template<typename TIterator >

pointer DGtal::Circulator< TIterator >::operator-> ( ) const

inline

Returns: pointer to myCurrentIt

Definition at line 244 of file Circulator.h.

     { 
      //ASSERT( myCurrentIt != myEndIt ); //myCurrentIt == myEndIt when using reverse iterators on circulators
      ASSERT( isValid() ); 
      return myCurrentIt.operator->(); 
     }

References DGtal::Circulator< TIterator >::isValid(), and DGtal::Circulator< TIterator >::myCurrentIt.

◆ operator<()

template<typename TIterator >

bool DGtal::Circulator< TIterator >::operator< ( const Self & ) const

inline

Definition at line 409 of file Circulator.h.

     {
       return true; 
     }

◆ operator<=()

template<typename TIterator >

bool DGtal::Circulator< TIterator >::operator<= ( const Self & ) const

inline

Definition at line 413 of file Circulator.h.

     {
       return true; 
     }

Referenced by DGtal::Circulator< TIterator >::operator>().

◆ operator=() [1/2]

template<typename TIterator >

Circulator& DGtal::Circulator< TIterator >::operator= ( const Circulator< TIterator > & other )

inline

Assignment.

Parameters

other the object to copy.

Returns: a reference on 'this'.

Definition at line 166 of file Circulator.h.

     {
       if ( this != &other )
         {
           myCurrentIt = other.myCurrentIt;
           myBeginIt = other.myBeginIt;
           myEndIt = other.myEndIt;
           if (myBeginIt != myEndIt) 
             myFlagIsValid = true; 
           else 
             myFlagIsValid = false;
         }
       return *this;
     }

References DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, DGtal::Circulator< TIterator >::myEndIt, and DGtal::Circulator< TIterator >::myFlagIsValid.

◆ operator=() [2/2]

template<typename TIterator >

template<typename other_Iterator >

Circulator& DGtal::Circulator< TIterator >::operator= ( const Circulator< other_Iterator > & other )

inline

Assignment that adapts other iterator types (not const / const).

Parameters

other the object to copy.

Returns: a reference on 'this'.

Definition at line 187 of file Circulator.h.

     {
       if ( this != &other )
         {
           myCurrentIt = other.base();
           myBeginIt = other.begin();
           myEndIt = other.end();
           if (myBeginIt != myEndIt) 
             myFlagIsValid = true; 
           else 
             myFlagIsValid = false;
         }
       return *this;
     }

References DGtal::Circulator< TIterator >::base(), DGtal::Circulator< TIterator >::begin(), DGtal::Circulator< TIterator >::end(), DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, DGtal::Circulator< TIterator >::myEndIt, and DGtal::Circulator< TIterator >::myFlagIsValid.

◆ operator==() [1/2]

template<typename TIterator >

template<typename OtherIterator >

bool DGtal::Circulator< TIterator >::operator== ( const OtherIterator & other ) const

inline

Definition at line 320 of file Circulator.h.

     { 
       return ( ( (!isValid())&&(!other.isValid()) )
                || 
                ( ( isValid() && other.isValid())
                  &&
                  ( (myBeginIt == other.begin())
                    &&(myEndIt == other.end())
                    &&(myCurrentIt == other.base())
                    )
                  )
                ); 
     }

References DGtal::Circulator< TIterator >::isValid(), DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, and DGtal::Circulator< TIterator >::myEndIt.

◆ operator==() [2/2]

template<typename TIterator >

bool DGtal::Circulator< TIterator >::operator== ( const Self & other ) const

inline

Definition at line 304 of file Circulator.h.

     { 
       return ( ( (!isValid())&&(!other.isValid()) )
                || 
                ( ( isValid() && other.isValid())
                  &&
                  ( (myBeginIt == other.begin())
                    &&(myEndIt == other.end())
                    &&(myCurrentIt == other.base())
                    )
                  )
                ); 
     }

References DGtal::Circulator< TIterator >::base(), DGtal::Circulator< TIterator >::begin(), DGtal::Circulator< TIterator >::end(), DGtal::Circulator< TIterator >::isValid(), DGtal::Circulator< TIterator >::myBeginIt, DGtal::Circulator< TIterator >::myCurrentIt, and DGtal::Circulator< TIterator >::myEndIt.

◆ operator>()

template<typename TIterator >

bool DGtal::Circulator< TIterator >::operator> ( const Self & c ) const

inline

Definition at line 417 of file Circulator.h.

     {
       return !operator<=(c); 
     }

References DGtal::Circulator< TIterator >::operator<=().

Referenced by DGtal::Circulator< TIterator >::operator>=().

◆ operator>=()

template<typename TIterator >

bool DGtal::Circulator< TIterator >::operator>= ( const Self & c ) const

inline

Definition at line 421 of file Circulator.h.

     {
       return !operator>(c); 
     }

References DGtal::Circulator< TIterator >::operator>().

◆ operator[]()

template<typename TIterator >

reference DGtal::Circulator< TIterator >::operator[] ( difference_type d ) const

inline

Definition at line 401 of file Circulator.h.

     {
         Self tmp = *this;
         tmp += d;
         return *tmp;
     }

Field Documentation

◆ myBeginIt

template<typename TIterator >

Iterator DGtal::Circulator< TIterator >::myBeginIt

protected

Definition at line 431 of file Circulator.h.

Referenced by DGtal::Circulator< TIterator >::begin(), DGtal::Circulator< TIterator >::Circulator(), DGtal::Circulator< TIterator >::operator++(), DGtal::Circulator< TIterator >::operator+=(), DGtal::Circulator< TIterator >::operator-(), DGtal::Circulator< TIterator >::operator--(), DGtal::Circulator< TIterator >::operator=(), and DGtal::Circulator< TIterator >::operator==().

◆ myCurrentIt

template<typename TIterator >

Iterator DGtal::Circulator< TIterator >::myCurrentIt

protected

Definition at line 430 of file Circulator.h.

Referenced by DGtal::Circulator< TIterator >::base(), DGtal::Circulator< TIterator >::operator*(), DGtal::Circulator< TIterator >::operator++(), DGtal::Circulator< TIterator >::operator+=(), DGtal::Circulator< TIterator >::operator-(), DGtal::Circulator< TIterator >::operator--(), DGtal::Circulator< TIterator >::operator->(), DGtal::Circulator< TIterator >::operator=(), and DGtal::Circulator< TIterator >::operator==().

◆ myEndIt

template<typename TIterator >

Iterator DGtal::Circulator< TIterator >::myEndIt

protected

Definition at line 432 of file Circulator.h.

Referenced by DGtal::Circulator< TIterator >::Circulator(), DGtal::Circulator< TIterator >::end(), DGtal::Circulator< TIterator >::operator++(), DGtal::Circulator< TIterator >::operator+=(), DGtal::Circulator< TIterator >::operator-(), DGtal::Circulator< TIterator >::operator--(), DGtal::Circulator< TIterator >::operator=(), and DGtal::Circulator< TIterator >::operator==().

◆ myFlagIsValid

template<typename TIterator >

bool DGtal::Circulator< TIterator >::myFlagIsValid

protected

Definition at line 433 of file Circulator.h.

Referenced by DGtal::Circulator< TIterator >::Circulator(), DGtal::Circulator< TIterator >::isValid(), and DGtal::Circulator< TIterator >::operator=().

The documentation for this class was generated from the following file:

Circulator.h

Public Types

Public Member Functions

Protected Attributes

Private Member Functions

Detailed Description

template<typename TIterator> class DGtal::Circulator< TIterator >

Member Typedef Documentation

◆ difference_type

◆ Iterator

◆ iterator_category

◆ pointer

◆ reference

◆ Self

◆ Type

◆ value_type

Constructor & Destructor Documentation

◆ Circulator() [1/4]

◆ Circulator() [2/4]

◆ ~Circulator()

◆ Circulator() [3/4]

◆ Circulator() [4/4]

Member Function Documentation

◆ base()

◆ begin()

◆ BOOST_STATIC_ASSERT()

◆ end()

◆ isValid()

◆ operator!=() [1/2]

◆ operator!=() [2/2]

◆ operator*()

◆ operator+()

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator+=()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator--() [1/2]

◆ operator--() [2/2]

◆ operator-=()

◆ operator->()

◆ operator<()

◆ operator<=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator>()

◆ operator>=()

◆ operator[]()

Field Documentation

◆ myBeginIt

◆ myCurrentIt

◆ myEndIt

◆ myFlagIsValid

template<typename TIterator>
class DGtal::Circulator< TIterator >