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

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Semantics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="
   2       C++
   3     ,
   4       library
   5     ,
   6       debug
   7     "><meta name="keywords" content="
   8       ISO C++
   9     ,
  10       library
  11     "><meta name="keywords" content="
  12       ISO C++
  13     ,
  14       runtime
  15     ,
  16       library
  17     "><link rel="home" href="../index.html" title="The GNU C++ Library"><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode"><link rel="prev" href="debug_mode.html" title="Chapter 17. Debug Mode"><link rel="next" href="bk01pt03ch17s03.html" title="Using"></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">Semantics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="debug_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch17s03.html">Next</a></td></tr></table><hr></div><div class="section" title="Semantics"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="manual.ext.debug_mode.semantics"></a>Semantics</h2></div></div></div><p>
  18   </p><p>A program that uses the C++ standard library correctly
  19   will maintain the same semantics under debug mode as it had with
  20   the normal (release) library. All functional and exception-handling
  21   guarantees made by the normal library also hold for the debug mode
  22   library, with one exception: performance guarantees made by the
  23   normal library may not hold in the debug mode library. For
  24   instance, erasing an element in a <code class="code">std::list</code> is a
  25   constant-time operation in normal library, but in debug mode it is
  26   linear in the number of iterators that reference that particular
  27   list. So while your (correct) program won't change its results, it
  28   is likely to execute more slowly.</p><p>libstdc++ includes many extensions to the C++ standard library. In
  29   some cases the extensions are obvious, such as the hashed
  30   associative containers, whereas other extensions give predictable
  31   results to behavior that would otherwise be undefined, such as
  32   throwing an exception when a <code class="code">std::basic_string</code> is
  33   constructed from a NULL character pointer. This latter category also
  34   includes implementation-defined and unspecified semantics, such as
  35   the growth rate of a vector. Use of these extensions is not
  36   considered incorrect, so code that relies on them will not be
  37   rejected by debug mode. However, use of these extensions may affect
  38   the portability of code to other implementations of the C++ standard
  39   library, and is therefore somewhat hazardous. For this reason, the
  40   libstdc++ debug mode offers a "pedantic" mode (similar to
  41   GCC's <code class="code">-pedantic</code> compiler flag) that attempts to emulate
  42   the semantics guaranteed by the C++ standard. For
  43   instance, constructing a <code class="code">std::basic_string</code> with a NULL
  44   character pointer would result in an exception under normal mode or
  45   non-pedantic debug mode (this is a libstdc++ extension), whereas
  46   under pedantic debug mode libstdc++ would signal an error. To enable
  47   the pedantic debug mode, compile your program with
  48   both <code class="code">-D_GLIBCXX_DEBUG</code>
  49   and <code class="code">-D_GLIBCXX_DEBUG_PEDANTIC</code> .
  50   (N.B. In GCC 3.4.x and 4.0.0, due to a bug,
  51   <code class="code">-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has
  52   been fixed in GCC 4.0.1 and later versions.) </p><p>The following library components provide extra debugging
  53   capabilities in debug mode:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">std::basic_string</code> (no safe iterators and see note below)</p></li><li class="listitem"><p><code class="code">std::bitset</code></p></li><li class="listitem"><p><code class="code">std::deque</code></p></li><li class="listitem"><p><code class="code">std::list</code></p></li><li class="listitem"><p><code class="code">std::map</code></p></li><li class="listitem"><p><code class="code">std::multimap</code></p></li><li class="listitem"><p><code class="code">std::multiset</code></p></li><li class="listitem"><p><code class="code">std::set</code></p></li><li class="listitem"><p><code class="code">std::vector</code></p></li><li class="listitem"><p><code class="code">std::unordered_map</code></p></li><li class="listitem"><p><code class="code">std::unordered_multimap</code></p></li><li class="listitem"><p><code class="code">std::unordered_set</code></p></li><li class="listitem"><p><code class="code">std::unordered_multiset</code></p></li></ul></div><p>N.B. although there are precondition checks for some string operations,
  54 e.g.  <code class="code">operator[]</code>,
  55 they will not always be run when using the <code class="code">char</code> and
  56 <code class="code">wchar_t</code> specialisations (<code class="code">std::string</code> and
  57 <code class="code">std::wstring</code>).  This is because libstdc++ uses GCC's
  58 <code class="code">extern template</code> extension to provide explicit instantiations
  59 of <code class="code">std::string</code> and <code class="code">std::wstring</code>, and those
  60 explicit instantiations don't include the debug-mode checks.  If the
  61 containing functions are inlined then the checks will run, so compiling
  62 with <code class="code">-O1</code> might be enough to enable them.  Alternatively
  63 <code class="code">-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations
  64 of the explicit instantiations and cause the functions to be instantiated
  65 with the debug-mode checks included, but this is unsupported and not
  66 guaranteed to work.  For full debug-mode support you can use the
  67 <code class="code">__gnu_debug::basic_string</code> debugging container directly,
  68 which always works correctly.
  69 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug_mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch17s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 17. Debug Mode </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Using</td></tr></table></div></body></html>