%% =============================================================================
%% 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 $
%% $Id$
%% $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

%%  \ccIncludeExampleCode{STL_Extension_ref/compact_container_example.C}

\end{ccRefClass}

%% +--------------------------------------------------------+
\ccParDims

% EOF
