mirror of https://github.com/CGAL/cgal
236 lines
11 KiB
TeX
236 lines
11 KiB
TeX
%% =============================================================================
|
|
%% The CGAL Reference Manual
|
|
%% Chapter: STL Extensions - Introduction
|
|
%% -----------------------------------------------------------------------------
|
|
%% file : doc_tex/support/STL_Extension/STL_Extension_ref/intro.tex
|
|
%% author: Michael Hoffmann, Lutz Kettner
|
|
%% -----------------------------------------------------------------------------
|
|
%% $CGAL_Chapter: STL_Extension $
|
|
%% $Revision$
|
|
%% $Date$
|
|
%% =============================================================================
|
|
|
|
\chapter{STL Extensions for CGAL}
|
|
\label{chapterDataStructures}\label{chapterStlExtensions}
|
|
|
|
\RCSdef{\stlExtensionRev}{$Revision$}
|
|
\RCSdefDate{\stlExtensionDate}{$Date$}
|
|
\ccChapterRelease{\stlExtensionRev. \ \stlExtensionDate}
|
|
\ccChapterAuthor{Michael Hoffmann, Lutz Kettner, Sylvain Pion, and Ron Wein}
|
|
|
|
%% +=========================================================================+
|
|
|
|
\section*{Introduction}
|
|
|
|
\cgal\ is designed in the spirit of the generic programming paradigm
|
|
to work together with the Standard Template Library (\stl)
|
|
\cite{cgal:ansi-is14882-98,cgal:a-gps-98}. This chapter documents non-geometric
|
|
\stl-like components that are not provided in the \stl\ standard but
|
|
in \cgal: a doubly-connected list managing items in place (where
|
|
inserted items are not copied), a compact container, a multi-set class that
|
|
uses three-valued comparisons and offers additional functionality,
|
|
generic algorithms, iterators, functor adaptors for binding and swapping
|
|
arguments and for composition, functors for projection and creation and
|
|
adaptor classes around iterators and circulators. See also circulators in
|
|
Chapter~\ref{chapterCirculators}.
|
|
|
|
\subsection*{Doubly-Connected List Managing Items in Place.}
|
|
|
|
The class \ccStyle{In_place_list<T,bool>} manages a
|
|
sequence of items in place in a doubly-connected list. Its goals are
|
|
the flexible handling of memory management and performance
|
|
optimization. The item type has to provide the two necessary
|
|
pointers \ccc{&T::next_link} and \ccc{&T::prev_link}. One possibility
|
|
to obtain these pointers is to inherit them from the base class
|
|
\ccStyle{In_place_list_base<T>}.
|
|
|
|
The class \ccStyle{In_place_list<T,bool>} is a container quite similar
|
|
to \stl\ containers, with the advantage that it is able to handle the
|
|
stored elements by reference instead of copying them. It is possible
|
|
to delete an element only knowing its address and no iterator to it.
|
|
This used to simplify mutually pointered data structures like a halfedge
|
|
data structure for planar maps or polyhedral surfaces (the current design
|
|
does not need this anymore). The usual iterators are also available.
|
|
|
|
\ccRefIdfierPage{CGAL::In_place_list<T,bool>}\\
|
|
\ccRefIdfierPage{CGAL::In_place_list_base<T>}
|
|
|
|
\subsection*{Compact container.}
|
|
|
|
The class \ccStyle{Compact_container<T, Allocator>} is an \stl\ like container
|
|
which provides a very compact storage for its elements. It achieves this goal
|
|
by requiring \ccc{T} to provide access to a pointer in it, which is going to be
|
|
used by \ccStyle{Compact_container<T, Allocator>} for its internal management.
|
|
The traits class \ccStyle{Compact_container_traits<T>} specifies the way to
|
|
access that pointer. The class \ccStyle{Compact_container_base} can be
|
|
used as a base class to provide the pointer, although in this case you do not
|
|
get the most compact representation. The values that this pointer can have
|
|
during valid use of the object are valid pointer values to 4 bytes aligned
|
|
objects (i.e., the two least significant bits of the pointer need to be zero
|
|
when the object is constructed). Another interesting property of this
|
|
container is that iterators are not invalidated during \ccc{insert} or
|
|
\ccc{erase} operations.
|
|
|
|
The main deviation from the \stl\ container concept is that the \ccc{++} and
|
|
\ccc{--} operators of the iterator do not have a constant time complexity in
|
|
all cases. The actual complexity is related to the maximum size that the
|
|
container has had during its life time compared to its current size, because
|
|
the iterator has to go over the "erased" elements as well, so the bad case is
|
|
when the container used to contain lots of elements, but now has far less. In
|
|
this case, we suggest to do a copy of the container in order to "defragment"
|
|
the internal representation.
|
|
|
|
This container has been developed in order to efficiently handle large data
|
|
structures like the triangulation and halfedge data structures. It can
|
|
probably be useful for other kinds of graphs as well.
|
|
|
|
\ccRefIdfierPage{CGAL::Compact_container<T, Allocator>}\\
|
|
\ccRefIdfierPage{CGAL::Compact_container_traits<T>}\\
|
|
\ccRefIdfierPage{CGAL::Compact_container_base}
|
|
|
|
\subsection*{Multiset with Extended Functionality.}
|
|
|
|
The class \ccStyle{Multiset<Type,Compare,Allocator>} represents a
|
|
multi-set of elements of type \ccc{Type}, represented as a red-black tree
|
|
(see~\cite[Chapter~13]{clrs-ia-01} for an excellent introduction to red-black
|
|
trees). It differs from the \stl's \ccc{multiset} class-template mainly due
|
|
to the fact that it is parameterized by a comparison functor \ccc{Compare}
|
|
that returns the three-valued \ccc{Comparison_result} (namely it returns
|
|
either \ccc{SMALLER}, \ccc{EQUAL}, or \ccc{LARGER}), rather than a {\em less}
|
|
functor returning \ccc{bool}. Thus, it is possible to maintain
|
|
the underlying red-black tree with less invocations of the comparison functor,
|
|
which can considerably decrease running times, especially when comparing
|
|
elements of type \ccc{Type} is an expensive operation.
|
|
|
|
\ccStyle{Multiset<Type,Compare,Allocator>} also guarantees that the order of
|
|
elements sent to the comparison functor is fixed. For example, if we insert
|
|
a new element \ccc{x} into the set (or erase an element from the set), then
|
|
we always invoke \ccc{Compare() (x, y)} (and never \ccc{Compare() (y, x)}),
|
|
where \ccc{y} is an element already stored in the set. This behavior, not
|
|
supported by \ccc{std::multiset}, is sometimes crucial for designing more
|
|
efficient comparison predicates.
|
|
|
|
The interface of \ccStyle{Multiset<Type,Compare,Allocator>} is in general
|
|
derived from \ccc{std::multiset}. However, it extends the interface by
|
|
offering some additional operations, such as: inserting of an element into
|
|
the set given its {\em exact} position (and not just using an insertion hint);
|
|
looking up keys whose type may differ from \ccc{Type}, as long as users supply
|
|
a comparison functor \ccc{CompareKey}, between the keys and set elements;
|
|
and catenating and splitting sets.
|
|
|
|
\ccRefIdfierPage{CGAL::Multiset<Type,Compare,Allocator>}
|
|
|
|
|
|
\subsection*{Generic Algorithms.}
|
|
|
|
\ccRefIdfierPage{CGAL::copy_n}\\
|
|
\ccRefIdfierPage{CGAL::min_max_element}\\
|
|
%% Michael: I commented these, as I think they should be replaced by combining
|
|
%% Filter_iterator with std::min/max_element().
|
|
%%\ccRefIdfierPage{CGAL::min_element_if}\\
|
|
%%\ccRefIdfierPage{CGAL::max_element_if}\\
|
|
\ccRefIdfierPage{CGAL::predecessor}\\
|
|
\ccRefIdfierPage{CGAL::successor}
|
|
|
|
\subsection*{Iterators and Iterator/Circulator Adaptors.}
|
|
|
|
\ccRefIdfierPage{CGAL::Emptyset_iterator}\\
|
|
\ccRefIdfierPage{CGAL::Oneset_iterator<T>}\\
|
|
\ccRefIdfierPage{CGAL::Insert_iterator<Container>}\\
|
|
\ccRefIdfierPage{CGAL::Counting_iterator<Iterator, Value>}\\
|
|
\ccRefIdfierPage{CGAL::N_step_adaptor<I,int N>}\\
|
|
\ccRefIdfierPage{CGAL::Filter_iterator<Iterator, Predicate>}\\
|
|
\ccRefIdfierPage{CGAL::Join_input_iterator_1<Iterator, Creator>}\\
|
|
\ccRefIdfierPage{CGAL::Inverse_index<IC>}\\
|
|
\ccRefIdfierPage{CGAL::Random_access_adaptor<IC>}\\
|
|
\ccRefIdfierPage{CGAL::Random_access_value_adaptor<IC,T>}
|
|
|
|
\subsection*{Functor Adaptors.}
|
|
|
|
The standard library contains some adaptors for binding functors, that
|
|
is fixing one argument of a functor to a specific value thereby
|
|
creating a new functor that takes one argument less than the original
|
|
functor. Also, though non-standard, some STL implementations (such as
|
|
SGI) provide adaptors to compose function objects. Unfortunately,
|
|
these bind and compose adaptors are limited to unary and binary
|
|
functors only, and these functors must not be overloaded.
|
|
|
|
Since there are a number of functors in \cgal\ that take more than two
|
|
arguments, and since functors may also be overloaded, i.e., accept
|
|
several different sets of arguments, we have to define our own
|
|
adaptors to be used with \cgal\ functors.
|
|
|
|
\ccRefIdfierPage{CGAL::swap_1}\\
|
|
\ccRefIdfierPage{CGAL::swap_2}\\
|
|
\ccRefIdfierPage{CGAL::swap_3}\\
|
|
\ccRefIdfierPage{CGAL::swap_4}\\
|
|
\ccRefIdfierPage{CGAL::bind_1}\\
|
|
\ccRefIdfierPage{CGAL::bind_2}\\
|
|
\ccRefIdfierPage{CGAL::bind_3}\\
|
|
\ccRefIdfierPage{CGAL::bind_4}\\
|
|
\ccRefIdfierPage{CGAL::bind_5}\\
|
|
\ccRefIdfierPage{CGAL::compose}\\
|
|
\ccRefIdfierPage{CGAL::compose_shared}\\
|
|
\ccRefIdfierPage{CGAL::Swap<F,i>}\\
|
|
\ccRefIdfierPage{CGAL::Bind<F,A,i>}\\
|
|
\ccRefIdfierPage{CGAL::Compose<F0,F1,F2,F3>}\\
|
|
\ccRefIdfierPage{CGAL::Compose_shared<F0,F1,F2,F3>}\\
|
|
\ccRefConceptPage{AdaptableFunctor}\\
|
|
\ccRefIdfierPage{CGAL::Arity_tag<int>}\\
|
|
\ccRefIdfierPage{CGAL::Arity_traits<F>}\\
|
|
\ccRefIdfierPage{CGAL::Set_arity<F,a>}\\
|
|
\ccRefIdfierPage{CGAL::set_arity_0}\\
|
|
\ccRefIdfierPage{CGAL::set_arity_1}\\
|
|
\ccRefIdfierPage{CGAL::set_arity_2}\\
|
|
\ccRefIdfierPage{CGAL::set_arity_3}\\
|
|
\ccRefIdfierPage{CGAL::set_arity_4}\\
|
|
\ccRefIdfierPage{CGAL::set_arity_5}
|
|
|
|
\subsection*{Projection Function Objects.}
|
|
|
|
\ccRefIdfierPage{CGAL::Identity<Value>}\\
|
|
%%\ccRefIdfierPage{CGAL::Compose<Fct1, Fct2>}\\
|
|
\ccRefIdfierPage{CGAL::Dereference<Value>}\\
|
|
\ccRefIdfierPage{CGAL::Get_address<Value>}\\
|
|
\ccRefIdfierPage{CGAL::Cast_function_object<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Project_vertex<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_facet<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_point<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_normal<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_plane<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_next<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_prev<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_next_opposite<Node>}\\
|
|
\ccRefIdfierPage{CGAL::Project_opposite_prev<Node>}
|
|
|
|
\subsection*{Creator Function Objects.}
|
|
|
|
\ccRefIdfierPage{CGAL::Creator_1<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_2<Arg1, Arg2, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_3<Arg1, Arg2, Arg3, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_4<Arg1, Arg2, Arg3, Arg4, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_5<Arg1, Arg2, Arg3, Arg4, Arg5, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_2<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_3<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_4<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_5<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_6<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_7<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_8<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_9<Arg, Result>}\\
|
|
\ccRefIdfierPage{CGAL::Creator_uniform_d<Arg, Result>}
|
|
|
|
\subsection*{Utilities.}
|
|
\ccRefIdfierPage{CGAL::Twotuple<T>}\\
|
|
\ccRefIdfierPage{CGAL::Threetuple<T>}\\
|
|
\ccRefIdfierPage{CGAL::Fourtuple<T>}\\
|
|
\ccRefIdfierPage{CGAL::Sixtuple<T>}\\
|
|
\ccRefIdfierPage{CGAL::Triple<T1, T2, T3>}\\
|
|
\ccRefIdfierPage{CGAL::Quadruple<T1, T2, T3, T4>}
|
|
|
|
\begin{ccHtmlOnly}
|
|
<hr><h2>Reference Pages</h2>
|
|
\end{ccHtmlOnly}
|
|
|
|
%% EOF
|