songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Move to the museum.

This commit is contained in:
Sylvain Pion 2009-01-06 13:15:07 +00:00
parent a1cddcf733
commit eece2c9d21
18 changed files with 0 additions and 2028 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Manual/doc_tex/Use_of_Stl/Algorithm.tex
View File

@ -1,3 +0,0 @@
\cleardoublepage
\chapter{Algorithms}

18
Manual/doc_tex/Use_of_Stl/AssociativeContainer.tex
View File

@ -1,18 +0,0 @@
\cleardoublepage
\chapter{Associative Containers}
Associative containers are objects that store other objects of a single type.
They allow for the fast retrieval of data based on keys.
\input{Use_of_Stl/set}
\input{Use_of_Stl/multiset}
\newpage
\input{Use_of_Stl/map}
\newpage
\input{Use_of_Stl/multimap}

499
Manual/doc_tex/Use_of_Stl/Circulator_stl.tex
View File

@ -1,499 +0,0 @@
% +------------------------------------------------------------------------+
% | STL User Manual: Circulator_stl.tex
% +------------------------------------------------------------------------+
% | Requirements for circulators in analogy to STL iterators.
% | Adaptors between circulators and iterators.
% | Proposal for CGAL.
% |
% | 27.01.1997 Lutz Kettner
% | Adapted from the iterator chapter and the circulator
% | chapter of the CGAL Reference Manual circulator.tex R1.3.
% |
% | $Id$
% | $Date$
% +------------------------------------------------------------------------+
\cleardoublepage
\chapter{Circulators\label{sectionCirculatorWarning}}
Circulators are quite similar to iterators that are described in
Chapter~\ref{chapterIterators}. Circulators are a generalization of
pointers that allow a programmer to work with different circular data
structures like a ring list in a uniform manner. Please note that
circulators are not part of the \stl, but of \cgal. A summary of the
requirements for circulators is presented here. Thereafter, a couple
of adaptors are described that convert between iterators and
circulators. For the complete description of the requirements, support
to develop own circulators, and the adaptors please refer to the \cgal\
Reference Manual: Part 3: Support Library.
The specialization on circular data structures gives the reason for
the slightly different requirements for circulators than for
iterators. A circular data structure has no natural past-the-end
value. In consequence, a container supporting circulators will not
have an {\tt end()}-member function, only a {\tt begin()}-member
function. The semantic of a range is different for a circulator $c$:
The range $\left[c, c\right)$ denotes the sequence of all elements in
the data structure. For iterators, this range would be empty. A
separate test for an empty sequence has been added to the
requirements. A comparison $c ==$ {\tt NULL} for a circulator $c$
tests whether the data structure is empty or not. As for
\CC, we recommend the use of 0 instead of {\tt NULL}. An example
function demonstrates a typical use of circulators. It counts the
number of elements in the range $\left[c, d\right)$:
\begin{verbatim}
template <class Circulator, class Size>
void count( Circulator c, Circulator d, Size& n) {
n = 0;
if ( c != 0) {
do {
++n;
} while (++c != d);
}
}
\end{verbatim}
Given a circular data structure $S$, the expression {\tt
count(}$S${\tt.begin(),} $S${\tt.begin(), counter)} returns the
number of elements of $S$ in the {\tt counter} parameter.
As for iterators, circulators come in different flavors. There are
{\em forward, bidirectional\/} and {\em random access circulators}.
They are either {\em mutable} or {\em constant}. The past-the-end
value is not applicable for circulators.
{\bf Reachability:}
A circulator $d$ is called {\em reachable} from a circulator $c$ if
and only if there is a finite sequence of applications of
\ccStyle{operator++} to $c$ that makes $c == d$. If $c$ and $d$ refer
to the same non-empty data structure, then $d$ is reachable from $c$,
and $c$ is reachable from $d$. In particular, any circulator $c$
referring to a non-empty data structure will return to itself after a
finite sequence of applications of \ccStyle{operator++} to $c$.
{\bf Range:}
Most of the library's algorithmic templates that operate on data
structures have interfaces that use {\em ranges}. A range is a pair of
circulators that designate the beginning and end of the computation. A
range $\left[c, c\right)$ is a {\em full range}; in general, a range
$\left[c, d\right)$ refers to the elements in the data structure
starting with the one pointed to by $c$ and up to but not including
the one pointed to by $d$. Range $\left[c, d\right)$ is valid if and
only if both refer to the same data structure. The result of the
application of the algorithms in the library to invalid ranges is
undefined.
{\bf Warning:} Please note that the definition of a range is different
to that of iterators. An interface of a data structure must declare
whether it works with iterators, circulators, or both. \stl\ algorithms
always specify only iterators in their interfaces. A range $\left[c,
d\right)$ of circulators used in an interface for iterators will
work as expected as long as $c\; !\!= d$. A range $\left[c, c\right)$ will
be interpreted as the empty range like for iterators, which is
different than the full range that it should denote for circulators.
Algorithms could be written to support both, iterators and
circulators, in a single interface. Here, the range $\left[c,
c\right)$ would be interpreted correctly. For more information how
to program functions with this behavior, please refer to the \cgal\
Reference Manual.
\medskip
As we said in the introduction, we are a little bit sloppy in the
presentation, in order to make it easier to understand. A class is
said to be a circulator if it fulfills a set of requirements. In the
following sections we do not present the requirements, but we state
properties that are true, if the requirements are fulfilled. The
difference is best seen by an example: We write that the return value
of the test for equality returns a \ccStyle{bool}. The requirement is
only that the return value is convertible to \ccStyle{bool}.
\begin{ccHtmlClassFile}{Circulator.html}{Requirements for Circulators}
\begin{ccClass}{Circulator}
\ccSection{Forward Circulator}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of a forward circulator
for the value type \ccStyle{T}, supports the following operations.
\ccCreation
\ccCreationVariable{c}
%\ccSetThreeColumns{Circulator&}{int n + Circulator d}{}
%\ccSetThreeColumns{difference_type}{difference_type n += d}{}
\ccPropagateThreeToTwoColumns
\ccConstructor{Circulator();}
{}
\ccConstructor{Circulator(const Circulator& d);}
{}
\ccOperations
\ccMethod{bool operator=(const Circulator &d);}
{Assignment.}
\ccMethod{bool operator==(NULL) const;}
{Test for emptiness.}
\ccMethod{bool operator!=(NULL) const;}
{Test for non-emptiness. The result is the same as \ccStyle{!(c == NULL)}.}
\ccMethod{bool operator==(const Circulator &d) const;}
{Test for equality: Two circulators are equal if they refer to the same item.}
\ccMethod{bool operator!=(const Circulator &d) const;}
{Test for inequality. The result is the same as \ccStyle{!(c == d)}.}
\ccMethod{T& operator*();}
{Returns the value of the circulator.
If \ccClassName\ is mutable \ccStyle{*c = t} is valid.
\ccPrecond \ccVar\ is dereferenceable.}
\ccMethod{Circulator& operator++();}
{Prefix increment operation.
\ccPrecond \ccVar\ is dereferenceable. \ccPostcond \ccVar\ is dereferenceable.}
\ccMethod{const Circulator& operator++(int);}
{Postfix increment operation. The result is the same as that of
\ccStyle{Circulator tmp = c; ++c; return tmp;}~.}
\end{ccClass}
\ccHtmlNoClassLinks
\ccHtmlNoClassIndex
\begin{ccClass}{Circulator}
\ccSection{Bidirectional Circulator}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of a bidirectional
circulator for the value type \ccStyle{T}, supports the following operations
in addition to the operations supported by a forward circulator.
\ccCreationVariable{c}
\ccOperations
\ccMethod{Circulator& operator--();}
{Prefix decrement operation.
\ccPrecond \ccVar\ is dereferenceable. \ccPostcond \ccVar\
is dereferenceable.}
\ccMethod{const Circulator& operator--(int);}
{Postfix decrement operation. The result is the same as that of
\ccStyle{Circulator tmp = c; --c; return tmp;}~.}
\end{ccClass}
\ccHtmlNoClassLinks
\ccHtmlNoClassIndex
\begin{ccClass}{Circulator}
\ccSection{Random Access Circulator}
\label{sectionRandomAccessCirculatorRequ}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of a random access
Circulator for the value type \ccStyle{T}, supports the following operations
in addition to the operations supported by a bidirectional Circulator.
\ccCreationVariable{c}
\ccOperations
\ccMethod{Circulator& operator+=(int n);}
{The result is the same as if the prefix increment operation
was applied $n$ times, but it is computed in constant time.}
\ccMethod{Circulator operator+(int n);}
{Same as above, but returns a new circulator.}
\renewcommand{\ccTagRmEigenClassName}{\ccTrue}
\ccFunction{Circulator operator+(int n, Circulator c);}
{Same as above.}
\renewcommand{\ccTagRmEigenClassName}{\ccFalse}
\ccMethod{Circulator& operator-=(int n);}
{The result is the same as if the prefix decrement operation
was applied $n$ times, but it is computed in constant time.}
\ccMethod{Circulator operator-(int n);}
{Same as above, but returns a new circulator.}
\ccMethod{T& operator[](int n);}
{Returns \ccStyle{*(c + n)}.}
\ccMethod{int operator-(const Circulator& d) const;}
{returns the difference between the two circulators within the
interval $\left[ 1-s , s-1 \right]$ for a sequence size $s$. The
difference for a fixed circulator \ccVar\ (or $d$) with all other
circulators $d$ (or \ccVar) is a consistent ordering of the elements
in the data structure. There has to be a minimal circulator
$d_{\mbox{\footnotesize min}}$ for which the difference \ccVar $-
d_{\mbox{\footnotesize min}}$ to all other circulators \ccVar\ is
non negative.}
\ccMethod{Circulator min_circulator() const;}
{Returns the minimal circulator $c_{\mbox{\footnotesize min}}$ in
constant time. If $c$ has a singular value, a singular value is
returned.}
There are no comparison operators required.
\end{ccClass}
\end{ccHtmlClassFile}
% +-----------------------------------------------------+
\newpage
\section{Adaptor: Container with Iterators from Circulator\label{sectionContainerFromCirc}}
Algorithms working on iterators cannot be applied to circulators in
full generality, only to subranges (see the warning in
Section~\ref{sectionCirculatorWarning}). The following adaptors
convert circulators to iterators (with the unavoidable space and time
drawback) to reestablish this generality.
\begin{ccClassTemplate}{Container_from_circulator<C>}
\ccDefinition
The adaptor \ccClassTemplateName\ is a class that converts any
circulator type \ccStyle{C} to a kind of container class, i.e.~a class
that provides an \ccStyle{iterator} and a \ccStyle{const_iterator}
type and two member functions -- \ccStyle{begin()} and \ccStyle{end()}
-- that return the appropriate iterators. In analogy to \stl\
container classes these member functions return a \ccc{const_iterator}
in the case that the container itself is constant and a mutable
\ccc{iterator} otherwise.
\ccInclude{CGAL/circulator.h}
\ccTypes
\ccNestedType{Circulator}{the template argument \ccc{C}.}
\ccNestedType{iterator}{}
\ccGlue
\ccNestedType{const_iterator}{}
\ccCreation
\ccCreationVariable{container}
%\ccSetTwoColumns{Circulator}{}
\ccConstructor{Container_from_circulator();}{%
the resulting iterators will have a singular value.}
\ccConstructor{Container_from_circulator(const C& c);}{%
the resulting iterators will have a singular value if the circulator
\ccStyle{c} is singular.}
\ccOperations
%\ccSetThreeColumns{const_iterator}{container.begin() const;}{}
\def\ccTagRmTrailingConst{\ccFalse}
\ccMethod{iterator begin();}{the start iterator.}
\ccGlue
\ccMethod{const_iterator begin() const;}{the start const iterator.}
\ccGlue
\ccMethod{iterator end();}{the past-the-end iterator.}
\ccGlue
\ccMethod{const_iterator end() const;}{the past-the-end const iterator.}
\def\ccTagRmTrailingConst{\ccTrue}
The \ccc{iterator} and \ccc{const_iterator} types are of the
appropriate iterator category. In addition to the operations required
for their category, they have a member function
\ccc{current_circulator()} that returns a circulator pointing to the
same position as the iterator does.
\ccExample
The generic {\tt reverse()} algorithm from the \stl\ can be used with an
adaptor if at least a bidirectional circulator {\tt c} is given.
\begin{ccExampleCode}
Circulator c; // c is assumed to be a bidirectional circulator.
CGAL::Container_from_circulator<Circulator> container(c);
reverse( container.begin(), container.end());
\end{ccExampleCode}
\ccImplementation
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
\ccStyle{begin()}-iterator and one for the \ccStyle{end()}-iterator.
It is incremented whenever a circulator passes the \ccStyle{begin()}
position. Two iterators are equal if their internally used circulators
and winding numbers are equal. This is more general than necessary
since the \ccStyle{end()}-iterator is not supposed to move any more.
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. 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~\ref{sectionRandomAccessCirculatorRequ}.
\end{ccClassTemplate}
% +-----------------------------------------------------+
\newpage
\section{Adaptor: Circulator from Iterator\label{sectionCircFromIter}}
To obtain circulators, one could use a container class like those in
the Standard Template Library (\stl) or a pair of \ccStyle{begin()}-,
\ccStyle{end()}-iterators and one of the following adaptors. The adaptor
for iterator pairs is described here, the adaptor for container classes
is described in the next section.
\begin{ccClassTemplate}{Circulator_from_iterator<I>}
\ccDefinition
The adaptor \ccClassTemplateName\ converts two iterators of type
\ccc{I}, a begin and a past-the-end value, to a circulator of equal
category. The iterator must be at least of the forward iterator
category. The circulator will be mutable or non-mutable according to
the iterator. Iterators provide no \ccc{size_type}. This adapter
assumes \ccc{std::size_t} instead.
\ccInclude{CGAL/circulator.h}
\ccTypes
%\ccSetThreeColumns{typedef const T&}{const_reference;}{}
\ccUnchecked\ccTypedef{typedef I iterator;}{}
In addition all types required for circulators are provided.
\ccCreation
\ccCreationVariable{c}
\ccConstructor{Circulator_from_iterator();}{%
a circulator \ccVar\ with a singular value.}
\ccConstructor{Circulator_from_iterator(const I& begin, const I& end);}{%
a circulator \ccVar\ initialized to refer to the element
\ccStyle{*begin} in a range {\tt [}\ccStyle{begin}{\tt
,}\ccStyle{end}{\tt )}.
The circulator \ccVar\ contains a singular value if \ccStyle{begin==end}.
}
\ccOperations
The adaptors conform to the requirements of the different circulator
categories. An additional member function \ccc{current_iterator()} is
provided that returns the current iterator that points to the same
position as the circulator does.
\ccExample
This program uses two adaptors, iterators to circulators and back to
iterators. It applies an \stl\ sort algorithm on a \stl\ vector with three
elements. The resulting vector will be {\tt [2 5 9]} as it will be
checked by the assertions. The program is part of the \cgal\
distribution.
\ccIncludeExampleCode{Circulator/circulator_prog1.cpp}
Another example usage for this adaptor are random access circulators
over the built-in C arrays. Given an array of type {\tt T*} with a
begin pointer {\tt b} and a past-the-end pointer {\tt e} the adaptor
\ccStyle{Circulator_from_iterator< T*> c( b,e)} is a random circulator
\ccStyle{c} over this array.
\end{ccClassTemplate}
% +-----------------------------------------------------+
\newpage
\section{Adaptor: Circulator from Container\label{sectionCircFromContainer}}
To obtain circulators, one could use a container class like those in the
Standard Template Library (\stl) or a pair of \ccStyle{begin()}-,
\ccStyle{end()}-iterators and one of the provided adaptors here.
The adaptor for iterator pairs is described in the previous section,
the adaptor for container classes is described here.
\begin{ccClassTemplate}{Circulator_from_container<C>}
\ccHtmlCrossLink{Const_circulator_from_container}
\ccHtmlCrossLink{Const_circulator_from_container<C>}
\ccIndexMainItemDef[C]{Const_circulator_from_container<C>}
\ccDefinition
The adaptor \ccClassTemplateName\ provides a circulator for an \stl\
container $C$ of equal category as the iterator provided by the container.
The iterator must be at least of the forward iterator
category. The corresponding non-mutable circulator is called
\ccc{Const_circulator_from_container<C>}.
The container type \ccc{C} is supposed to conform to the \stl\
requirements for container (i.e.~to have a \ccStyle{begin()} and an
\ccStyle{end()} iterator as well as the local types
\ccStyle{reference}, \ccStyle{const_reference}, \ccStyle{value_type},
\ccStyle{size_type}, and \ccStyle{difference_type}).
\ccInclude{CGAL/circulator.h}
\ccTypes
%\ccSetThreeColumns{typedef container::const_reference}{const_reference;}{}
All types required for circulators are provided.
\ccCreation
\ccCreationVariable{c}
\ccConstructor{Circulator_from_container();}{%
a circulator \ccVar\ with a singular value.}
\ccConstructor{Circulator_from_container(C* container);}{%
a circulator \ccVar\ initialized to refer to the first element in
\ccStyle{container}, i.e. \ccStyle{container.begin()}.
The circulator \ccVar\ contains a singular value if the
\ccStyle{container} is empty.
}
\ccConstructor{Circulator_from_container(C* container, C::iterator i);}{%
a circulator \ccVar\ initialized to refer to the element \ccStyle{*i} in
\ccStyle{container}. \ccPrecond \ccStyle{*i} is dereferenceable and refers
to \ccStyle{container}.
}
\ccOperations
The adaptors conform to the requirements of the different circulator
categories. An additional member function \ccc{current_iterator()} is
provided that returns the current iterator that points to the same
position as the circulator does.
\ccExample
This program uses two adaptors, container to circulators and back to
iterators. It applies an \stl\ sort algorithm on a \stl\ vector with three
elements. The resulting vector will be {\tt [2 5 9]} as it will be
checked by the assertions. The program is part of the \cgal\
distribution.
\ccIncludeExampleCode{Circulator/circulator_prog2.cpp}
\end{ccClassTemplate}
% EOF

