mirror of https://github.com/CGAL/cgal
91 lines
2.9 KiB
Plaintext
91 lines
2.9 KiB
Plaintext
/*!
|
|
|
|
\page chapnamespaces Namespaces
|
|
|
|
\author 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, for example,
|
|
OpenGL adds `gl`
|
|
and FLTK adds `fl`. \leda uses prefix `leda_`
|
|
|
|
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 `-DLEDA_PREFIX`.} Initially, \cgal used
|
|
prefix `CGAL_`.
|
|
At the beginning of 1999, it was decided to drop prefix `CGAL_` and to
|
|
introduce namespace `CGAL`.
|
|
|
|
# Namespace CGAL #
|
|
|
|
All names introduced by \cgal should be in namespace `CGAL`, <I>e.g.</I>:
|
|
\code{.cpp}
|
|
#include <something>
|
|
|
|
namespace CGAL {
|
|
|
|
class My_new_cgal_class {};
|
|
|
|
My_new_cgal_class
|
|
my_new_function( My_new_cgal_class& );
|
|
|
|
} // namespace CGAL
|
|
\endcode
|
|
Make sure not to have include statements nested between
|
|
<TT> namespace CGAL { </TT> and <TT> } // namespace CGAL</TT>.
|
|
Otherwise all names defined in the file included will be
|
|
added to namespace `CGAL`.
|
|
|
|
# Namespace <TT>internal</TT> #
|
|
|
|
All names introduced by \cgal which are not documented to the user
|
|
should be under an `internal` subnamespace of `CGAL`, <I>e.g.</I>:
|
|
\code{.cpp}
|
|
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
|
|
\endcode
|
|
|
|
# Note on global template functions #
|
|
|
|
According to the resolutions of the following issues in the forthcoming
|
|
\cpp-standard (
|
|
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#225">225</a>,
|
|
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#226">226</a>
|
|
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#229">229</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
|
|
</TT>, the namespace `CGAL::NTS` does not need to be used anymore
|
|
(currently `CGAL_NTS` macro boils down to `CGAL::`).
|
|
|
|
# Requirements and recommendations #
|
|
|
|
Requirements:
|
|
<UL>
|
|
<LI>all names defined by \cgal are in namespace `CGAL`
|
|
(including namespaces nested in namespace `CGAL`).
|
|
<LI>explicitly prefix calls to template functions of CGAL
|
|
(such as `square`, `sign`, `abs`, \f$ \dots\f$ ) by `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).
|
|
</UL>
|
|
|
|
*/
|