mirror of https://github.com/CGAL/cgal
112 lines
3.9 KiB
TeX
112 lines
3.9 KiB
TeX
% =============================================================================
|
|
% The CGAL Developers' Manual
|
|
% Chapter: Namespaces
|
|
% -----------------------------------------------------------------------------
|
|
% file : namespaces.tex
|
|
% authors: Stefan Schirra <stschirr@mpi-sb.mpg.de>
|
|
% -----------------------------------------------------------------------------
|
|
% $Id$
|
|
% $Date$
|
|
% =============================================================================
|
|
|
|
\chapter{Namespaces\label{chap:namespaces}}
|
|
\ccChapterAuthor{Stefan Schirra}
|
|
|
|
Names, in particular (member) function names and class names should
|
|
be descriptive and easily remembered. So it is not surprising that
|
|
different libraries or packages choose the same name for corresponding
|
|
or similar classes and functions. A common approach to solving the
|
|
naming problem is to add a prefix,\ccIndexMainItem{prefix} for example,
|
|
OpenGL adds \ccc{gl}
|
|
and FLTK adds \ccc{fl}. \leda\ uses prefix \ccc{leda_}%
|
|
\ccIndexSubitem{prefix}{\ccFont leda_}
|
|
\ccIndexSubitem{\leda}{prefix}
|
|
to some extent,
|
|
but you have to tell \leda\ not to make the corresponding unprefixed names
|
|
available as well.\footnote{\cgal's
|
|
makefile does this by setting \ccc{-DLEDA_PREFIX}.} Initially, \cgal\ used
|
|
prefix \ccc{CGAL_}.
|
|
At the beginning of 1999, it was decided to drop prefix \ccc{CGAL_} and to
|
|
introduce namespace \ccc{CGAL}.
|
|
|
|
\section{Namespace CGAL}
|
|
\ccIndexSubitem{namespace}{\ccFont CGAL}
|
|
All names introduced by \cgal\ should be in namespace \ccc{CGAL}, \eg:
|
|
\begin{verbatim}
|
|
#include <something>
|
|
|
|
namespace CGAL {
|
|
|
|
class My_new_cgal_class {};
|
|
|
|
My_new_cgal_class
|
|
my_new_function( My_new_cgal_class& );
|
|
|
|
} // namespace CGAL
|
|
\end{verbatim}
|
|
Make sure not to have include statements nested between
|
|
\verb+ namespace CGAL { + and \verb+ } // namespace CGAL+.
|
|
Otherwise all names defined in the file included will be
|
|
added to namespace \ccc{CGAL}.
|
|
|
|
\section{Namespace {\tt internal}}
|
|
\ccIndexSubitem{namespace}{\ccFont internal}
|
|
All names introduced by \cgal\ which are not documented to the user
|
|
should be under an \ccc{internal} subnamespace of \ccc{CGAL}, \eg:
|
|
\begin{verbatim}
|
|
namespace CGAL { namespace internal {
|
|
|
|
class My_undocumented_class {};
|
|
|
|
void my_new_function( My_undocumented_class& );
|
|
|
|
}} // namespace CGAL::internal
|
|
|
|
namespace CGAL { namespace internal { namespace Package { namespace tags {
|
|
|
|
class Some_further_class_local_to_Package;
|
|
|
|
}}}} // namespace CGAL::internal::Package::tags
|
|
\end{verbatim}
|
|
|
|
|
|
\section{Note on global template functions}
|
|
|
|
According to the resolutions of the following issues in the forthcoming
|
|
\CC-standard (
|
|
\begin{ccHtmlOnly}
|
|
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#225">
|
|
\end{ccHtmlOnly}%
|
|
225\ccTexHtml{,}{</a>,}%
|
|
\begin{ccHtmlOnly}
|
|
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#226">
|
|
\end{ccHtmlOnly}%
|
|
226\ccTexHtml{,}{</a>,} and%
|
|
\begin{ccHtmlOnly}
|
|
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#229">
|
|
\end{ccHtmlOnly}%
|
|
229\ccTexHtml{.}{</a>.}
|
|
):
|
|
{\tt
|
|
Unless otherwise specified, no global or non-member function in the standard library
|
|
shall use a function from another namespace which is found through argument-dependent
|
|
name lookup
|
|
}, the namespace \ccc{CGAL::NTS} does not need to be used anymore
|
|
(currently \ccc{CGAL_NTS} macro boils down to \ccc{CGAL::}).
|
|
|
|
\section{Requirements and recommendations}
|
|
|
|
Requirements:
|
|
\begin{itemize}
|
|
\item all names defined by \cgal\ are in namespace \ccc{CGAL}
|
|
(including namespaces nested in namespace \ccc{CGAL}).
|
|
\item explicitly prefix calls to template functions of CGAL
|
|
(such as \ccc{square}, \ccc{sign}, \ccc{abs}, \dots) by \ccc{CGAL::}
|
|
to ensure the functions used are the one from \cgal\ and not one from another
|
|
library. If you want to allow an optimized function from another library
|
|
to be used, then you should not qualify the call and document it explicitly
|
|
(if appropriate).
|
|
\end{itemize}
|
|
|
|
|