\begin{ccRefConcept}{TriangulationDSFullCell}

\ccDefinition

The concept \ccRefName\ describes what a full cell is in a model of the concept
\ccc{TriangulationDataStructure}. It sets requirements of combinatorial nature
only, as geometry is not concerned here.
In the context of triangulation, the term full cell refers to a face of
\emph{maximal} dimension. This maximality characteristic is emphasized by using
the adjective {\em full}.

A \ccRefName\ is responsible for storing handles to the vertices of a
full cell as well as handles to its neighbors.


\ccHasModels

\ccc{CGAL::Triangulation_ds_full_cell<TriangulationDataStructure,DSFullCellStoragePolicy>}\\
\ccc{CGAL::Triangulation_full_cell<TriangulationTraits, Data, TriangulationDSFullCell>}

\ccTypes

\ccThree{Full_cell_handle}{v. set_full_cell(Full_cell_handle c);}{}
\ccThreeToTwo


\ccNestedType{Vertex_handle}%{}
%\ccGlue\ccNestedType{Vertex_const_handle}
{A handle to a vertex. It must be the same as the
nested type \ccc{TriangulationDataStructure::Vertex_handle} of the \ccc{TriangulationDataStructure} in which the
\ccc{TriangulationDSFullCell} is defined/used.}

\ccNestedType{Vertex_handle_iterator}{An iterator over the handles to
the vertices of the full cell.}

\ccNestedType{Full_cell_handle}%{}
%\ccGlue\ccNestedType{Full_cell_const_handle}
{A handle to a full cell. It must be the same as the
nested type \ccc{TriangulationDataStructure::Full_cell_handle} of the \ccc{TriangulationDataStructure} in which the
\ccc{TriangulationDSFullCell} is defined/used.}

\ccThree{Full_cell_handle}{TriangulationDataStructure::Full_cell_data TDS_data}{}
\ccThreeToTwo

\ccTypedef{typedef TriangulationDataStructure::Full_cell_data
  TDS_data;}{A data member of this type has to be stored and accessible through
  access function below.}


\ccThree{Full_cell_handle}{v. set_full_cell(Full_cell_handle c);}{}
\ccThreeToTwo

\ccNestedType{
  template <typename TDS2>
  Rebind_TDS}
{This nested template class has to define a type \ccc{Other} which is the
{\it rebound} vertex, that is, the one whose \ccc{Triangulation_data_structure}
will be the actually used one.  The \ccc{Other} type will be the real base
class of \ccc{Triangulation_data_structure::Full_cell}.}



\ccCreation	
\ccCreationVariable{c}

\ccConstructor{TriangulationDSFullCell(int dmax);}{Sets the maximum possible
dimension of the full cell.}

\ccConstructor{TriangulationDSFullCell(const TriangulationDSFullCell & fc);}%
{Copy constructor.}

If you want to create a full cell as part of a \ccc{TriangulationDataStructure},
you would rather want to call the \ccc{new_full_cell()} from the latter concept,
as it is not possible to incorporate an existing external full cell into
a triangulation.

\ccHeading{Access functions}

\ccMethod{int maximal_dimension() const;}{Returns one less than the maximum
number of vertices that the full cell can store. This does {not} return
the dimension of the actual full cell stored in \ccVar.}

\ccMethod{Vertex_handle_iterator vertices_begin() const;}
{Returns an iterator to the first \ccc{Vertex_handle} stored in the
full cell.}

\ccMethod{Vertex_handle_iterator vertices_end() const;}
{Returns an iterator pointing beyond the last \ccc{Vertex_handle} stored in
the full cell.}

\ccMethod{Vertex_handle vertex(const int i) const;}{Returns the \ccc{i}-th vertex
of the full cell. \ccPrecond $0\leq i\leq$\ccc{maximal_dimension()}.}

\ccGlue\ccMethod{Full_cell_handle neighbor(const int i) const;}{Returns the
full cell opposite to the \ccc{i}-th vertex of the full cell \ccVar. \ccPrecond 
$0\leq i\leq$\ccc{maximal_dimension()}.}

\ccMethod{int mirror_index(const int i) const;}{Returns the index \ccc{j} of
the full cell \ccVar as a neighbor in the full cell \ccVar\ccc{.neighbor(i);}. If the
returned integer is not negative, it holds that \ccVar.%
\ccc{neighbor(i)->neighbor(j) == }\ccVar. Returns
\ccc{-1} if \ccVar has no adjacent full cell of index \ccc{i}. 
\ccPrecond $0\leq i\leq$\ccc{maximal_dimension()}.}

\ccMethod{int index(Full_cell_handle n) const;}{Returns the index \ccc{i}
such that \ccVar\ccc{.neighbor(i)==n}. \ccPrecond \ccc{n}
must be a neighbor of \ccVar.}
\ccGlue
\ccMethod{int index(Vertex_handle v) const;}{Returns the index \ccc{i} of
the vertex \ccc{v} such that \ccVar\ccc{.vertex(i)==v}. \ccPrecond \ccc{v} must be
a vertex of the \ccVar.}

\ccMethod{const TDS_data & get_tds_data() const;}{Returns the data member of
type \ccc{TDS_data}. It is typically used to mark the full cell as \emph{visited}
during operations on a \ccc{TriangulationDataStructure}.}

\ccMethod{TDS_data & get_tds_data();}{Same as above, but returns a reference to
a non-\ccc{const} object.}

