# Chapter 5
Handles and Circulators

Olivier Devillers, Lutz Kettner, Michael Seel, and Mariette Yvinec

## Summary

Most data structures in CGAL use the concept of Handle in their user interface to refer to the elements they store. This concept describes what is sometimes called a trivial iterator. A Handle is akeen to a pointer to an object providing the dereference operator operator*() and member access operator->() but no increment or decrement operators like iterators. A Handle is intended to be used whenever the referenced object is not part of a logical sequence.

The concept of iterators in STL is tailored for linear sequences. In contrast, circular sequences 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.

### Concepts

Handle
Circulator
Forward_circulator
Bidirectional_circulator
Random_access_circulator

### Classes

CGAL::Container_from_circulator<C>
CGAL::Circulator_from_iterator<I>
CGAL::Circulator_from_container<C>
CGAL::Const_circulator_from_container<C>

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>

### Functions

size_type | CGAL::circulator_size ( C c)
difference_type | CGAL::circulator_distance ( C c, C d)
difference_type | CGAL::iterator_distance ( IC ic1, IC ic2)
bool | CGAL::is_empty_range ( IC i, IC j)
CGAL::Circulator_tag
| CGAL::query_circulator_or_iterator ( C c)
CGAL::Iterator_tag | CGAL::query_circulator_or_iterator ( I i)
void | CGAL::Assert_circulator ( C c)
void | CGAL::Assert_iterator ( I i)
void | CGAL::Assert_input_category ( I i)
void | CGAL::Assert_output_category ( I i)
void | CGAL::Assert_forward_category ( IC ic)
void | CGAL::Assert_bidirectional_category ( IC ic)
void | CGAL::Assert_random_access_category ( IC ic)
void | CGAL::Assert_circulator_or_iterator ( IC i)

### Macros

CGAL_For_all(i,j)
CGAL_For_all_backwards(i,j)

## Reference Pages

- Assert_circulator

- circulator_distance

- circulator_size

- Circulator

- Circulator_from_container<C>

- Circulator_from_iterator<I>

- Circulator_tag

- Circulator_traits<C>

- Container_from_circulator<C>

- CGAL_For_all

- Handle

- is_empty_range

- iterator_distance

- query_circulator_or_iterator