/// \defgroup PkgHandlesAndCirculatorsRef Reference Manual
/// \defgroup PkgHandlesAndCirculatorsConcepts Concepts
/// \ingroup PkgHandlesAndCirculatorsRef


/// \defgroup PkgHandlesAndCirculatorsAdapter Adapters for Iterators and Containers
/// \ingroup PkgHandlesAndCirculatorsRef


/// \defgroup PkgHandlesAndCirculatorsFunctions Functions
/// \ingroup PkgHandlesAndCirculatorsRef

/// \defgroup PkgHandlesAndCirculatorsTags Compile Time Tags
/// \ingroup PkgHandlesAndCirculatorsRef

/// \defgroup PkgHandlesAndCirculatorsAssert Assertions
/// \ingroup PkgHandlesAndCirculatorsRef

/// \defgroup PkgHandlesAndCirculatorsBaseClasses Base Classes
/// \ingroup PkgHandlesAndCirculatorsRef


/*!
\addtogroup PkgHandlesAndCirculatorsRef
\cgalPkgDescriptionBegin{Handles and Circulators,PkgHandlesAndCirculators}
\cgalPkgPicture{circulator.png}
\cgalPkgSummaryBegin
\cgalPkgAuthors{Olivier Devillers, Lutz Kettner, Sylvain Pion, Michael Seel, and Mariette Yvinec}
\cgalPkgDesc{This package describes handles and circulators. They are related to iterators. Handles allow to dereference but neither to increment nor to decrement. Circulators have no notion of past-the-end, and they are used in \cgal whenever we have cyclic structures. }
\cgalPkgManuals{Chapter_Handles_Ranges_and_Circulators,PkgHandlesAndCirculatorsRef}
\cgalPkgSummaryEnd
\cgalPkgShortInfoBegin
\cgalPkgSince{1.0}
\cgalPkgBib{cgal:dksy-hc}
\cgalPkgLicense{\ref licensesLGPL  "LGPL"}
\cgalPkgShortInfoEnd
\cgalPkgDescriptionEnd

The concept of iterators in the \stl is tailored for linear sequences.

\cgal extends this in several directions.  First, it supports the notion
of `Handle` (also sometimes referred to as the trivial iterator) which is
used to document that no traversal operation is needed, only reference to an
element.  It also uses the `Range` and `ConstRange` concepts which
encapsulates the access to both the first and the past-the-end iterators of an
iterator range.

Besides linear sequences, circular sequences also occur naturally in many combinatorial
and geometric structures. Examples are polyhedral surfaces and planar
maps, where the edges emanating from a vertex or the edges around a
facet form a circular sequence.

We provide several functions, classes and macros to assist in working
with circulators: distance computation, adaptor classes converting
between circulators and iterators, base classes to ease the implementation
of circulators, and support for generic algorithms that work with
circulators as well as with iterators.

\cgalClassifedRefPages

\cgalCRPSection{Concepts}
- `Handle`
- `Range`
- `ConstRange`
- `Circulator`
- `ForwardCirculator`
- `BidirectionalCirculator`
- `RandomAccessCirculator`

\cgalCRPSection{Classes}
- `CGAL::Container_from_circulator<C>`
- `CGAL::Circulator_from_iterator<I>`
- `CGAL::Circulator_from_container<C>`
- \link CGAL::Circulator_from_container `CGAL::Const_circulator_from_container<C>` \endlink

- `CGAL::Circulator_tag`
- `CGAL::Iterator_tag`
- `CGAL::Forward_circulator_tag`
- `CGAL::Bidirectional_circulator_tag`
- `CGAL::Random_access_circulator_tag`

- `CGAL::Circulator_base`
- `CGAL::Forward_circulator_base`
- `CGAL::Bidirectional_circulator_base`
- `CGAL::Random_access_circulator_base`

- `CGAL::Circulator_traits<C>`

*/

