% ============================================================================= % The CGAL Developers' Manual % Chapter: Namespaces % ----------------------------------------------------------------------------- % file : namespaces.tex % authors: Stefan Schirra % ----------------------------------------------------------------------------- % $Revision$ % $Date$ % ============================================================================= \chapter{Namespaces} \label{chap:namespaces} \ccChapterAuthor{Stefan Schirra ({\tt stschirr@mpi-sb.mpg.de})} 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{What are namespaces} A namespace\ccIndexMainItemDef{namespace} is a scope with a name.\footnote{There are also unnamed namespaces. They are intented to replace file scope.} Inside the namespace, \ie, the named scope, all names defined in that scope (and made known to the compiler) can be used directly. Outside a namespace, a name defined in the namespace has to be qualified\footnote{This is a somewhat simplified view; read further for more details.} by the namespace name, for example \ccc{CGAL::Object},% \ccIndexSubitem{qualification}{of names} or they have to be made usable without qualificiation by a so-called {\em using declaration}, \ccIndexMainItem{using declaration} \begin{verbatim} using CGAL::Object; Object obj; // name is now known \end{verbatim} There is also a statement to make all names from a namespace available in another scope, but this is a bad idea. Actually, in order not to set a bad example, we recommend not to use this in \cgal's example and demo programs. \section{Namespace std} \ccIndexSubitem{namespace}{\ccFont std} The names form the standard \CC\ library, especially those from the standard template library, are (supposed to be) in namespace \ccc{std}. This subsumes the I/O-library% \index{IO library@I/O library!and namespace std@and namespace \texttt{std}} and also the C-library% \index{C standard library!and namespace std@and namespace \ccStyle{std}} functions. If rules are applied strictly\footnote{Not all compilers do that, but some at least have a flag to force strict application of the rules.}, you have to qualify streams and so by \ccc{std::}, too. That is: \begin{verbatim} std::cout << "Hello CGAL" << std::endl; \end{verbatim} or you have to add \ccc{using} declarations for the names you want to use without \ccc{std::} qualification. Developers should of course assume that the rules will be applied strictly. Whenever a platform does not put names in namespace \ccc{std}, \cgal\ adds the names it needs to namespace \ccc{std}. This is done by the configuration tools! \ccIndexMainItem{configuration} As for the C-library functions, you should use the macro \texttt{CGAL\_CLIB\_STD} instead of \texttt{std}: \begin{verbatim} CGAL_CLIB_STD::isspace(c) \end{verbatim} \index{cgal_clib_std macro@{\tt CGAL\_CLIB\_STD} macro} \section{Namespace CGAL} \ccIndexSubitem{namespace}{\ccFont CGAL} All names introduced by \cgal\ should be in namespace \ccc{CGAL}, \eg: \begin{verbatim} #include 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}. (Some people use the macros \ccc{CGAL_BEGIN_NAMESPACE} and \ccc{CGAL_END_NAMEPACE} in place of the \texttt{namespace CGAL \{} and \texttt{\} // namespace CGAL}, respectively for better readability.) Some compilers don't like \texttt{CGAL::} qualification in namespace \ccc{CGAL}. In other cases, \eg, template friend declarations,% \ccIndexSubitem{friend declaration}{function template} \ccIndexSubsubitem{template}{function}{friend declarations} compilers need to see \texttt{CGAL::} qualification. To resolve this dilemma, use \texttt{CGAL\_SCOPE} instead of \texttt{CGAL::} in such cases. \index{cgal_scope macro@{\tt CGAL\_SCOPE} macro} \section{Name lookup} The process of searching for a definition of a name detected in some scope is called name lookup.\ccIndexMainItemDef{name lookup} Simply speaking, name lookup looks up names in the scope where the name is used, and if not found, the lookup proceeds in successively enclosing scope until the name is found. It terminates as soon as the name is found, no matter whether the name found fits or not. If a name is qualified by a namespace name, that namespace is searched for the name. \subsection{Argument-dependent name lookup} \ccIndexSubitem{name lookup}{argument-dependent}% \ccIndexSubitem{name lookup}{unqualified} Unqualified name lookup, \ie, lookup when there is no namespace or class name and no scope resolution% \ccIndexMainItem{scope resolution} operator \verb+::+, proceeds like qualified name lookup, but name lookup for a function call is supposed to search also the namespaces of the argument types for a matching function name. This is sometimes called Koenig-lookup.\footnote{% \path+http://www.devresource.hp.com/devresource/Docs/TechPapers/KoenigLookup.html+}\ccIndexMainItem{Koenig lookup} \cgal\ checks for Koenig-lookup. If this is not available, the flag \ccc{CGAL_CFG_NO_KOENIG_LOOKUP}% \index{CGAL_CFG_NO_KOENIG_LOOKUP flag@{\tt CGAL\_CFG\_NO\_KOENIG\_LOOKUP} flag} is set. As a workaround, you can add matching function(s) with the same name in the using namespace; most likely, this will be the global scope. Here is an example: \ccIncludeExampleCode{kl.C} While \verb+gcc 2.95+ and the Kai \CC\ compiler don't have problems with correctly compiling the program above, the mips compiler on {\sc IRIX} does not implement Koenig lookup, so it fails: {\small \begin{verbatim} bash-2.03$ CC -64 kl.C cc-1387 CC: ERROR File = kl.C, Line = 19 No suitable conversion function from "A::Cls" to "int" exists. foo( c ); ^ 1 error detected in the compilation of "kl.C". \end{verbatim} } Workaround for missing Koenig lookup:\ccIndexSubitem{Koenig lookup}{workaround} Define \begin{verbatim} bool foo( const A::Cls& cls) { return A::foo( cls); } \end{verbatim} in global scope, too. \subsection{Point of instantiation of a template} Name lookup in a template is slightly more complicated. \ccIndexSubitem{name lookup}{template} Names that do not depend on template parameters are looked up at the point of definition of the template% \ccIndexSubitem{template}{point of definition} (so they must be known at the point of definition). Names depending on the template parameters are looked up at the point of instantiation% \ccIndexSubitem{template}{point of instantiation} of the template. The name is searched for in the scope of the point of instantiation and the scope of the point of definition. Here is a small example: \ccIncludeExampleCode{poi.C} There is a ambiguity, because both the scope enclosing the point of instantiation and the scope enclosing the point of definition contain a \ccc{mix} function. The mips compiler on {\sc IRIX} and the Kai \CC\ compiler complain about this ambiguity: {\small \begin{verbatim} bash-2.03$ CC -64 poi.C cc-1282 CC: ERROR File = poi.C, Line = 11 More than one instance of overloaded function "mix" matches the argument list. Function symbol function template "B::mix(const T &, const T &)" is ambiguous by inheritance. Function symbol function template "A::mix(const T &, const T &)" is ambiguous by inheritance. The argument types are: (const double, const double). { return mix( a1, a2); } ^ detected during instantiation of "const double &A::use(const double &, const double &)" 1 error detected in the compilation of "poi.C". \end{verbatim} \bigskip \begin{verbatim} bash-2.03$ /opt/kaic++/KCC_BASE/bin/KCC poi.C Recompiling poi.o "poi.C", line 11: error: more than one instance of overloaded function "mix" matches the argument list: function template "B::mix(const T &, const T &)" function template "A::mix(const T &, const T &)" argument types are: (const double, const double) { return mix( a1, a2); } ^ detected during instantiation of "const T &A::use(const T &, const T &) [with T=double]" 1 error detected in the compilation of "poi.C". \end{verbatim} } There wouldn't be any problems, if \verb+B::use_use()+ would be a template function as well, because this would move the point of instantiation into global scope. By the way, \verb+gcc 2.95+ uses the function defined at the point of definition. \section{Namespace CGAL::NTS} What are the conclusions from the previous subsection. If \ccc{A} plays the role of \ccc{std} and \ccc{B} the role of \cgal, we can conclude that \cgal\ should not define template functions that are already defined in namespace \ccc{std}, especially \ccc{min} and \ccc{max}. Also, letting CGAL be namespace \ccc{A}, we should not define templates in \cgal\ that are likely to conflict with templates in other namespaces (playing the role of \ccc{B}): Assume that both \cgal\ and some other namespace define an \ccc{is_zero()} template. Then an instantiation of some \cgal\ template using \ccc{is_zero()} that takes place inside the other namespace causes trouble. For this reason, we have another namespace \ccc{NTS}% \ccIndexSubitem{namespace}{\ccFont CGAL::NTS} nested in \ccc{CGAL}, which contains potentially conflicting template functions. \subsection{Which function calls should be qualified in \cgal\ code?} Out current policy is: \begin{itemize} \item \ccc{max} should be used without qualification\ccIndexGlobalFunction{max} \item \ccc{min} should be used without qualification\ccIndexGlobalFunction{min} \item For the following functions, templates are provided in nested namespace \ccc{NTS}: \begin{itemize} \item[]\ccc{abs}\ccIndexGlobalFunction{abs} \item[]\ccc{compare}\ccIndexGlobalFunction{compare} \item[]\ccc{gcd}\ccIndexGlobalFunction{gcd} \item[]\ccc{is_negative}\ccIndexGlobalFunction{is_negative} \item[]\ccc{is_positive}\ccIndexGlobalFunction{is_positive} \item[]\ccc{is_one}\ccIndexGlobalFunction{is_one} \item[]\ccc{is_zero}\ccIndexGlobalFunction{is_zero} \item[]\ccc{sign}\ccIndexGlobalFunction{sign} \item[]\ccc{lexicographical_sign}\ccIndexGlobalFunction{lexicographical_sign} \item[]\ccc{square}\ccIndexGlobalFunction{square} \end{itemize} Calls of the above functions should be qualified using macro \ccc{CGAL_NTS},% \index{CGAL_NTS macro@{\tt CGAL\_NTS} macro} which maps to \ccc{CGAL::NTS::}\footnote{The use of the macro eases future changes in our policy.}: For example, \begin{verbatim} if ( CGAL_NTS is_zero(0) ) { /* ... */ } \end{verbatim} Qualification with \ccc{CGAL} does not work. \item The following functions can be qualified by \ccc{CGAL_NTS} as well: \begin{itemize} \item[]\ccc{to_double}\ccIndexGlobalFunction{to_double} \item[]\ccc{is_valid}\ccIndexGlobalFunction{is_valid} \item[]\ccc{is_finite}\ccIndexGlobalFunction{is_finite} \item[]\ccc{sqrt}\ccIndexGlobalFunction{sqrt}\\ \item[]\ccc{div}\ccIndexGlobalFunction{div}\\ Whenever the argument of \ccc{sqrt} is a concrete type, \ie, it does not depend on a template parameter, you should qualify the call of \ccc{sqrt}, for example \verb+CGAL_CLIB_STD::sqrt(2.0)+ \end{itemize} Here, qualification with \ccc{CGAL} works as well. \end{itemize} Summarizing, you can always qualify functions on number types with \ccc{CGAL_NTS} besides \ccc{min} and \ccc{max}. \InternalOnly{ \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 qualify calls of \ccc{is_zero}, \ccc{is_one}, \ccc{is_negative}, \ccc{is_positive}, \ccc{sign}, \ccc{lexicographical_sign}, \ccc{abs}, \ccc{compare}, \ccc{square} by \texttt{CGAL\_NTS}. \ccIndexSubitem{qualification}{\ccFont CGAL_NTS}% \item use \texttt{CGAL\_CLIB\_STD} with C-library functions. \index{cgal_clib_std macro@{\tt CGAL\_CLIB\_STD} macro}% \ccIndexSubitem{qualification}{\ccFont CGAL_CLIB_STD}% \end{itemize} Recommendations: \begin{itemize} \item Don't qualify calls of \ccc{max} and \ccc{min}. \item Don't use \ccc{CGAL::} qualification inside namespace \ccc{CGAL},% \ccIndexSubitem{qualification}{\ccFont CGAL::} unless it is required by a compiler or to resolve a name conflict with a local type in a scope enclosed by namespace \ccc{CGAL}. \end{itemize} }