libstdc++-v3/doc/html/manual/using_namespaces.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Namespaces</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="
   2       ISO C++
   3     ,
   4       library
   5     "><meta name="keywords" content="
   6       ISO C++
   7     ,
   8       runtime
   9     ,
  10       library
  11     "><link rel="home" href="../index.html" title="The GNU C++ Library"><link rel="up" href="using.html" title="Chapter 3. Using"><link rel="prev" href="using_macros.html" title="Macros"><link rel="next" href="using_dynamic_or_shared.html" title="Linking"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr></table><hr></div><div class="section" title="Namespaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="section" title="Available Namespaces"><div class="titlepage"><div><div><h3 class="title"><a name="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
  12 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>std</p><p>The ISO C++ standards specify that "all library entities are defined
  13 within namespace std." This includes namespaces nested
  14 within <code class="code">namespace std</code>, such as <code class="code">namespace
  15 std::tr1</code>.
  16 </p></li><li class="listitem"><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
  17 function APIs supplemental to those required by the ISO C++ Standard,
  18 but necessary for interoperability.
  19 </p></li><li class="listitem"><p>__gnu_</p><p>Indicating one of several GNU extensions. Choices
  20 include <code class="code">__gnu_cxx</code>, <code class="code">__gnu_debug</code>, <code class="code">__gnu_parallel</code>,
  21 and <code class="code">__gnu_pbds</code>.
  22 </p></li></ul></div><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="link" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html" target="_top">documentation</a>.
  23 </p></div><div class="section" title="namespace std"><div class="titlepage"><div><div><h3 class="title"><a name="manual.intro.using.namespaces.std"></a>namespace std</h3></div></div></div><p>
  24       One standard requirement is that the library components are defined
  25       in <code class="code">namespace std::</code>. Thus, in order to use these types or
  26       functions, one must do one of two things:
  27 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>put a kind of <span class="emphasis"><em>using-declaration</em></span> in your source
  28 (either <code class="code">using namespace std;</code> or i.e. <code class="code">using
  29 std::string;</code>) This approach works well for individual source files, but
  30 should not be used in a global context, like header files.
  31           </p></li><li class="listitem"><p>use a <span class="emphasis"><em>fully
  32 qualified name</em></span> for each library symbol
  33 (i.e. <code class="code">std::string</code>, <code class="code">std::cout</code>) Always can be
  34 used, and usually enhanced, by strategic use of typedefs. (In the
  35 cases where the qualified verbiage becomes unwieldy.)
  36           </p></li></ul></div></div><div class="section" title="Using Namespace Composition"><div class="titlepage"><div><div><h3 class="title"><a name="manual.intro.using.namespaces.comp"></a>Using Namespace Composition</h3></div></div></div><p>
  37 Best practice in programming suggests sequestering new data or
  38 functionality in a sanely-named, unique namespace whenever
  39 possible. This is considered an advantage over dumping everything in
  40 the global namespace, as then name look-up can be explicitly enabled or
  41 disabled as above, symbols are consistently mangled without repetitive
  42 naming prefixes or macros, etc.
  43 </p><p>For instance, consider a project that defines most of its classes in <code class="code">namespace gtk</code>. It is possible to
  44         adapt <code class="code">namespace gtk</code> to <code class="code">namespace std</code> by using a C++-feature called
  45         <span class="emphasis"><em>namespace composition</em></span>. This is what happens if
  46         a <span class="emphasis"><em>using</em></span>-declaration is put into a
  47         namespace-definition: the imported symbol(s) gets imported into the
  48         currently active namespace(s). For example:
  49 </p><pre class="programlisting">
  50 namespace gtk
  51 {
  52   using std::string;
  53   using std::tr1::array;
  54
  55   class Window { ... };
  56 }
  57 </pre><p>
  58         In this example, <code class="code">std::string</code> gets imported into
  59         <code class="code">namespace gtk</code>.  The result is that use of
  60         <code class="code">std::string</code> inside namespace gtk can just use <code class="code">string</code>, without the explicit qualification.
  61         As an added bonus,
  62         <code class="code">std::string</code> does not get imported into
  63         the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
  64         <code class="code">using</code>-declarations can wrapped in macros that
  65         are set based on autoconf-tests to either "" or i.e. <code class="code">using
  66           std::string;</code> (depending on whether the system has
  67         libstdc++ in <code class="code">std::</code> or not).  (ideas from
  68         Llewelly and Karl Nelson)
  69 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_macros.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Linking</td></tr></table></div></body></html>