Reference Manual:

Navigation: Up, Table of Contents, Bibliography, Index, Title Page

Definition

The adaptor CGAL_Forward_container_from_circulator<C> is a class that converts any circulator type C to a kind of container class, i.e. a class that provides an iterator and a const_iterator type and two member functions - begin() and end() - that return the appropriate forward iterators. By analogy to STL container classes these member functions return a const iterator in the case that the container itself is constant and a mutable iterator otherwise.

For CGAL_Forward_container_from_circulator<C> the circulator has to fulfill at least the requirements for a forward circulator. The similar CGAL_Bidirectional_container_from_circulator<C> adaptor requires a bidirectional circulator in order to provide bidirectional iterators and the adaptor CGAL_Random_access_container_from_circulator<C> requires a random access circulator to provide random access iterators. In this case the adaptor implements a total ordering relation that is currently not required for random access circulators.

#include <CGAL/circulator.h>

Types

The types shown here are similar for all container-from-circulator adaptors.

Creation

CGAL_Forward_container_from_circulator<C> container;
the resulting iterators will have a singular value.

CGAL_Forward_container_from_circulator<C> container ( C c);
the resulting iterators will have a singular value if the circulator c is singular.

The bidirectional and random access container have similar constructors. The default construction is shown here to present the names.

CGAL_Bidirectional_container_from_circulator<C> container;

CGAL_Random_access_container_from_circulator<C> container;

Operations

iterator container.begin ()
the start iterator.

const_iterator container.begin () const
the start const iterator.

iterator container.end () the past-the-end iterator.

const_iterator container.end () const
the past-the-end const iterator.

The iterator and const_iterator types are of the appropriate iterator category. In addition to the operations required for their category, they have a member function current_circulator() that returns a circulator pointing to the same position as the iterator does.

Example

The generic reverse() algorithm from the STL can be used with an adaptor when at least a bidirectional circulator c is given.

Circulator c;  /* c is assumed to be a bidirectional circulator. */
CGAL_Bidirectional_container_from_circulator<Circulator> container( c);
reverse( container.begin(), container.end());

Implementation

The forward and bidirectional iterator adaptors keep track of the number of rounds a circulator has done around the ring-like data structure. This is a kind of winding number. It is used to distinguish between the start position and the end position which will be denoted by the same circulator. This winding number is zero for the begin()-iterator and one for the end()-iterator. It is incremented whenever a circulator passes the begin() position. Two iterators are equal if their internally used circulators and winding numbers are equal. This is more general than necessary since the end()-iterator is not supposed to move any more, which is here still possible in a defined manner. However, for random access iterators it is not yet supported.

The random access iterator has to be able to compute the size of the data structure. It is needed for the difference of a past-the-end iterator and the begin iterator as well as for the family of the add-operators where a possible wrap around might occur (this feature beyond the iterator requirements is not supported for the moment). Therefore, the constructor for the random access iterator choose the minimal circulator for the internal anchor position. The minimal circulator is part of the random access circulator requirements, see Section .

These adaptor cannot be used for non-mutable circulators if the C++ compiler has the CGAL_CFG_NO_LAZY_INSTANTIATION bug[^1].

Footnotes

The g++ accepts non-mutable circulators with some warnings even though it has this bug.

Next: Class declaration of CGAL_..._circulator_from_iterator<I,T,Size,Dist>