CGAL 5.6 - Manual
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.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, e.g.:

#include <something>
namespace CGAL {
class My_new_cgal_class {};
My_new_cgal_class
my_new_function( My_new_cgal_class& );
} // namespace CGAL

Make sure not to have include statements nested between namespace CGAL { and } // namespace CGAL. Otherwise all names defined in the file included will be added to namespace CGAL.

Namespace internal

All names introduced by CGAL which are not documented to the user should be under an internal subnamespace of CGAL, e.g.:

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

Note on global template functions

According to the resolutions of the following issues in the forthcoming C++-standard ( 225, 226 and 229 ):

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 CGAL::NTS does not need to be used anymore (currently CGAL_NTS macro boils down to CGAL::).

Requirements and recommendations

Requirements:

  • all names defined by CGAL are in namespace CGAL (including namespaces nested in namespace CGAL).
  • explicitly prefix calls to template functions of CGAL (such as square, sign, abs, \( \dots\) ) 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).
CGAL 5.6 - Manual
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.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, e.g.:

#include <something>
namespace CGAL {
class My_new_cgal_class {};
My_new_cgal_class
my_new_function( My_new_cgal_class& );
} // namespace CGAL

Make sure not to have include statements nested between namespace CGAL { and } // namespace CGAL. Otherwise all names defined in the file included will be added to namespace CGAL.

Namespace internal

All names introduced by CGAL which are not documented to the user should be under an internal subnamespace of CGAL, e.g.:

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

Note on global template functions

According to the resolutions of the following issues in the forthcoming C++-standard ( 225, 226 and 229 ):

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 CGAL::NTS does not need to be used anymore (currently CGAL_NTS macro boils down to CGAL::).

Requirements and recommendations

Requirements:

  • all names defined by CGAL are in namespace CGAL (including namespaces nested in namespace CGAL).
  • explicitly prefix calls to template functions of CGAL (such as square, sign, abs, \( \dots\) ) 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).