mirror of https://github.com/CGAL/cgal
328 lines
12 KiB
TeX
328 lines
12 KiB
TeX
%% =============================================================================
|
|
%% The CGAL Reference Manual
|
|
%% Chapter: STL Extensions - The Reference Part
|
|
%% -----------------------------------------------------------------------------
|
|
%% file : doc_tex/support/STL_Extension/STL_Extension_ref/compact_container.tex
|
|
%% author: Sylvain Pion
|
|
%% -----------------------------------------------------------------------------
|
|
%% $CGAL_Chapter: STL_Extension $
|
|
%% $Revision$
|
|
%% $Date$
|
|
%% =============================================================================
|
|
|
|
%% +=========================================================================+
|
|
|
|
\begin{ccRefClass}{Compact_container_base}
|
|
|
|
\ccDefinition The class \ccRefName\ can be used as a base class for
|
|
your own type \ccc{T}, so that \ccc{T} can be used directly within
|
|
\ccc{Compact_container<T, Allocator>}. This class stores a \ccc{void *}
|
|
pointer only for this purpose, so it may not be the most memory efficient
|
|
way to achieve this goal. The other ways are to provide in \ccc{T} the
|
|
necessary member functions so that the template
|
|
\ccc{Compact_container_traits<T>} works, or to specialize it for the
|
|
particular type \ccc{T} that you want to use.
|
|
|
|
\ccInclude{CGAL/Compact_container.h}
|
|
\ccSetThreeColumns{void *&}{ccb.for_compact_container() const;}{}
|
|
\ccCreationVariable{ccb}
|
|
\ccTagFullDeclarations
|
|
|
|
\ccOperations
|
|
|
|
\ccMethod{void * for_compact_container() const;}
|
|
{ Returns the pointer necessary for \ccc{Compact_container_traits<T>}. }
|
|
\ccGlue
|
|
\ccMethod{void * & for_compact_container();}
|
|
{ Returns a reference to the pointer necessary for
|
|
\ccc{Compact_container_traits<T>}. }
|
|
\end{ccRefClass}
|
|
|
|
%% +--------------------------------------------------------+
|
|
\begin{ccRefClass}{Compact_container_traits<T>}
|
|
|
|
\ccDefinition The traits class \ccClassTemplateName\ provides
|
|
the way to access the internal pointer required for \ccc{T} to be
|
|
used in a \ccc{Compact_container<T, Allocator>}. Note that this
|
|
pointer needs to be accessible even when the object is not constructed,
|
|
which means it has to reside in the same memory place as \ccc{T}.
|
|
|
|
You can specialize this class for your own type \ccc{T}
|
|
if the default template is not suitable.
|
|
|
|
You can also use \ccc{Compact_container_base} as base class for your own
|
|
types \ccc{T} to make them usable with the default \ccClassTemplateName.
|
|
|
|
\ccInclude{CGAL/Compact_container.h}
|
|
|
|
\ccSetThreeColumns{static void *&}{cct.pointer(const T &t) ;}{}
|
|
\ccCreationVariable{cct}
|
|
\ccTagFullDeclarations
|
|
|
|
\ccParameters
|
|
|
|
\ccc{T} is any type providing the following member functions:\\
|
|
\ccc{void * t.for_compact_container() const;}\\
|
|
\ccc{void *& t.for_compact_container();}.
|
|
|
|
\ccOperations
|
|
|
|
\ccMethod{static void * pointer(const T &t);}
|
|
{Returns the pointer hold by \ccc{t}.
|
|
The template version defines this function as:\\
|
|
\ccc{
|
|
return t.for_compact_container();
|
|
}
|
|
}
|
|
\ccGlue
|
|
\ccMethod{static void * & pointer(T &t);}
|
|
{Returns a reference to the pointer hold by \ccc{t}.
|
|
The template version defines this function as:\\
|
|
\ccc{
|
|
return t.for_compact_container();
|
|
}
|
|
}
|
|
|
|
\end{ccRefClass}
|
|
|
|
%% +--------------------------------------------------------+
|
|
\begin{ccRefClass}{Compact_container<T, Allocator>}
|
|
|
|
\ccDefinition An object of the class \ccClassTemplateName\
|
|
is a container of objects of type \ccc{T}. It matches all the
|
|
standard requirements for reversible containers, except that
|
|
the complexity of its iterator increment and decrement operations
|
|
is not always guaranteed to be amortized constant time.
|
|
|
|
This container is not a standard \textit{sequence} nor \textit{associative} container,
|
|
which means the elements are stored in no particular order, and it is not
|
|
possible to specify a particular place in the iterator sequence where to
|
|
insert new objects. However, all dereferenceable iterators are
|
|
still valid after calls to \ccc{insert()} and \ccc{erase()}, except those
|
|
that have been erased (it behaves similarly to \ccc{std::list}).
|
|
|
|
The main feature of this container is that it is very memory efficient :
|
|
its memory size is \ccc{N*sizeof(T)+o(N)}, where \ccc{N} is the maximum size
|
|
that the container has had in its past history, its \ccc{capacity()}
|
|
(the memory of erased elements is not deallocated until destruction of the
|
|
container or a call to \ccc{clear()}). This container has been developped in
|
|
order to store large graph-like data structures like the triangulation and
|
|
the halfedge data structures.
|
|
|
|
It supports bidirectional iterators and allows a constant time amortized
|
|
\ccc{insert()} operation. You cannot specify where to insert new objects
|
|
(i.e. you don't know where they will end up in the iterator sequence,
|
|
although \ccc{insert()} returns an iterator pointing to the newly inserted
|
|
object). You can erase any element with a constant time complexity.
|
|
|
|
Summary of the differences with \ccc{std::list}~: it is more compact in
|
|
memory since it doesn't store two additional pointers for the iterator needs.
|
|
It doesn't deallocate elements until the destruction or \ccc{clear()} of the
|
|
container. The iterator does not have constant amortized time complexity for
|
|
the increment and decrement operations in all cases, only when not too many
|
|
elements have not been freed (i.e. when the \ccc{size()} is close to the
|
|
\ccc{capacity()}). Iterating from \ccc{begin()} to \ccc{end()} takes
|
|
\ccc{O(capacity())} time, not \ccc{size()}. In the case where the container
|
|
has a small \ccc{size()} compared to its \ccc{capacity()}, we advise to
|
|
"defragment the memory" by copying the container if the iterator performance
|
|
is needed.
|
|
|
|
The iterators themselves can be used as \ccc{T}, they provide the necessary
|
|
functions to be used by \ccc{Compact_container_traits<T>}.
|
|
|
|
\ccInclude{CGAL/Compact_container.h}
|
|
|
|
%% +-----------------------------------+
|
|
\ccParameters
|
|
|
|
The parameter \ccStyle{T} is required to have a copy constructor and an
|
|
assignment operator. It also needs to provide access to an internal
|
|
pointer via \ccc{Compact_container_traits<T>}.
|
|
|
|
The equality test and the relational order require the operators
|
|
\ccStyle{==} and \ccStyle{<} for \ccc{T} respectively.
|
|
|
|
The parameter \ccStyle{Allocator} has to match the standard allocator
|
|
requirements, with value type \ccc{T}. This parameter has the default
|
|
value \ccc{CGAL_ALLOCATOR(T)}.
|
|
|
|
%% +-----------------------------------+
|
|
\ccTypes
|
|
\ccSetThreeColumns{Compact_container<T, Allocator> &}{l.swap( l1);}{}
|
|
\ccPropagateThreeToTwoColumns
|
|
|
|
\ccNestedType{value_type}{}
|
|
\ccGlue
|
|
\ccNestedType{reference}{}
|
|
\ccGlue
|
|
\ccNestedType{const_reference}{}
|
|
\ccGlue
|
|
\ccNestedType{pointer}{}
|
|
\ccGlue
|
|
\ccNestedType{const_pointer}{}
|
|
\ccGlue
|
|
\ccNestedType{size_type}{}
|
|
\ccGlue
|
|
\ccNestedType{difference_type}{}
|
|
|
|
\ccNestedType{iterator}{}
|
|
\ccGlue
|
|
\ccNestedType{const_iterator}{}
|
|
\ccGlue
|
|
\ccNestedType{reverse_iterator}{}
|
|
\ccGlue
|
|
\ccNestedType{const_reverse_iterator}{}
|
|
|
|
\ccNestedType{allocator_type}{}
|
|
|
|
%% +-----------------------------------+
|
|
\ccCreation
|
|
\ccCreationVariable{c}
|
|
|
|
\ccConstructor{explicit Compact_container(const Allocator &a = Allocator());}
|
|
{introduces an empty container, eventually specifying a particular
|
|
allocator \ccc{a} as well.}
|
|
|
|
\ccConstructor{template <class InputIterator> Compact_container(
|
|
InputIterator first, InputIterator last,
|
|
const Allocator &a = Allocator());}
|
|
{a container with copies from the range [\ccStyle{first,last}), eventually
|
|
specifying a particular allocator.}
|
|
|
|
\ccConstructor{Compact_container(const Compact_container<T, Allocator> &cc);}
|
|
{copy constructor. Each item in \ccStyle{cc} is copied. The allocator
|
|
is copied. The iterator order is preserved.}
|
|
|
|
\ccMethod{Compact_container<T, Allocator> & operator=(const
|
|
Compact_container<T, Allocator> &cc);}
|
|
{assignment. Each item in \ccStyle{cc} is copied. The allocator is copied.
|
|
Each item in \ccVar\ is deleted. The iterator order is preserved.}
|
|
|
|
\ccMethod{void swap(Compact_container<T, Allocator> &cc);}
|
|
{swaps the contents of \ccVar\ and \ccStyle{cc} in constant time
|
|
complexity. No exception is thrown.}
|
|
|
|
%% +-----------------------------------+
|
|
\ccHeading{Access Member Functions}
|
|
|
|
\def\ccTagRmTrailingConst{\ccFalse}
|
|
\ccMethod{iterator begin();}
|
|
{returns a mutable iterator referring to the first element in~\ccVar.}
|
|
|
|
\ccGlue\ccMethod{const_iterator begin() const;}
|
|
{returns a constant iterator referring to the first element in~\ccVar.}
|
|
|
|
\ccGlue\ccMethod{iterator end();}
|
|
{returns a mutable iterator which is the past-end-value of~\ccVar.}
|
|
|
|
\ccGlue\ccMethod{const_iterator end() const;}
|
|
{returns a constant iterator which is the past-end-value of~\ccVar.}
|
|
|
|
\ccMethod{reverse_iterator rbegin();}{}
|
|
\ccGlue\ccMethod{const_reverse_iterator rbegin() const;}{}
|
|
\ccGlue\ccMethod{reverse_iterator rend();}{}
|
|
\ccGlue\ccMethod{const_reverse_iterator rend() const;}{}
|
|
\def\ccTagRmTrailingConst{\ccTrue}
|
|
|
|
\ccMethod{bool empty() const;}
|
|
{returns \ccStyle{true} iff \ccVar\ is empty.}
|
|
|
|
\ccGlue\ccMethod{size_type size() const;}
|
|
{returns the number of items in~\ccVar.}
|
|
|
|
\ccGlue\ccMethod{size_type max_size() const;}
|
|
{returns the maximum possible size of the container~\ccVar.}
|
|
|
|
\ccGlue\ccMethod{size_type capacity() const;}
|
|
{returns the total number of elements that~\ccVar\ can hold without requiring
|
|
reallocation.}
|
|
|
|
% - reserve() % XXX FIXME
|
|
% - block_size() % TODO
|
|
|
|
\ccMethod{Allocator get_allocator() const;}{returns the allocator.}
|
|
|
|
%% +-----------------------------------+
|
|
\ccHeading{Insertion}
|
|
|
|
\ccMethod{iterator insert(const T& t);}
|
|
{inserts a copy of \ccc{t} in \ccVar\ and returns the iterator pointing
|
|
to it.}
|
|
|
|
\ccMethod{template <class InputIterator>
|
|
void insert(InputIterator first, InputIterator last);}
|
|
{inserts the range [\ccStyle{first, last}) in \ccVar.}
|
|
|
|
\ccMethod{template <class InputIterator>
|
|
void assign(InputIterator first, InputIterator last);}
|
|
{erases all the elements of \ccVar, then inserts the range
|
|
[\ccStyle{first, last}) in \ccVar.}
|
|
|
|
\ccMethod{template < typename T1 >
|
|
iterator construct_insert(T1 t1);}
|
|
{constructs an object of type \ccc{T} with the constructor that takes
|
|
\ccc{t1} as argument, inserts it in \ccVar, and returns the iterator pointing
|
|
to it. The same constructor exists for up to nine arguments.}
|
|
|
|
%% +-----------------------------------+
|
|
\ccHeading{Removal}
|
|
|
|
\ccMethod{void erase(iterator pos);}
|
|
{removes the item pointed by \ccc{pos} from~\ccVar.}
|
|
|
|
\ccMethod{void erase(iterator first, iterator last);}
|
|
{removes the items from the range [\ccStyle{first, last}) from~\ccVar.}
|
|
|
|
\ccMethod{void clear();}
|
|
{all items in \ccVar\ are deleted, and the memory is deallocated.
|
|
After this call, \ccVar\ is in the same state as if just default
|
|
constructed.}
|
|
|
|
%% +-----------------------------------+
|
|
\ccHeading{Special Operation}
|
|
|
|
\ccSetThreeColumns{const_iterator}{l.erase( iterator pos);}{}
|
|
|
|
\ccMethod{void merge(Compact_container<T, Allocator> &cc);}
|
|
{adds the items of \ccc{cc} to the end of \ccVar\ and \ccc{cc} becomes empty.
|
|
The time complexity is O(\ccVar.\ccc{capacity()}-\ccVar.\ccc{size()}).
|
|
\ccPrecond \ccc{cc} must not be the same as \ccVar,
|
|
and the allocators of \ccVar\ and \ccc{cc} need to be compatible :
|
|
\ccVar.\ccc{get_allocator() == cc.get_allocator()}.}
|
|
|
|
%% +-----------------------------------+
|
|
\ccHeading{Comparison Operations}
|
|
\ccSetThreeColumns{const_iterator}{l.erase( iterator pos);}{}
|
|
|
|
\ccMethod{bool operator==(const Compact_container<T, Allocator> &cc) const;}
|
|
{test for equality: Two containers are equal, iff they have the
|
|
same size and if their corresponding elements are equal.}
|
|
|
|
\ccMethod{bool operator!=(const Compact_container<T, Allocator> &cc) const;}
|
|
{test for inequality: returns !(\ccVar\ \ccc{== cc}).}
|
|
|
|
\ccMethod{bool operator<(const Compact_container<T, Allocator> &cc) const;}
|
|
{compares in lexicographical order.}
|
|
|
|
\ccMethod{bool operator>(const Compact_container<T, Allocator> &cc) const;}
|
|
{returns \ccc{cc <} \ccVar.}
|
|
|
|
\ccMethod{bool operator<=(const Compact_container<T, Allocator> &cc) const;}
|
|
{returns !(\ccVar\ \ccc{> cc}).}
|
|
|
|
\ccMethod{bool operator>=(const Compact_container<T, Allocator> &cc) const;}
|
|
{returns !(\ccVar\ \ccc{< cc}).}
|
|
|
|
%% TBD
|
|
%% \newpage
|
|
%% \ccExample
|
|
|
|
%% \ccIncludeVerbatim{STL_Extension_ref/compact_container_example.C}
|
|
|
|
\end{ccRefClass}
|
|
|
|
%% +--------------------------------------------------------+
|
|
\ccParDims
|
|
|
|
% EOF
|