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

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Namespaces</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><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><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="sect1" title="Namespaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="sect2" title="Available Namespaces"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
</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
within namespace std." This includes namespaces nested
within <code class="code">namespace std</code>, such as <code class="code">namespace
std::tr1</code>.
</p></li><li class="listitem"><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
function APIs supplemental to those required by the ISO C++ Standard,
but necessary for interoperability.
</p></li><li class="listitem"><p>__gnu_</p><p>Indicating one of several GNU extensions. Choices
include <code class="code">__gnu_cxx</code>, <code class="code">__gnu_debug</code>, <code class="code">__gnu_parallel</code>,
and <code class="code">__gnu_pbds</code>.
</p></li></ul></div><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html" target="_top">documentation</a>.
</p></div><div class="sect2" title="namespace std"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.std"></a>namespace std</h3></div></div></div><p>
      One standard requirement is that the library components are defined
      in <code class="code">namespace std::</code>. Thus, in order to use these types or
      functions, one must do one of two things:
</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
(either <code class="code">using namespace std;</code> or i.e. <code class="code">using
std::string;</code>) This approach works well for individual source files, but
should not be used in a global context, like header files.
	  </p></li><li class="listitem"><p>use a <span class="emphasis"><em>fully
qualified name</em></span> for each library symbol
(i.e. <code class="code">std::string</code>, <code class="code">std::cout</code>) Always can be
used, and usually enhanced, by strategic use of typedefs. (In the
cases where the qualified verbiage becomes unwieldy.)
	  </p></li></ul></div></div><div class="sect2" title="Using Namespace Composition"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.comp"></a>Using Namespace Composition</h3></div></div></div><p>
Best practice in programming suggests sequestering new data or
functionality in a sanely-named, unique namespace whenever
possible. This is considered an advantage over dumping everything in
the global namespace, as then name look-up can be explicitly enabled or
disabled as above, symbols are consistently mangled without repetitive
naming prefixes or macros, etc.
</p><p>For instance, consider a project that defines most of its classes in <code class="code">namespace gtk</code>. It is possible to
	adapt <code class="code">namespace gtk</code> to <code class="code">namespace std</code> by using a C++-feature called
	<span class="emphasis"><em>namespace composition</em></span>. This is what happens if
	a <span class="emphasis"><em>using</em></span>-declaration is put into a
	namespace-definition: the imported symbol(s) gets imported into the
	currently active namespace(s). For example:
</p><pre class="programlisting">
namespace gtk
{
  using std::string;
  using std::tr1::array;

  class Window { ... };
}
</pre><p>
	In this example, <code class="code">std::string</code> gets imported into
	<code class="code">namespace gtk</code>.  The result is that use of
	<code class="code">std::string</code> inside namespace gtk can just use <code class="code">string</code>, without the explicit qualification.
	As an added bonus,
	<code class="code">std::string</code> does not get imported into
	the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
	<code class="code">using</code>-declarations can wrapped in macros that
	are set based on autoconf-tests to either "" or i.e. <code class="code">using
	  std::string;</code> (depending on whether the system has
	libstdc++ in <code class="code">std::</code> or not).  (ideas from
	Llewelly and Karl Nelson)
</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="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Linking</td></tr></table></div></body></html>
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								<?xml version="1.0" encoding="UTF-8" standalone="no"?>
 								<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-												using.xml: Update.

