CGAL 4.7 - Handles and Circulators: Functions

\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)

CGAL 4.7 - Handles and Circulators

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Macros | Functions
Functions
Handles and Circulators Reference

##

## Macros

#define | CGAL_For_all(i, j)
| In order to write algorithms that work with iterator ranges as well as with circulator ranges we have to consider the difference of representing an empty range. More...
#define | CGAL_For_all_backwards(i, j)
| See CGAL_For_all.

## Functions

template<class C >
C::difference_type | CGAL::circulator_distance (C c, C d)
| The distance of a circulator `c` to a circulator `d` is the number of elements in the range `[c, d)`. More...
template<class C >
C::size_type | CGAL::circulator_size (C c)
| The size of a circulator is the size of the data structure it refers to. More...
template<class IC >
bool | CGAL::is_empty_range (const IC &i, const IC &j)
| is `true` if the range `[i, j)` is empty, `false` otherwise. More...
template<class IC >
iterator_traits< IC > ::difference_type | CGAL::iterator_distance (IC ic1, IC ic2)
| The following function returns the distance between either two iterators or two circulators. More...
template<class I >
Iterator_tag | CGAL::query_circulator_or_iterator (const I &i)
| This function matches for type `I` if the iterator category of `I` belongs to an iterator. More...
template<class C >
Circulator_tag | CGAL::query_circulator_or_iterator (const C &c)
| This functiona matches for type `C` if the iterator category of `C` belongs to a circulator. More...

## Macro Definition Documentation

#define CGAL_For_all | ( |  | i,
|  |  | j
| ) |  |

In order to write algorithms that work with iterator ranges as well as with circulator ranges we have to consider the difference of representing an empty range.

For iterators this is the range `[i,i)`, while for circulators it would be `c == NULL`, the empty sequence test. The function `is_empty_range()` provides the necessary generic test which accepts an iterator range or a circulator range and says whether the range is empty or not.

A macro `CGAL_For_all( i, j)` simplifies the writing of such simple loops as the one in the example of the function `is_empty_range()`. `i` and `j` can be either iterators or circulators. The macro loops through the range `[i, j)`. It increments `i` until it reaches `j`. The implementation looks like:

for ( bool _circ_loop_flag = ! ::CGAL::is_empty_range(i,j);
_circ_loop_flag;
_circ_loop_flag = ((++i) != (j))
)

Note that the macro behaves like a `for`-loop. It can be used with a single statement or with a statement block. For bidirectional iterators or circulators, a backwards loop macro `CGAL_For_all_backwards(i, j)` exists that decrements `j` until it reaches `i`.

See Also
  `CGAL::iterator_distance()`
  `CGAL::is_empty_range()`
  `CGAL::Circulator_tag`
  `CGAL::Circulator_traits`
  `CGAL::Assert_circulator_or_iterator`
  `Circulator`

`#include <CGAL/circulator.h>`

## Function Documentation

template<class C >

C::difference_type CGAL::circulator_distance | ( | C | c,
|  | C | d
| ) |  |

The distance of a circulator `c` to a circulator `d` is the number of elements in the range `[c, d)`.

It is defined to be zero for a circulator on an empty sequence and it returns the size of the data structure when applied to a range of the form `[c, c)`.

See Also
  `circulator_size`
  `iterator_distance`
  `is_empty_range`
  `Circulator`

`#include <CGAL/circulator.h>`

template<class C >

C::size_type CGAL::circulator_size | ( | C | c) |  |

The size of a circulator is the size of the data structure it refers to.

It is zero for a circulator on an empty sequence. The size can be computed in linear time for forward and bidirectional circulators, and in constant time for random access circulators using the minimal circulator. The function `circulator_size(c)` returns the circulator size. It uses the `c.min_circulator()` function if `c` is a random access circulator.

See Also
  `circulator_distance`
  `iterator_distance`
  `is_empty_range`
  `Circulator`

`#include <CGAL/circulator.h>`

template<class IC >

bool CGAL::is_empty_range | ( | const IC & | i,
|  | const IC & | j
| ) |  |

is `true` if the range `[i, j)` is empty, `false` otherwise.

In order to write algorithms that work with iterator ranges as well as with circulator ranges we have to consider the difference of representing an empty range. For iterators this is the range `[i,i)`, while for circulators it would be `c == NULL`, the empty sequence test. The function `is_empty_range()` provides the necessary generic test which accepts an iterator range or a circulator range and says whether the range is empty or not.

Precondition
  `IC` is either a circulator or an iterator type. The range `[i, j)` is valid.

Example

The following function `process_all()` accepts a range `[i, j)` of an iterator or circulator `IC` and processes each element in this range:

template <class IC>
void process_all( IC i, IC j) {
if (! CGAL::is_empty_range( i, j)) {
do {
process(*i);
} while (++i != j);
}
}

See Also
  `iterator_distance`
  `CGAL_For_all`
  `Circulator_tag`
  `Circulator_traits`
  `Assert_circulator_or_iterator`
  `Circulator`

`#include <CGAL/circulator.h>`

template<class IC >

iterator_traits<IC>::difference_type CGAL::iterator_distance | ( | IC | ic1,
|  | IC | ic2
| ) |  |

The following function returns the distance between either two iterators or two circulators.

See Also
  `circulator_size`
  `circulator_distance`
  `is_empty_range`
  `Circulator_tag`
  `Assert_circulator_or_iterator`
  `CGAL_For_all`
  `Circulator`

`#include <CGAL/circulator.h>`

template<class I >

Iterator_tag CGAL::query_circulator_or_iterator | ( | const I & | i) |  |

This function matches for type `I` if the iterator category of `I` belongs to an iterator.

See Also
  `Circulator_tag`
  `Circulator_traits`
  `Assert_circulator`
  `Circulator`

`#include <CGAL/circulator.h>`

template<class C >

Circulator_tag CGAL::query_circulator_or_iterator | ( | const C & | c) |  |

This functiona matches for type `C` if the iterator category of `C` belongs to a circulator.

See Also
  `Circulator_tag`
  `Circulator_traits`
  `Assert_circulator`
  `Circulator`

`#include <CGAL/circulator.h>`