cgal/Spatial_searching/doc_tex/Spatial_searching_ref/Point_container.tex

% +------------------------------------------------------------------------+
% | Reference manual page: Point_container.tex
% +------------------------------------------------------------------------+
% | 1.07.2001   Johan W.H. Tangelder
% | Package: ASPAS
% |
\RCSdef{\RCSPointcontainerRev}{$Id$}
\RCSdefDate{\RCSPointcontainerDate}{$Date$}
% |
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+


\begin{ccRefClass}{Point_container<Traits>}

%% \ccHtmlCrossLink{}     %% add further rules for cross referencing links
%% \ccHtmlIndexC[class]{} %% add further index entries


\begin{ccAdvanced}


\ccDefinition
A custom container for points used to build a tree. Each point container
holds the points from a rectangle associated with a node of the tree.
In the remainder of this reference page this rectangle is called the
associated rectangle.
Provides a method to split a container and a number of methods
to support the implementation of splitting rules.

\ccInclude{CGAL/Point_container.h}

\ccParameters

Expects for the template argument an implementation for
$d$-dimensional points of the concept \ccc{SearchTraits}, for example
\ccc{CGAL::Cartesian_d<double>}.

\ccTypes

\ccTypedef{Traits::FT FT;}{Number type.}
\ccTypedef{Traits::Point_d Point_d;}{Point type.}
\ccNestedType{iterator}{An iterator with value type \ccc{Point_d*}.}
\ccNestedType{const_iterator}{A const iterator with value type \ccc{const Point_d*}.}

%----------------------------------------
\ccCreation
\ccCreationVariable{c}

\ccConstructor{Point_container(int d);}
{
Construct an empty container for storing \ccc{d}-dimensional points.
}

\ccConstructor{
template <class InputIterator>
Point_container(int d, InputIterator begin, InputIterator end);}
{
Construct the container of $d$-dimensional points of type \ccc{Point_d}
given by the iterator sequence \ccc{[begin, end)}.}



\ccOperations

\ccMethod{template <class SpatialSeparator>
void split(Point_container<Traits> &c2, SpatialSeparator sep, bool sliding=false);}
{Given an empty container \ccc{c2} with the same dimension as \ccVar, splits \ccVar\ into
\ccVar and \ccc{c2} using the separator \ccc{sep}. If sliding is \ccc{true} after splitting 
each container contains at least one point. Container \ccVar\ should contain at least two points.}


\ccMethod{void swap(Point_container<Traits> &c2);}
{Swap the contents of \ccVar\ and \ccc{c2}}


\ccMethod{void recompute_tight_bounding_box();}
{Recompute the bounding box of the points in the container.}


\ccMethod{iterator begin();}
{
Returns an iterator to a pointer to the first point.
}

\ccMethod{iterator end();}
{
Returns the appropriate past-the-end iterator.
}

\ccMethod{const_iterator begin() const;}
{
Returns a const iterator to a pointer to the first point.
}

\ccMethod{const_iterator end() const;}
{
Returns the appropriate past-the-end const iterator.
}

\ccMethod{int dimension() const;}
{
Returns the dimension.
}

\ccMethod{int built_coordinate() const;}
{
Returns coordinate for which the pointer list is built.
}

\ccMethod{int max_span_coord() const;}
{
Returns coordinate where the associated rectangle has maximal span.
}

\ccMethod{int max_tight_span_coord() const;}
{
Returns coordinate where the point coordinates have maximal span.
}

\ccMethod{FT max_span_lower() const;}
{
Returns lower value of the interval corresponding to
\ccc{max_span_coord()}.
}


\ccMethod{FT max_tight_span_lower() const;}
{
Returns lower value of the interval corresponding to
\ccc{max_tight_span_coord()}. That is, the smallest
\ccc{max_tight_span_coord()}-th coordinate of the points in
\ccVar.
}


\ccMethod{FT max_span_upper() const;}
{
Returns upper value of the interval corresponding to
\ccc{max_span_coord()}.
}

\ccMethod{FT max_span_upper_without_dim(int d) const;}
{
Returns upper value of the interval over all dimensions
without taking dimension \ccc{d} into account.
}

\ccMethod{FT max_tight_span_upper() const;}
{
Returns upper value of the interval corresponding to
\ccc{max_tight_span_coord()}.
}

\ccMethod{FT  max_spread() const;}
{
Returns the size of the interval corresponding to \ccc{max_span_coord()}.
}

\ccMethod{FT max_tight_spread() const;}
{
Returns the size of the interval corresponding to \ccc{max_tight_span_coord()}.
}

\ccMethod{FT median(int split_coord) const;}
{
Returns the median value of the points stored in the container for
dimension \ccc{split_coord}.
}

\ccMethod{const Kd_tree_rectangle<Traits> & bounding_box() const;}
{Returns the associated rectangle.}

\ccMethod{const Kd_tree_rectangle<Traits> & tight_bounding_box();}
{Returns the bounding box of the items in associated rectangle.}

\ccMethod{int max_tight_span_coord_balanced(FT aspect_ratio) const;}
{Returns the dimension with the maximal point spread, for which after fair splitting
the ratio of the length of the longest side and the smallest side of the bounding box of
the items in associated rectangle,
does not exceed \ccc{aspect_ratio}.}

\ccMethod{FT balanced_fair(int d, FT aspect_ratio);}
{Returns the splitting value for fair splitting.}

\ccMethod{FT balanced_sliding_fair(int d, FT aspect_ratio);}
{Returns the splitting value for sliding fair splitting.}

\ccMethod{std::size_t size() const;}
{
Returns the number of points stored.
}

\ccMethod{bool empty() const;}
{
Returns true if no points are present, false otherwise.
}




\ccHeading{Output Routines}

\ccFunction{ template<class Traits>
std::ostream& operator<<(std::ostream& s, Point_container<Traits> c);}
{Prints the point container \ccVar\ to the output stream \ccc{s} and returns \ccc{s}.}


\ccSeeAlso

\ccc{SearchTraits}\\
\ccc{SpatialSeparator}

\end{ccAdvanced}
\end{ccRefClass}

% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
% EOF
% +------------------------------------------------------------------------+