2010-02-18  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/using.xml: Update.
	* doc/xml/manual/status_cxx1998.xml: Same.
	* doc/xml/manual/status_cxx200x.xml: Add link.
	* doc/html/*: Regenerate.

	* testsuite/17_intro/freestanding.cc: Add.

From-SVN: r156871

											
										
										
											2010-02-18 19:52:12 +01:00
+								<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Namespaces</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><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><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="sect1" title="Namespaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="sect2" title="Available Namespaces"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
-												evolution.xml: Update for 4.4 and 4.5 releases.

2010-01-05  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/evolution.xml: Update for 4.4 and 4.5 releases.
	* doc/html: Regenerate.

From-SVN: r155661

											
										
										
											2010-01-05 21:51:05 +01:00
+								</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
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								within namespace std." This includes namespaces nested
 								within <code class="code">namespace std</code>, such as <code class="code">namespace
 								std::tr1</code>.
-												evolution.xml: Update for 4.4 and 4.5 releases.

2010-01-05  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/evolution.xml: Update for 4.4 and 4.5 releases.
	* doc/html: Regenerate.

From-SVN: r155661

											
										
										
											2010-01-05 21:51:05 +01:00
+								</p></li><li class="listitem"><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								function APIs supplemental to those required by the ISO C++ Standard,
 								but necessary for interoperability.
-												evolution.xml: Update for 4.4 and 4.5 releases.

2010-01-05  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/evolution.xml: Update for 4.4 and 4.5 releases.
	* doc/html: Regenerate.

From-SVN: r155661

											
										
										
											2010-01-05 21:51:05 +01:00
+								</p></li><li class="listitem"><p>__gnu_</p><p>Indicating one of several GNU extensions. Choices
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								include <code class="code">__gnu_cxx</code>, <code class="code">__gnu_debug</code>, <code class="code">__gnu_parallel</code>,
 								and <code class="code">__gnu_pbds</code>.
-												using.xml: Update.

2010-02-18  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/using.xml: Update.
	* doc/xml/manual/status_cxx1998.xml: Same.
	* doc/xml/manual/status_cxx200x.xml: Add link.
	* doc/html/*: Regenerate.

	* testsuite/17_intro/freestanding.cc: Add.

From-SVN: r156871

											
										
										
											2010-02-18 19:52:12 +01:00
+								</p></li></ul></div><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html" target="_top">documentation</a>.
-												evolution.xml: Update for 4.4 and 4.5 releases.

2010-01-05  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/evolution.xml: Update for 4.4 and 4.5 releases.
	* doc/html: Regenerate.

From-SVN: r155661

											
										
										
											2010-01-05 21:51:05 +01:00
+								</p></div><div class="sect2" title="namespace std"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.std"></a>namespace std</h3></div></div></div><p>
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								      One standard requirement is that the library components are defined
 								      in <code class="code">namespace std::</code>. Thus, in order to use these types or
 								      functions, one must do one of two things:
-												evolution.xml: Update for 4.4 and 4.5 releases.

2010-01-05  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/evolution.xml: Update for 4.4 and 4.5 releases.
	* doc/html: Regenerate.

From-SVN: r155661

											
										
										
											2010-01-05 21:51:05 +01:00
+								</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
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								(either <code class="code">using namespace std;</code> or i.e. <code class="code">using
 								std::string;</code>) This approach works well for individual source files, but
 								should not be used in a global context, like header files.
-												evolution.xml: Update for 4.4 and 4.5 releases.

2010-01-05  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/evolution.xml: Update for 4.4 and 4.5 releases.
	* doc/html: Regenerate.

From-SVN: r155661

											
										
										
											2010-01-05 21:51:05 +01:00
+									  </p></li><li class="listitem"><p>use a <span class="emphasis"><em>fully
-												using.xml: Update.

2010-02-18  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/using.xml: Update.
	* doc/xml/manual/status_cxx1998.xml: Same.
	* doc/xml/manual/status_cxx200x.xml: Add link.
	* doc/html/*: Regenerate.

	* testsuite/17_intro/freestanding.cc: Add.

From-SVN: r156871

											
										
										
											2010-02-18 19:52:12 +01:00
+								qualified name</em></span> for each library symbol
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								(i.e. <code class="code">std::string</code>, <code class="code">std::cout</code>) Always can be
 								used, and usually enhanced, by strategic use of typedefs. (In the
 								cases where the qualified verbiage becomes unwieldy.)
-												evolution.xml: Update for 4.4 and 4.5 releases.

2010-01-05  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/evolution.xml: Update for 4.4 and 4.5 releases.
	* doc/html: Regenerate.

From-SVN: r155661

											
										
										
											2010-01-05 21:51:05 +01:00
+									  </p></li></ul></div></div><div class="sect2" title="Using Namespace Composition"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.comp"></a>Using Namespace Composition</h3></div></div></div><p>
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								Best practice in programming suggests sequestering new data or
 								functionality in a sanely-named, unique namespace whenever
 								possible. This is considered an advantage over dumping everything in
 								the global namespace, as then name look-up can be explicitly enabled or
 								disabled as above, symbols are consistently mangled without repetitive
 								naming prefixes or macros, etc.
 								</p><p>For instance, consider a project that defines most of its classes in <code class="code">namespace gtk</code>. It is possible to
 									adapt <code class="code">namespace gtk</code> to <code class="code">namespace std</code> by using a C++-feature called
 									<span class="emphasis"><em>namespace composition</em></span>. This is what happens if
 									a <span class="emphasis"><em>using</em></span>-declaration is put into a
 									namespace-definition: the imported symbol(s) gets imported into the
 									currently active namespace(s). For example:
 								</p><pre class="programlisting">
-												using.xml: Update.

2010-02-18  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/using.xml: Update.
	* doc/xml/manual/status_cxx1998.xml: Same.
	* doc/xml/manual/status_cxx200x.xml: Add link.
	* doc/html/*: Regenerate.

	* testsuite/17_intro/freestanding.cc: Add.

From-SVN: r156871

											
										
										
											2010-02-18 19:52:12 +01:00
+								namespace gtk
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+								{
 								  using std::string;
 								  using std::tr1::array;
 								  class Window { ... };
 								}
 								</pre><p>
 									In this example, <code class="code">std::string</code> gets imported into
 									<code class="code">namespace gtk</code>.  The result is that use of
-												using.xml: Update.

2010-02-18  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/using.xml: Update.
	* doc/xml/manual/status_cxx1998.xml: Same.
	* doc/xml/manual/status_cxx200x.xml: Add link.
	* doc/html/*: Regenerate.

	* testsuite/17_intro/freestanding.cc: Add.

From-SVN: r156871

											
										
										
											2010-02-18 19:52:12 +01:00
+									<code class="code">std::string</code> inside namespace gtk can just use <code class="code">string</code>, without the explicit qualification.
 									As an added bonus,
-												html: Regenerate.

2009-04-15  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html: Regenerate.

From-SVN: r146140

											
										
										
											2009-04-16 01:31:04 +02:00
+									<code class="code">std::string</code> does not get imported into
 									the global namespace.  Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
 									<code class="code">using</code>-declarations can wrapped in macros that
 									are set based on autoconf-tests to either "" or i.e. <code class="code">using
 									  std::string;</code> (depending on whether the system has
 									libstdc++ in <code class="code">std::</code> or not).  (ideas from
-												run_doxygen: Correct nested scope on the man pages.

2010-01-07  Benjamin Kosnik  <bkoz@redhat.com>

	* scripts/run_doxygen: Correct nested scope on the man pages.
	* doc/xml/faq.xml: Edits, linkcheck, doxygen link reassociate.
	* doc/xml/manual/mt_allocator.xml: Same.
	* doc/xml/manual/allocator.xml: Same.
	* doc/xml/manual/codecvt.xml: Same.
	* doc/xml/manual/backwards_compatibility.xml: Same.
	* doc/xml/manual/concurrency.xml: Same.
	* doc/xml/manual/parallel_mode.xml: Same.
	* doc/xml/manual/io.xml: Same.
	* doc/xml/manual/support.xml: Same.
	* doc/xml/manual/evolution.xml: Same.
	* doc/xml/manual/using.xml: Same.
	* doc/xml/manual/extensions.xml: Same.
	* doc/xml/manual/appendix_contributing.xml: Same.
	* doc/xml/manual/prerequisites.xml: Same.
	* doc/xml/manual/diagnostics.xml: Same.
	* doc/xml/manual/spine.xml: Same.
	* doc/xml/manual/status_cxx200x.xml: Same.
	* doc/xml/manual/test.xml: Same.
	* doc/xml/spine.xml: Same.
	* doc/html/*: Regenerate.

	* include/profile/impl/profiler.h: Remove duplicate markup.

From-SVN: r155827

											
										
										
											2010-01-12 02:37:06 +01:00
+									Llewelly and Karl Nelson)
-												using.xml: Update.

2010-02-18  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/xml/manual/using.xml: Update.
	* doc/xml/manual/status_cxx1998.xml: Same.
	* doc/xml/manual/status_cxx200x.xml: Add link.
	* doc/html/*: Regenerate.

	* testsuite/17_intro/freestanding.cc: Add.

From-SVN: r156871

											
										
										
											2010-02-18 19:52:12 +01:00
+								</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="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Linking</td></tr></table></div></body></html>