\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 cell refer to a face of
\emph{maximal} dimension. We emphasize this maximality characteristic by using
the term {\em full cell}.

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

This concept is a \emph{sub-concept} of the \ccc{TriangulationDataStructure}
concept.

\ccHasModels

\ccc{Triangulation_ds_full_cell<TDS, TDSFullCellStoragePolicy>}\\
\ccc{Triangulation_full_cell<TrTraits, Data, TDSFullCell>}

\ccTypes

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

\ccNestedType{Vertex_handle_iterator}{An iterator over the handles to
the vertices of the 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{TDS::Full_cell_handle} of the \ccc{TDS} in which the
\ccc{TriangulationDSFullCell} is defined/used.}

\ccTypedef{typedef TDS::Full_cell_data TDS_data;}{}

\ccNestedType{template<typename TDS2> Rebind_TDS}{This nested template
class must define a nested type \ccc{Other} which is the rebound cell
class template, that is: \ccc{Other == TriangulationDSFullCell<TDS2>}.}

\ccCreation	
\ccCreationVariable{c}

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

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

If you want to create a 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 cell into
a triangulation.

\ccHeading{Access functions}

\ccMethod{int ambient_dimension() const;}{Returns one less than the maximum
number of vertices that the full cell can store. This does \textbf{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 cell. \ccPrecond $0\leq i\leq$\ccc{ambient_dimension()}.}

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

\ccMethod{int mirror_index(const int i) const;}{Returns the index \ccc{j} of
the cell \ccc{s} as a neighbor in the 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 \ccc{s} has no neighboring cell of index \ccc{i}. 
\ccPrecond $0\leq i\leq$\ccc{ambient_dimension()}.}

\ccMethod{int index(Full_cell_handle n) const;}{Returns the index \ccc{i}
of the neighbor \ccc{n} such that \ccVar\ccc{.neighbor(i)==n}. \ccPrecond \ccc{n}
must be a neighbor of \ccc{s}.}
\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 \ccc{s}.}

\ccMethod{const TDS_data & get_tds_data() const;}{Returns the data member of
type \ccc{TDS_data}. It is typically used to mark the 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 cell
\ccVar. This function works even if the neighboring 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{ambient_dimension()}.}
\end{ccAdvanced}


\ccHeading{Update functions} % - - - - - - - - - - - - - - - - - UPDATES

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

\ccMethod{void set_neighbor(const int i, Full_cell_handle n);} {Sets the
\ccc{i}-th neighboring cell of \ccVar\ to \ccc{n}. Full cell \ccc{n} is
opposite to the $i$-th vertex of \ccVar. 
\ccPrecond $0\leq i\leq$\ccc{ambient_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 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{ambient_dimension()}.}

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

\ccHeading{Queries}

\ccMethod{bool has_vertex(Vertex_handle v) const;}{Returns \ccc{true}
if the vertex \ccc{v} is a vertex of the 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 cell \ccVar. Returns
\ccc{false} otherwise.}

\ccMethod{bool has_neighbor(Full_cell_handle n) const;}{Returns \ccc{true}
if the cell \ccc{n} is a neighbor of the 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 cell \ccc{n} is a neighbor of the cell
\ccVar. Returns \ccc{false} otherwise.}

\ccHeading{Validity check}

\ccMethod{bool is_valid(bool verbose=false, int level=0) const;}{Performs any
desired test on a cell. \emph{E.g.}, checks that for each existing vertex,
there is an existing neighbor.}

% \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, TDSVertex, TDSFullCell>} and
% \ccc{Triangulation<TrTraits, TDS>} (and its derived classes) because they use
% \ccc{Compact_container} to store their vertices and simplices. See the
% documentation of \ccc{Compact_container} for the exact requirements.

\ccHeading{Input/Output}

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

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

\ccSeeAlso

\ccc{TriangulationDSVertex}\\
\ccc{TriangulationDataStructure}

\end{ccRefConcept}