\begin{ccAdvanced}
\ccMethod{Vertex_handle mirror_vertex(const int i, const int cur_dim) const;}
{Returns a handle to the mirror vertex of the \ccc{i}-th vertex of full cell
\ccVar. This function works even if the adjacency information stored in the
neighbor full cell \ccc{*}\ccVar\ccc{.neighbor(i)} is corrupted. This is useful
when temporary corruption is necessary during surgical operation on a
triangulation.  \ccPrecond $0\leq
i,$\ccc{cur_dim}$\leq$\ccc{maximal_dimension()}.}
\end{ccAdvanced}


\ccHeading{Update functions} % - - - - - - - - - - - - - - - - - UPDATES
\ccThree{ostream&}{c. set_mirror_index(const int i, const int index)}{}

\ccMethod{void set_vertex(const int i, Vertex_handle v);}{Sets the $i$-th
vertex of the full cell. 
\ccPrecond $0\leq i\leq$\ccc{maximal_dimension()}.}

\ccMethod{void set_neighbor(const int i, Full_cell_handle n);} {Sets the
\ccc{i}-th neighbor of \ccVar\ to \ccc{n}. Full cell \ccc{n} is
opposite to the $i$-th vertex of \ccVar. 
\ccPrecond $0\leq i\leq$\ccc{maximal_dimension()}.}

\ccMethod{void set_mirror_index(const int i, const int index);} {Sets the
mirror index of the $i$-th vertex of \ccVar\ to \ccc{index}. This corresponds
to the index, in \ccVar\ccc{->neighbor(i)}, of the full cell \ccVar.\\
Note: an implementation of the concept \ccVar\ may choose not to store mirror
indices, in which case this function should do nothing.
\ccPrecond $0\leq i\leq$\ccc{maximal_dimension()}.}

\ccMethod{void swap_vertices(int d1, int d2);}{Switches the orientation of the
full cell \ccVar\ by swapping its vertices with index \ccc{d1} and \ccc{d2}.
\ccPrecond $0\leq d1,d2\leq$\ccc{maximal_dimension()}.}

\ccHeading{Queries}

\ccMethod{bool has_vertex(Vertex_handle v) const;}{Returns \ccc{true}
if the vertex \ccc{v} is a vertex of the full cell \ccVar. Returns \ccc{false}
otherwise.}

\ccMethod{bool has_vertex(Vertex_handle v, int & ret) const;}%
{Returns \ccc{true} and sets the value of \ccc{ret} to the index of \ccc{v} in
\ccVar\ if the vertex \ccc{v} is a vertex of the full cell \ccVar. Returns
\ccc{false} otherwise.}

\ccMethod{bool has_neighbor(Full_cell_handle n) const;}{Returns \ccc{true}
if the full cell \ccc{n} is a neighbor of the full cell \ccVar. Returns
\ccc{false} otherwise.}

\ccMethod{bool has_neighbor(Full_cell_handle n, int & ret) const;}%
{Returns \ccc{true} and sets the value of \ccc{ret} to the index of \ccc{n} as
a neighbor of \ccVar\ if the full cell \ccc{n} is a neighbor of the full cell
\ccVar. Returns \ccc{false} otherwise.}


\begin{ccDebug}
\ccHeading{Validity check}

\ccMethod{bool is_valid(bool verbose=false) const;}{
Performs some validity checks on the full cell \ccVar.

It must \emph{at least} check that for each \emph{existing} neighbor \ccc{n},
\ccVar\ is also a neighbor of \ccc{n}. 

Returns \ccc{true} if all the tests pass, \ccc{false} if any test fails. See
the documentation for the models of this concept to see the additionnal (if
any) validity checks that they implement.%
}
\end{ccDebug}

\ccHeading{Memory management}

% \ccMethod{void*   for_compact_container() const;}{}
% \ccGlue\ccMethod{void* & for_compact_container();}{}

% These member functions are required by the classes
% \ccc{Triangulation_data_structure<Dimensionality, TriangulationDSVertex, TriangulationDSFullCell>} and
% \ccc{Triangulation<TriangulationTraits, TriangulationDataStructure>} (and its derived classes) because they use
% \ccc{Compact_container} to store their vertices and full cells. See the
% documentation of \ccc{Compact_container} for the exact requirements.

\ccMethod{void * for_compact_container() const;}{}
\ccGlue
\ccMethod{void * & for_compact_container();}{}
{ These member functions are required by \ccc{Triangulation_data_structure}
  because it uses \ccc{Compact_container} to store its cells.  See the
  documentation of \ccc{Compact_container} for the exact requirements.}


\ccHeading{Input/Output}
These operators can be used directly and are called by the I/O
operator of class \ccc{TriangulationDataStructure}.

\ccFunction{template<class TriangulationDataStructure> istream& operator>>(istream & is,
        Triangulation_ds_full_cell<TriangulationDataStructure> & c);}
{Reads (possibly) non-combinatorial information about a full cell from the stream \ccc{is}
into \ccc{c}.}

\ccFunction{template<class TriangulationDataStructure> ostream& operator<<(ostream & os, const
        Triangulation_ds_full_cell<TriangulationDataStructure> & c);}
{Writes (possibly) non-combinatorial information about full cell \ccc{c} to the stream
    \ccc{os}.}

\ccSeeAlso

\ccc{TriangulationDSVertex}\\
\ccc{TriangulationDSFace}\\
\ccc{TriangulationDataStructure}\\
\ccc{Triangulation}

\end{ccRefConcept}