117
Manual/doc_tex/Use_of_Stl/FunctionObject.tex
View File

@ -1,117 +0,0 @@
\cleardoublepage
\chapter{Function Objects}
Function objects are objects with an \ccc{operator()(..)} defined. This results
in faster code than passing function pointers, as the operator can
even be inlined. The following function object classes are defined in \stl.
\section{Arithmetic operations}
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{functional}
\ccHtmlLinksOn
\stl\ defines the following function object classes \ccStyle{plus<T>},
\ccStyle{minus<T>}, \ccStyle{times<T>}, \ccStyle{divides<T>}, and
\ccStyle{modulus<T>}, which have an operator() with two arguments.
Furthermore, there is the function object class \ccStyle{negate<T>} with
a single argument. The arguments as well as the return value are of
type \ccStyle{T}.
Pars pro toto we give the more formal definition for tha class \ccc{plus<T>}.
\begin{ccClassTemplate}{plus<T>}
\ccDefinition
An object of the class \ccClassName\ is a function object that allows
to add two objects of type \ccc{T}.
\ccCreationVariable{add}
\ccOperations
\ccMethod{T operator()(const T& t1, const T& t2) const;}
{returns \ccc{t1 + t2}.
\ccPrecond `+' must be defined for type \ccc{T}.}
\end{ccClassTemplate}
\ccExample
The following example shows how the function object \ccc{negate<T>}
is applied on each element of an array.
\begin{cprog}
{
const int n = 10;
int A[n];
A[0] = 23;
...
A[9] = 56;
for_each(A, A+n, negate<int>());
}
\end{cprog}
\newpage
\section{Comparisons}
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{functional}
\ccHtmlLinksOn
\stl\ defines the following function object classes \ccStyle{equal_to<T>},
\ccStyle{not_equal_to<T>}, \ccStyle{greater<T>}, \ccStyle{less<T>},
\ccStyle{greater_equal<T>}, \ccStyle{less_equal<T>}. They all have an
operator() with two arguments of type \ccStyle{T} and the return value
is of type \ccStyle{bool}.
\begin{ccClassTemplate}{greater<T>}
\ccDefinition
An object of the class \ccClassName\ is a function object that allows
to compare two objects of type \ccc{T}.
\ccCreationVariable{g}
\ccOperations
\ccMethod{T operator()(const T& t1, const T& t2) const;}
{returns \ccc{t1 > t2}.
\ccPrecond `$>$' must be defined for type \ccc{T}.}
\end{ccClassTemplate}
\ccExample
A {\em set} is a container that stores objects in a linear
order. Instead of having global {\em compare} functions for a type we
pass a function object as template argument. Set \ccStyle{S} stores
integers in a decreasing order. The first template argument is the
type of the data in the set, the second template argument is the type
of the comparison function object class.
\begin{cprog}
{
set< int, greater<int> > S;
}
\end{cprog}
The following code fragment shows how to sort an array using the
\stl\ function \ccc{sort}.
\begin{cprog}
{
const int n = 10;
int A[n];
A[0] = 23;
...
A[9] = 56;
sort(A, A+n, greater<int>());
}
\end{cprog}

442
Manual/doc_tex/Use_of_Stl/Iterator.tex
View File

@ -1,442 +0,0 @@
\cleardoublepage
\chapter{Iterators\label{chapterIterators}}
Iterators are a generalization of pointers that allow a programmer to
work with different data structures (containers) in a uniform manner.
An iterator is the glue that allows to write a single implementation of
an algorithm that will work for data contained in an array, a list or
some other container -- even a container that did not yet exist when the
algorithm was implemented.
An iterator is a concept, not a programming language construct. It can
be seen as a set of requirements. A type is an iterator if it satisfies
those requirements. So, for instance, a pointer to an element of an
array is an iterator. We will check this later.
Depending on the operations defined for an iterator, there are five
categories: {\em input, output, forward, bidirectional} and {\em
random access iterators}. We first have to introduce some terminology.
{\bf Mutable versus constant:}
There is an additional attribute that forward, bidirectional and
random access iterators might have, that is, they can be {\em mutable}
or {\em constant} depending on whether the result of the
\ccTexHtml{{\tt operator }\raisebox{-1mm}{*}}{<TT>operator *</TT>}
behaves as a reference or as a reference to a constant.
{\bf Past-the-end value:}
Just as a regular pointer to an array guarantees that there is a
pointer value pointing past the last element of the array, so for any
iterator type there is an iterator value that points past the last
element of a corresponding container. These values are called {\em
past-the-end} values. Values of the iterator for which the
\ccTexHtml{{\tt operator }\raisebox{-1mm}{*}}{<TT>operator *</TT>}
is defined are called {\em dereferenceable}.
The library never assumes that past-the-end values are
dereferenceable.
{\bf Reachability} An iterator $j$ is called {\em reachable} from an
iterator $i$ if and only if there is a finite sequence of applications
of \ccStyle{operator}$\!+\!+$ to $i$ that makes $i == j$. If $i$ and
$j$ refer to the same container, then either $j$ is reachable from
$i$, or $i$ is reachable from $j$, or both ($i == j$).
{\bf Range:}
Most of the library's algorithmic templates that operate on data
structures have interfaces that use {\em ranges}. A range is a pair of
iterators that designate the beginning and end of the computation. A
range $\left[i, i\right)$ is an {\em empty range}; in general, a range
$\left[i, j\right)$ refers to the elements in the data structure
starting with the one pointed to by $i$ and up to but not including the
one pointed to by $j$. Range $\left[i, j\right)$ is valid if and only if $j$
is reachable from $i$. The result of the application of the
algorithms in the library to invalid ranges is undefined.
\medskip
As we mentioned in the introduction we are a little bit sloppy in the
presentation of \stl, in order to make it easier to understand. A
class is said to be an iterator if it fulfills a set of requirements.
In the following sections we do not present the requirements, but we
state properties that are true, if the requirements are fulfilled.
The difference is best seen by an example: we write that the return
value of the test for equality returns a \ccStyle{bool}, but the
requirement is only that the return value is convertible to \ccStyle{bool}.
\newpage
\begin{ccClass}{forward_iterator}
\ccSection{Forward Iterator}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of a forward iterator
for the value type \ccStyle{T}, supports the following operations.
\ccCreation
\ccCreationVariable{it}
\ccConstructor{iterator();}
{}
\ccConstructor{iterator(const iterator& it1);}
{}
\ccOperations
\ccMethod{iterator& operator=(const iterator &it1);}
{Assignment.}
\ccMethod{bool operator==(const iterator &it1) const;}
{Test for equality: Two iterators are equal if they refer to the same item.}
\ccMethod{bool operator!=(const iterator &it1) const;}
{Test for inequality. The result is the same as \ccStyle{!(it == it1)}.}
\ccMethod{T& operator*();}
{Returns the value of the iterator.
If \ccClassName\ is mutable \ccStyle{*it = t} is valid.
\ccPrecond \ccVar\ is dereferenceable.}
\ccMethod{iterator& operator++();}
{Prefix increment operation.
\ccPrecond \ccVar\ is dereferenceable.}
\ccMethod{const iterator& operator++(int);}
{Postfix increment operation. The result is the same as that of
\ccStyle{iterator tmp = it; ++it; return tmp;}.
\ccPrecond \ccVar\ is dereferenceable.}
\end{ccClass}
\begin{ccClass}{bidirectional_iterator}
\ccSection{Bidirectional Iterator}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of a bidirectional
iterator for the value type \ccStyle{T}, supports the following operations
in addition to the operations supported by a forward iterator.
\ccCreationVariable{it}
\ccOperations
\ccMethod{iterator& operator--();}
{Prefix decrement operation.
\ccPrecond \ccVar\ is dereferenceable.}
\ccMethod{const iterator& operator--(int);}
{Postfix decrement operation. The result is the same as that of
\ccStyle{iterator tmp = it; --it; return tmp;}.
\ccPrecond \ccVar\ is dereferenceable.}
\end{ccClass}
\newpage
\begin{ccClass}{random_access_iterator}
\ccSection{Random Access Iterator}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of a random access
iterator for the value type \ccStyle{T}, supports the following operations
in addition to the operations supported by a bidirectional iterator.
\ccCreationVariable{it}
\vfill
\ccOperations
\ccMethod{iterator& operator+=(int n);}
{The result is the same as if the prefix increment operation
was applied $n$ times, but it is computed in constant time.}
\ccMethod{iterator operator+(int n);}
{Same as above, but returns a new iterator.}
\ccFunction{iterator operator+(int n, iterator it);}
{Same as above.}
\ccMethod{iterator& operator-=(int n);}
{The result is the same as if the prefix decrement operation
was applied $n$ times, but it is computed in constant time.}
\ccMethod{iterator operator-(int n);}
{Same as above, but returns a new iterator.}
\ccMethod{int operator-(const iterator &it1);}
{The result \ccStyle{n} is such that \ccStyle{it1 + n ==} \ccVar.
\ccPrecond \ccVar\ is reachable from \ccStyle{it1}.}
\ccMethod{T& operator[](int n);}
{Returns \ccStyle{*(it + n)}.
\ccPrecond \ccStyle{*(it + n)} is dereferenceable}
\ccMethod{bool operator<(iterator it1);}
{$<$ is a total ordering relation.}
\ccMethod{bool operator>(iterator it1);}
{$>$ is a total ordering relation opposite to \ccStyle{<}.}
\ccMethod{bool operator<=(iterator it1);}
{Result is the same as \ccStyle{! it > it1}.}
\ccMethod{bool operator>=(iterator it1);}
{Result is the same as \ccStyle{! it < it1}.}
\vfill
\ccExample
We promised to show why a pointer (in this case \ccStyle{V*}) is a random access
iterator. In order to show that it supports the required operations, we
give a program that uses them. Not all operations are used --- so it is not a
complete proof --- but hopefully enough to convince the reader.
Notice that the program is nothing special. It was valid \CC\ (with minor
changes even valid C), long before the iterator concept was invented!
The comments point to the requirements.
\newpage
\begin{cprog}
const int N = 10;
struct V {
float val;
};
float fill_and_add(V *b, V *e)
{
V *c; /* creation, first way (ForwardIterator) */
float sum;
for (int i=0; i<e-b; i++) /* subtraction (RandomAccessIterator) */
b[i].val = i*i/2.0; /* indexing (RandomAccessIterator) */
for (c=b; c != e; ++c) /* assignment, inequality test, increment (ForwardIterator) */
sum += (*c).val; /* dereference (ForwardIterator) */
return sum;
}
float foo()
{
V a[N];
V *e(a+N); /* creation, second way (ForwardIterator) and */
/* integer adding (RandomAccessIterator) */
return fill_and_add(a,e);
}
\end{cprog}
\ccExample
We give a second example for the more advanced \stl\ user. We stated
that iterators allow us to work with different data structures in a
unform manner. But the function \ccStyle{fill_and_add} in the
previous example only takes pointers as argument. Here we rewrite it
so that it takes any random access iterator as argument, provided it
has the right value type (\ccStyle{V}).
\begin{cprog}
template <class RandomAccessIterator>
float fill_and_add(RandomAccessIterator b, RandomAccessIterator e)
{
RandomAccessIterator c;
float sum;
for (int i=0; i<e-b; i++)
b[i].val = i*i/2.0;
for (c=b; c != e; ++c)
sum += (*c).val;
return sum;
}
\end{cprog}
\end{ccClass}
\begin{ccClass}{input_iterator}
\ccSection{Input Iterator}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of an input iterator
for the value type \ccStyle{T}, supports the following operations.
Algorithms on input iterators should never attempt to pass through the
same iterator twice. They should be single pass algorithms.
\ccCreation
\ccCreationVariable{it}
\ccConstructor{iterator(const iterator& it1);}
{}
\ccOperations
\ccMethod{iterator& operator=(const iterator &it1);}
{Assignment.}
\ccMethod{T operator*();}
{Returns the value of the iterator.
\ccPrecond \ccVar\ is dereferenceable.}
\ccMethod{iterator& operator++();}
{Prefix increment operation.
\ccPrecond \ccVar\ is dereferenceable.}
\ccMethod{iterator operator++(int);}
{Postfix increment operation. The result is the same as that of
\ccStyle{(void)++it;}.
\ccPrecond \ccVar\ is dereferenceable.}
\ccExample
The following code fragment reads numbers of the type \ccc{double}
from \ccc{cin} and computes their sum. The {\sc Stl} provides an
\ccc{istream_iterator} that fulfills the input iterator requirements.
As the iterator is a kind of file pointer it should be clear
why only single pass algorithms can be applied on this iterator.
\begin{cprog}
{
istream_iterator<double> it(cin),
end();
double sum = 0.0;
while(it != end){
sum += *it;
++it;
}
cout << sum << endl;
}
\end{cprog}
\end{ccClass}
\begin{ccClass}{output_iterator}
\ccSection{Output Iterator}
\ccDefinition
A class \ccClassName\ that satisfies the requirements of an output iterator
for the value type \ccStyle{T}, supports the following operations.
Algorithms on input iterators should never attempt to pass through the
same iterator twice. They should be single pass algorithms.
\ccCreation
\ccCreationVariable{it}
\ccConstructor{iterator();}
{}
\ccConstructor{iterator(const iterator& it1);}
{}
\ccOperations
\ccMethod{iterator& operator=(const iterator &it1);}
{Assignment.}
\ccMethod{bool operator==(const iterator &it1) const;}
{Test for equality: Two iterators are equal if they refer to the same item.}
\ccMethod{bool operator!=(const iterator &it1) const;}
{Test for inequality. The result is the same as \ccStyle{!(it == it1)}.}
\ccMethod{T& operator*();}
{Returns a reference to the value of the iterator. This operator can
only be used in order to assign a value to this reference.}
\ccMethod{iterator& operator++();}
{Prefix increment operation.
\ccPrecond \ccVar\ is dereferenceable.}
\ccMethod{void operator++(int);}
{Postfix increment operation. The result is the same as that of
\ccStyle{iterator tmp = it; ++it; return tmp;}.
\ccPrecond \ccVar\ is dereferenceable.}
\ccExample
The following code fragment reads numbers of the type \ccc{double}
from \ccc{cin} and computes their sum. The {\sc Stl} provides an
\ccc{ostream_iterator} that fulfills the output iterator requirements.
As the iterator is a kind of file pointer it should be clear
why only single pass algorithms can be applied on this iterator.
\begin{cprog}
{
ostream_iterator<double> it(cout);
for(int r = 0; r < 10; r++){
*it = 3.1415 * r * r;
++it;
}
}
\end{cprog}
The above code fragment is equivalent to:
\begin{cprog}
{
for(int r = 0; r < 10; r++){
cout << 3.1415 * r * r;
}
}
\end{cprog}
The use of output iterators is better illustrated with a function
that can write into arbitrary containers:
\begin{cprog}
template < class OutputIterator >
void
generator(OutputIterator it)
{
for(int r = 0; r < 10; r++){
*it = 3.1415 * r * r;
++it;
}
}
\end{cprog}
and here comes its usage.
\begin{cprog}
{
ostream_iterator<double> it(cout);
generator(it);
double R[10];
generator(R);
}
\end{cprog}
Note that the memory where the function \ccc{generator} writes to
must be allocated. If you want to insert the generated doubles at the end
of a list you have to use a \ccc{back_insert_iterator}. To explain
this is out of the scope of this introduction to the {\sc Stl}. Please
refer to the {\sc Stl} reference manuals.
\end{ccClass}

56
Manual/doc_tex/Use_of_Stl/Preliminaries.tex
View File

@ -1,56 +0,0 @@
\cleardoublepage
\chapter{Preliminaries}
\ccHtmlNoClassLinks
\begin{ccClassTemplate}{pair<T1, T2>}
\ccSection{Pair}
\ccDefinition
A struct \ccClassName\ is a heterogeneous pair of values. Its data members
are \ccStyle{first} and \ccStyle{second}.
\ccHtmlLinksOff
\ccInclude{pair}
\ccHtmlLinksOn
\ccCreation
\ccCreationVariable{p}
\ccConstructor{pair(const T1& x, const T2& y);}
{Introduces a pair.}
\ccOperations
\ccGlobalFunction{template <class T1, class T2>
bool operator==(const pair<T1,T2> &p, const pair<T1,T2> &p1) const;}
{Test for equality: Two pairs are equal, iff their data members are equal.}
\ccGlobalFunction{template <class T1, class T2>
bool operator<(const pair<T1,T2> &p,
const pair<T1,T2> &p1) const;}
{Lexicographical comparison of two pairs.}
\ccExample
\begin{cprog}
Employee irene("Irene", "Eneri");
Employee leo("Leonard", "Eneri");
typedef int Social_security_number;
pair<Social_security_number, Employee> p1(7812, irene), p2(5555, leo);
assert( p1.first == 7812 );
assert( p2.second == leo );
\end{cprog}
\end{ccClassTemplate}

14
Manual/doc_tex/Use_of_Stl/SequenceContainer.tex
View File

@ -1,14 +0,0 @@
\cleardoublepage
\chapter{Sequence Containers}
Sequence containers are objects that store other objects of a single type,
organized in a strictly linear arrangement.
\input{Use_of_Stl/list}
\newpage
\input{Use_of_Stl/vector}
\newpage
\input{Use_of_Stl/deque}

150
Manual/doc_tex/Use_of_Stl/deque.tex
View File

@ -1,150 +0,0 @@
\ccHtmlNoClassLinks
\begin{ccClassTemplate} {deque<T>}
\ccSection{deque}
\ccDefinition
An object of the class \ccClassName\ is a sequence that supports
random access iterators. In addition it supports
constant time insert and erase operations at both ends. Insert and erase
in the middle take linear time.
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{deque}
\ccHtmlLinksOn
\ccTypes
\ccNestedType{iterator}{A mutable random access iterator.}
\ccNestedType{const_iterator}{A const random access iterator.}
\ccCreation
\ccCreationVariable{D}
\ccConstructor{deque();}
{Introduces an empty deque.}
\ccConstructor{deque(const deque<T> &q);}
{Copy constructor.}
\ccConstructor{deque(int n, const T& t = T() );}
{Introduces a deque with $n$ items, all initialized to $t$.}
\ccOperations
\ccSetTwoOfThreeColumns{3.5cm}{3.1cm}
\ccMethod{deque<T> & operator=(const deque<T> &D1);}
{Assignment.}
\ccMethod{bool operator==(const deque<T> &D1) const;}
{Test for equality: Two deques are equal, iff they have the same size
and if their corresponding elements are equal.}
\ccMethod{bool operator!=(const deque<T> &D1) const;}
{Test for inequality.}
\ccMethod{bool operator<(const deque<T> &D1) const;}
{Test for lexicographically smaller.}
\ccMethod{iterator begin();}
{Returns a mutable iterator referring to the first element in
deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const_iterator begin() const;}
{Returns a constant iterator referring to the first element in
deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{iterator end();}
{Returns a mutable iterator which is the past-end-value of
deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const_iterator end() const;}
{Returns a constant iterator which is the past-end-value of
deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{bool empty() const;}
{Returns \ccStyle{true} if \ccVar\ is empty.}
\ccMethod{int size() const;}
{Returns the number of items in deque~\ccVar.}
\ccMethod{T& operator[](int pos);}
{Random access operator.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const T& operator[](int pos) const;}
{Random access operator.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{T& front();}
{Returns a reference to the first item in deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const T& front() const;}
{Returns a const reference to the first item in deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{T& back();}
{Returns a reference to the last item in deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const T& back() const;}
{Returns a const reference to the last item in deque~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\subsubsection*{Insert and Erase}
\ccMethod{void push_front(const T&);}
{Inserts an item at the beginning of deque~\ccVar.}
\ccMethod{void push_back(const T&);}
{Inserts an item at the end of deque~\ccVar.}
\ccMethod{iterator insert(iterator pos, const T& t = T());}
{Inserts a copy of \ccStyle{t} in front of iterator \ccStyle{pos}.
The return value points to the inserted item.}
\ccMethod{iterator insert(iterator pos,
int n, const T& t = T());}
{Inserts $n$ copy of \ccStyle{t} in front of iterator \ccStyle{pos}.
The return value points to the inserted item.}
\ccMethod{void insert(iterator pos,
const_iterator first,
const_iterator last);}
{Inserts a copy of the range $\left[\right.$\ccStyle{first}, \ccStyle{last}$\left.\right)$
in front of iterator \ccStyle{pos}.}
\ccMethod{void pop_front();}
{Removes the first item from deque~\ccVar.}
\ccMethod{void pop_back();}
{Removes the last item from deque~\ccVar.}
\ccMethod{void erase(iterator pos);}
{Removes the item from deque~\ccVar, where \ccStyle{pos} refers to.}
\ccMethod{void erase(iterator first,
iterator last);}
{Removes the items in the range$\left[\right.$\ccStyle{first},
\ccStyle{last}$\left.\right)$ from deque ~\ccVar.}
\end{ccClassTemplate}

32
Manual/doc_tex/Use_of_Stl/introduction.tex
View File

@ -1,32 +0,0 @@
\cleardoublepage
\chapter{Introduction}
\cgal\ is the {\em Computational Geometry Algorithms Library} that is
developed by the {\sc Esprit} project \cgal.
The library is written in \CC\ and makes heavily use of {\em templates},
which are a means to obtain generic code.
\stl\ is the Standard Template Library. Its main components are {\em
containers}, {\em algorithms}, {\em iterators} and {\em function
objects}. This library is part of the ISO \CC\ standard
\cite{cgal:ansi-is14882-98}.
\stl\ is more than a library, it is a framework and a programming paradigm
which was adopted by the \cgal\ project for its library of geometric
algorithms.
This document describes in a simplified way the basic features of \stl.
After reading this document you should be able to use these features
which are used throughout the \cgal\ library.
This document is neither a reference manual nor a tutorial for \stl.
For the sake of simplicity we sometimes sacrifice exactness.
If you compare what is written in this document with what is written
in the reference manual you will see that in reality things are
slightly more general and hence slightly more complicated.
If you want to develop your own iterators or containers, this is
definitely the wrong document for you.
We recommend to have a look at the header files themselves as the code is
extremely instructive.

133
Manual/doc_tex/Use_of_Stl/list.tex
View File

@ -1,133 +0,0 @@
\ccHtmlNoClassLinks
\begin{ccClassTemplate} {list<T>}
\ccSection{list}
\ccDefinition
An object of the class \ccClassName\ is a sequence that supports
bidirectional iterators and allows constant time insert and erase
operations anywhere within the sequence.
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{list}
\ccHtmlLinksOn
\ccTypes
\ccNestedType{iterator}{A mutable bidirectional iterator.}
\ccNestedType{const_iterator}{A const bidirectional iterator.}
\ccCreation
\ccCreationVariable{L}
\ccConstructor{list();}
{Introduces an empty list.}
\ccConstructor{list(const list<T> &q);}
{Copy constructor.}
\ccConstructor{list(int n, const T& t = T() );}
{Introduces a list with $n$ items, all initialized to $t$.}
\ccOperations
\ccMethod{list<T> & operator=(const list<T> &L1);}
{Assignment.}
\ccMethod{bool operator==(const list<T> &L1) const;}
{Test for equality: Two lists are equal, iff they have the same size
and if their corresponding elements are equal.}
\ccMethod{bool operator!=(const list<T> &L1) const;}
{Test for inequality.}
\ccMethod{iterator begin();}
{Returns a mutable iterator referring to the first element in
list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const_iterator begin() const;}
{Returns a constant iterator referring to the first element in
list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{iterator end();}
{Returns a mutable iterator which is the past-end-value of
list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const_iterator end() const;}
{Returns a constant iterator which is the past-end-value of
list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{bool empty() const;}
{Returns \ccStyle{true} if \ccVar\ is empty.}
\ccMethod{int size() const;}
{Returns the number of items in list~\ccVar.}
\ccMethod{T& front();}
{Returns a reference to the first item in list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const T& front() const;}
{Returns a const reference to the first item in list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{T& back();}
{Returns a reference to the last item in list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const T& back() const;}
{Returns a const reference to the last item in list~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccHeading{Insertion}
\ccMethod{void push_front(const T&);}
{Inserts an item in front of list~\ccVar.}
\ccMethod{void push_back(const T&);}
{Inserts an item at the back of list~\ccVar.}
\ccMethod{iterator insert(iterator pos, const T& t);}
{Inserts a copy of \ccStyle{t} in front of iterator \ccStyle{pos}.
The return value points to the inserted item.}
\ccMethod{void insert(iterator pos,
int n, const T& t = T());}
{Inserts $n$ copies of \ccStyle{t} in front of iterator \ccStyle{pos}.}
\ccMethod{void insert(iterator pos,
const_iterator first,
const_iterator last);}
{Inserts a copy of the range $\left[\right.$\ccStyle{first}, \ccStyle{last}$\left.\right)$
in front of iterator \ccStyle{pos}.}
\ccHeading{Removal}
\ccMethod{void pop_front();}
{Removes the first item from list~\ccVar.}
\ccMethod{void pop_back();}
{Removes the last item from list~\ccVar.}
\ccMethod{void erase(iterator pos);}
{Removes the item from list~\ccVar, where \ccStyle{pos} refers to.}
\ccMethod{void erase(iterator first,
iterator last);}
{Removes the items in the range$\left[\right.$\ccStyle{first},
\ccStyle{last}$\left.\right)$ from list~\ccVar.}
\end{ccClassTemplate}

27
Manual/doc_tex/Use_of_Stl/main.tex
View File

@ -1,27 +0,0 @@
% Manual/doc_tex/Use_of_Stl/main.tex
% --------------------------------------------------------
% several chapters
\renewcommand{\cgalColumnLayout}{\ccTexHtml{%
\ccSetThreeColumns{Oriented_side}{}{\hspace*{8.5cm}}
\ccPropagateThreeToTwoColumns}{}}
\renewcommand{\ccTagRmEigenClassName}{\ccFalse}
\input{Use_of_Stl/preface}
\input{Use_of_Stl/introduction}
\input{Use_of_Stl/Preliminaries}
\input{Use_of_Stl/Iterator}
\input{Use_of_Stl/Circulator_stl}
\input{Use_of_Stl/FunctionObject}
\input{Use_of_Stl/SequenceContainer}
\input{Use_of_Stl/AssociativeContainer}
% EOF

113
Manual/doc_tex/Use_of_Stl/map.tex
View File

@ -1,113 +0,0 @@
\ccHtmlNoClassLinks
\begin{ccClassTemplate} {map<Key, T, Compare>}
\ccSection{map}
\ccDefinition
An object of the class \ccClassTemplateName\ supports unique keys of
type \ccStyle{Key}, and provides retrieval of values of type \ccStyle{T}
based on the keys. The keys into the map are ordered by the ordering
relation \ccStyle{Compare}.
Elements are stored in maps as \ccStyle{pairs} of \ccStyle{Key} and
\ccStyle{T}.
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{map}
\ccHtmlLinksOn
\ccTypes
\ccNestedType{iterator}{A const bidirectional iterator.}
\ccCreation
\ccCreationVariable{M}
\ccConstructor{map(const Compare& comp = Compare());}
{Introduces an empty map.}
\ccConstructor{map(const map<Key, T, Compare> &M1);}
{Copy constructor.}
\ccOperations
\ccMethod{map<Key, T, Compare> & operator=(const map<Key, T, Compare> &M1);}
{Assignment.}
\ccMethod{bool operator==(const map<Key, T, Compare> &M1);}
{Equality test: Two maps are equal, if the sequences \ccVar\ and \ccStyle{M1}
are elementwise equal.}
\ccMethod{bool operator<(const map<Key, T, Compare> &M1);}
{Returns \ccStyle{true} if \ccVar\ is lexicographically less than \ccStyle{M1},
\ccStyle{false} otherwise.}
\ccMethod{iterator begin() const;}
{Returns a constant iterator referring to the first element in
map~\ccVar.}
\ccMethod{iterator end() const;}
{Returns a constant past-the-end iterator of map~\ccVar.}
\ccMethod{bool empty() const;}
{Returns \ccStyle{true} if \ccVar\ is empty.}
\ccMethod{int size() const;}
{Returns the number of items in map~\ccVar.}
\ccMethod{T& operator[](const Key& k);}
{Returns a reference to the type \ccStyle{T} value associated with
key \ccStyle{k}. If the map is constant then a const reference is
returned. In contrast to vector or deque, the \ccStyle{pair(k,T())}
is inserted into the map, if no element is associated with the key.}
\ccHeading{Insert and Erase}
\ccMethod{iterator insert(iterator pos, pair<const Key&,T> val);}
{Inserts \ccStyle{val} into the map if \ccStyle{val} is not already
present in \ccVar. The iterator \ccStyle{pos} is the starting point of
the search. The return value points to the inserted item.}
\ccMethod{pair<iterator, bool> insert(pair<const Key&,T> val);}
{Inserts \ccStyle{val} into the map if \ccStyle{val} is not already
present in \ccVar. Returns a pair, where \ccStyle{first}
is the iterator that points to the inserted item or to the
item that is already present in \ccVar, and where \ccStyle{second}
is \ccStyle{true} if the insertion took place.}
\ccMethod{void erase(iterator pos);}
{Erases the element where pos points to.}
\ccMethod{int erase(Key k);}
{Erases all elements that equal \ccStyle{k}. Returns the number
of erased elements.}
\ccHeading{Miscellaneous}
\ccMethod{iterator find(Key k);}
{Returns an iterator that either points to the element \ccStyle{k},
or \ccStyle{end()} if \ccStyle{k} is not present in map \ccVar.}
\ccMethod{int count(Key k);}
{Returns the number of occurrences of \ccStyle{k} in map \ccVar.}
\ccMethod{iterator lower_bound(Key k);}
{Returns an iterator that points to the first element of \ccVar\
that is not less than \ccStyle{k}. If all elements are less than
\ccStyle{k} then \ccStyle{end()} is returned. If \ccStyle{k}
is present in the map the returned iterator points to \ccStyle{k}.}
\ccMethod{iterator upper_bound(Key k);}
{Returns an iterator that points to the first element of the map
that is greater than \ccStyle{k}. If no element is greater than
\ccStyle{k} then \ccStyle{end()} is returned. If \ccStyle{k}
is present in the map the returned iterator points to \ccStyle{k}.}
\end{ccClassTemplate}

46
Manual/doc_tex/Use_of_Stl/multimap.tex
View File

@ -1,46 +0,0 @@
\ccHtmlNoClassLinks
\begin{ccClassTemplate} {multimap<Key, T, Compare>}
\ccSection{multimap}
\ccDefinition
An object of the class \ccClassTemplateName\ can store multiple
equivalent keys of type \ccStyle{Key}, and provides retrieval of
values of type \ccStyle{T} based on the keys. The keys in the multimap
are ordered by the ordering relation \ccStyle{Compare}.
The interface of the class \ccClassTemplateName\ is almost the same as of
the class \ccStyle{map<Key, Compare>}. We only list the functions
that have a different syntax or semantics.
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{map}
\ccHtmlLinksOn
\ccTypes
\ccNestedType{iterator}{A const bidirectional iterator.}
\ccCreationVariable{M}
\ccOperations
\ccMethod{iterator insert(iterator pos,
const pair<constKey,T>& val);}
{Inserts \ccStyle{val} in the set. The iterator \ccStyle{pos} is the starting
point of the search. The return value points to the inserted item.}
\ccMethod{iterator insert(const pair<constKey,T>& val);}
{Inserts \ccStyle{val} in the set. Returns an iterator that points to the
inserted item.}
\ccMethod{void erase(iterator pos);}
{Erases the element where pos points to. This erases only one element}
\ccMethod{int erase(Key k);}
{Erases all elements that are equal to \ccStyle{k}. Returns the number
of erased elements.}
\end{ccClassTemplate}

44
Manual/doc_tex/Use_of_Stl/multiset.tex
View File

@ -1,44 +0,0 @@
\ccHtmlNoClassLinks
\begin{ccClassTemplate} {multiset<Key, Compare>}
\ccSection{multiset}
\ccDefinition
An object of the class \ccClassTemplateName\ can store multiple copies
of the same element of type \ccStyle{Key}. The elements in the
multiset are ordered by the ordering relation \ccStyle{Compare}.
The interface of the class \ccClassTemplateName\ is almost the same as of
the class \ccStyle{set<Key, Compare>}. We only list the functions
that have a different syntax or semantics.
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{set}
\ccHtmlLinksOn
\ccTypes
\ccNestedType{iterator}{A const bidirectional iterator.}
\ccCreationVariable{M}
\ccOperations
\ccMethod{iterator insert(iterator pos,
const Key& k);}
{Inserts \ccStyle{k} in the set. The iterator \ccStyle{pos} is the starting
point of the search. The return value points to the inserted item.}
\ccMethod{iterator insert(const Key& k);}
{Inserts \ccStyle{k} in the set. Returns an iterator that points to the
inserted item.}
\ccMethod{void erase(iterator pos);}
{Erases the element where pos points to. This erases only one element}
\ccMethod{int erase(Key k);}
{Erases all elements that are equal to \ccStyle{k}. Returns the number
of erased elements.}
\end{ccClassTemplate}

43
Manual/doc_tex/Use_of_Stl/preface.tex
View File

@ -1,43 +0,0 @@
\lcTex{\chapter*{Preface}}
\lcHtml{\chapter{Preface}}
\cgal\ is a {\em Computational Geometry Algorithms Library} written in \CC,
developed by a consortium consisting of
\ccAnchor{http://www.inf.ethz.ch/}{ETH Z\"urich} (Switzerland),
\ccAnchor{http://www.inf.fu-berlin.de/}{Freie Universit{\"a}t Berlin} (Germany),
\ccAnchor{http://www-sop.inria.fr/geometrica/}{{\sc Inria}
Sophia-Antipolis} (France),
\ccAnchor{http://www.informatik.uni-halle.de/}{Martin-Luther-Universit{\"a}t
Halle-Wittenberg} (Germany),
\ccAnchor{http://www.mpi-sb.mpg.de/}{Max-Planck Institut f{\"u}r Informatik},
Saarbr\"ucken (Germany),
\ccAnchor{http://info.risc.uni-linz.ac.at/}{{\sc Risc}} Linz (Austria)
\ccAnchor{http://www.math.tau.ac.il/}{Tel-Aviv University} (Israel), and
\ccAnchor{http://www.cs.uu.nl/}{Utrecht University} (The Netherlands).
You can find more information about the project on the
\ccAnchor{http://www.cgal.org}{\cgal\ home page}
\ccTexHtml{at URL {\tt http://www.cgal.org}}{}.
Should you have any questions, comments, remarks or criticism concerning
\cgal, please send a message to the email adresses specified on our web site.
\section*{Editorial Committee}
\input{Manual/editors}
\section*{Authors}
Lutz Kettner (ETH Z\"urich)\\
Andreas Fabri ({\sc Inria} Sophia-Antipolis).
\section*{Acknowledgement}
This work was supported
by the ESPRIT IV Long Term Research Projects No.~21957 (CGAL)
and No.~28155 (GALIA).
%\cleardoublepage

101
Manual/doc_tex/Use_of_Stl/set.tex
View File

@ -1,101 +0,0 @@
\ccHtmlNoClassLinks
\begin{ccClassTemplate} {set<Key, Compare>}
\ccSection{set}
\ccDefinition
An object of the class \ccClassTemplateName\ stores unique elements of
type \ccStyle{Key}. It allows for the retrieval for the elements
themselves. The elements in the set are ordered by the ordering
relation \ccStyle{Compare}.
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{set}
\ccHtmlLinksOn
\ccTypes
\ccNestedType{iterator}{A const bidirectional iterator.}
\ccCreation
\ccCreationVariable{S}
\ccConstructor{set(const Compare& comp = Compare());}
{Introduces an empty set.}
\ccConstructor{set(const set<Key, Compare> &S1);}
{Copy constructor.}
\ccOperations
\ccMethod{set<Key, Compare> & operator=(const set<Key, Compare> &S1);}
{Assignment.}
\ccMethod{bool operator==(const set<Key, Compare> &S1);}
{Equality test: Two sets are equal, if the sequences \ccVar\ and \ccStyle{S1}
are elementwise equal.}
\ccMethod{bool operator<(const set<Key, Compare> &S1);}
{Returns \ccStyle{true} if \ccVar\ is lexicographically less than \ccStyle{S1},
\ccStyle{false} otherwise.}
\ccMethod{set<Key, Compare>::iterator begin() const;}
{Returns a constant iterator referring to the first element in
set~\ccVar.}
\ccMethod{set<Key, Compare>::iterator end() const;}
{Returns a constant past-the-end iterator of set~\ccVar.}
\ccMethod{bool empty() const;}
{Returns \ccStyle{true} if \ccVar\ is empty.}
\ccMethod{int size() const;}
{Returns the number of items in set~\ccVar.}
\ccHeading{Insert and Erase}
\ccMethod{set<Key, Compare>::iterator insert(set<Key, Compare>::iterator pos,
const Key& k);}
{Inserts \ccStyle{k} in the set if \ccStyle{k} is not already
present in \ccVar. The iterator \ccStyle{pos} is the starting point of
the search. The return value points to the inserted item.}
\ccMethod{pair<set<Key, Compare>::iterator, bool> insert(const Key& k);}
{Inserts \ccStyle{k} in the set if \ccStyle{k} is not already
present in \ccVar. Returns a pair, where \ccStyle{first}
is the iterator that points to the inserted item or to the
item that is already present in \ccVar, and where \ccStyle{second}
is \ccStyle{true} if the insertion took place.}
\ccMethod{void erase(set<Key, Compare>::iterator pos);}
{Erases the element where pos points to.}
\ccMethod{int erase(Key k);}
{Erases the element \ccStyle{k}, if present. Returns the number
of erased elements.}
\ccHeading{Miscellaneous}
\ccMethod{set<Key, Compare>::iterator find(Key k);}
{Returns an iterator that either points to the element \ccStyle{k},
or \ccStyle{end()} if \ccStyle{k} is not present in set \ccVar.}
\ccMethod{int count(Key k);}
{Returns the number of occurrences of \ccStyle{k} in set \ccVar.}
\ccMethod{set<Key, Compare>::iterator lower_bound(Key k);}
{Returns an iterator that points to the first element of \ccVar\
that is not less than \ccStyle{k}. If all elements are less than
\ccStyle{k} then \ccStyle{end()} is returned. If \ccStyle{k}
is present in the set the returned iterator points to \ccStyle{k}.}
\ccMethod{set<Key, Compare>::iterator upper_bound(Key k);}
{Returns an iterator that points to the first element of the set
that is greater than \ccStyle{k}. If no element is greater than
\ccStyle{k} then \ccStyle{end()} is returned.}
\end{ccClassTemplate}

51
Manual/doc_tex/Use_of_Stl/use_of_stl_manual.tex
View File

@ -1,51 +0,0 @@
% +------------------------------------------------------------------------+
% | Manual/doc_tex/use_of_stl_manual.tex
% +------------------------------------------------------------------------+
\documentclass{book}
\usepackage{Manual/cgal_manual}
\lcHtml{\lcOneColumnToc}
\gdef\lciManualTitle{The Use of STL and STL Extensions in CGAL}%
\renewcommand{\cgalColumnLayout}{\ccTexHtml{%
\ccSetThreeColumns{Oriented_side}{}{\hspace*{8.5cm}}
\ccPropagateThreeToTwoColumns}{}}
\renewcommand{\ccTagRmEigenClassName}{\ccFalse}
\makeindex
\begin{document}
\cgaltitlepage{The Use of STL\\and\\STL Extensions in CGAL}
\cleardoublepage
\pagenumbering{roman}
\setcounter{page}{1}
\input{Use_of_Stl/preface}
\cleardoublepage
\tableofcontents
\cleardoublepage
\pagenumbering{arabic}
\setcounter{page}{1}
\input{Use_of_Stl/introduction}
\input{Use_of_Stl/Preliminaries}
\input{Use_of_Stl/Iterator}
\input{Use_of_Stl/Circulator_stl}
\input{Use_of_Stl/FunctionObject}
\input{Use_of_Stl/SequenceContainer}
\input{Use_of_Stl/AssociativeContainer}
\bibliographystyle{alpha}
\bibliography{Manual/cgal_manual,Manual/geom}
\printindex
\end{document}

139
Manual/doc_tex/Use_of_Stl/vector.tex
View File

@ -1,139 +0,0 @@
\ccHtmlNoClassLinks
\begin{ccClassTemplate} {vector<T>}
\ccSection{vector}
\ccDefinition
An object of the class \ccClassName\ is a sequence that supports
random access iterators. In addition it supports (amortized)
constant time insert and erase operations at the end. Insert and erase
in the middle take linear time.
% prevent dead links to non-CGAL include files
\ccHtmlLinksOff
\ccInclude{vector}
\ccHtmlLinksOn
\ccTypes
\ccNestedType{iterator}{A mutable random access iterator.}
\ccNestedType{const_iterator}{A const random access iterator.}
\ccCreation
\ccCreationVariable{V}
\ccConstructor{vector();}
{Introduces an empty vector.}
\ccConstructor{vector(const vector<T> &q);}
{Copy constructor.}
\ccConstructor{vector(int n, const T& t = T() );}
{Introduces a vector with $n$ items, all initialized to $t$.}
\ccOperations
\ccMethod{vector<T> & operator=(const vector<T> &V1);}
{Assignment.}
\ccMethod{bool operator==(const vector<T> &V1) const;}
{Test for equality: Two vectors are equal, iff they have the same size
and if their corresponding elements are equal.}
\ccMethod{bool operator!=(const vector<T> &V1) const;}
{Test for inequality.}
\ccMethod{bool operator<(const vector<T> &V1) const;}
{Test for lexicographically smaller.}
\ccMethod{iterator begin();}
{Returns a mutable iterator referring to the first element in
vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const_iterator begin() const;}
{Returns a constant iterator referring to the first element in
vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{iterator end();}
{Returns a mutable iterator which is the past-end-value of
vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const_iterator end() const;}
{Returns a constant iterator which is the past-end-value of
vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{bool empty() const;}
{Returns \ccStyle{true} if \ccVar\ is empty.}
\ccMethod{int size() const;}
{Returns the number of items in vector~\ccVar.}
\ccMethod{T& operator[](int pos);}
{Random access operator.}
\ccMethod{const T& operator[](int pos) const;}
{Random access operator.}
\ccMethod{T& front();}
{Returns a reference to the first item in vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const T& front() const;}
{Returns a const reference to the first item in vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\ccMethod{T& back();}
{Returns a reference to the last item in vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccFalse}
\ccMethod{const T& back() const;}
{Returns a const reference to the last item in vector~\ccVar.}
\renewcommand{\ccTagRmTrailingConst}{\ccTrue}
\subsubsection*{Insert and Erase}
\ccMethod{void push_back(const T&);}
{Inserts an item at the back of vector~\ccVar.}
\ccMethod{iterator insert(iterator pos,
const T& t);}
{Inserts a copy of \ccStyle{t} in front of iterator \ccStyle{pos}.
The return value points to the inserted item.}
\ccMethod{void insert(iterator pos,
int n, const T& t = T());}
{Inserts $n$ copy of \ccStyle{t} in front of iterator \ccStyle{pos}.}
\ccMethod{void insert(iterator pos,
const_iterator first,
const_iterator last);}
{Inserts a copy of the range $\left[\right.$\ccStyle{first}, \ccStyle{last}$\left.\right)$
in front of iterator \ccStyle{pos}.}
\ccMethod{void pop_back();}
{Removes the last item from vector~\ccVar.}
\ccMethod{void erase(iterator pos);}
{Removes the item from vector~\ccVar, where \ccStyle{pos} refers to.}
\ccMethod{void erase(iterator first,
iterator last);}
{Removes the items in the range$\left[\right.$\ccStyle{first},
\ccStyle{last}$\left.\right)$ from vector~\ccVar.}
\end{ccClassTemplate}