libstdc++-v3/docs/html/20_util/howto.html

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   9    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
  10    <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
  11    <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20." />
  12    <meta name="GENERATOR" content="vi and eight fingers" />
  13    <title>libstdc++-v3 HOWTO:  Chapter 20: General Utilities</title>
  14 <link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
  15 <link rel="Start" href="../documentation.html" type="text/html"
  16   title="GNU C++ Standard Library" />
  17 <link rel="Prev" href="../19_diagnostics/howto.html" type="text/html"
  18   title="Diagnostics" />
  19 <link rel="Next" href="../21_strings/howto.html" type="text/html"
  20   title="Strings" />
  21 <link rel="Bookmark" href="allocator.html" type="text/html"
  22   title="Allocators and allocation" />
  23 <link rel="Copyright" href="../17_intro/license.html" type="text/html" />
  24 <link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
  25 </head>
  26 <body>
  27
  28 <h1 class="centered"><a name="top">Chapter 20:  General Utilities</a></h1>
  29
  30 <p>Chapter 20 deals with utility classes and functions, such as
  31    the oft-debated <code>auto_ptr&lt;&gt;</code>.
  32 </p>
  33
  34
  35 <!-- ####################################################### -->
  36 <hr />
  37 <h1>Contents</h1>
  38 <ul>
  39    <li><a href="#1"><code>auto_ptr</code> is not omnipotent</a></li>
  40    <li><a href="#2"><code>auto_ptr</code> inside container classes</a></li>
  41    <li><a href="#3">Functors</a></li>
  42    <li><a href="#4">Pairs</a></li>
  43    <li><a href="#5">Memory allocators</a></li>
  44 </ul>
  45
  46 <hr />
  47
  48 <!-- ####################################################### -->
  49
  50 <h2><a name="1"><code>auto_ptr</code> is not omnipotent</a></h2>
  51    <p>I'm not going to try and explain all of the fun and delicious
  52       things that can happen with misuse of the auto_ptr class template
  53       (called AP here), nor am I going to try and teach you how to use
  54       AP safely in the presence of copying.  The AP class is a really
  55       nifty idea for a smart pointer, but it is one of the dumbest of
  56       all the smart pointers -- and that's fine.
  57    </p>
  58    <p>AP is not meant to be a supersmart solution to all resource
  59       leaks everywhere.  Neither is it meant to be an effective form
  60       of garbage collection (although it can help, a little bit).
  61       And it can <em>not</em> be used for arrays!
  62    </p>
  63    <p>AP <em>is</em> meant to prevent nasty leaks in the presence of
  64       exceptions.  That's <em>all</em>.  This code is AP-friendly:
  65    </p>
  66    <pre>
  67     // not a recommend naming scheme, but good for web-based FAQs
  68     typedef std::auto_ptr&lt;MyClass&gt;  APMC;
  69
  70     extern function_taking_MyClass_pointer (MyClass*);
  71     extern some_throwable_function ();
  72
  73     void func (int data)
  74     {
  75         APMC  ap (new MyClass(data));
  76
  77         some_throwable_function();   // this will throw an exception
  78
  79         function_taking_MyClass_pointer (ap.get());
  80     }
  81    </pre>
  82    <p>When an exception gets thrown, the instance of MyClass that's
  83       been created on the heap will be <code>delete</code>'d as the stack is
  84       unwound past <code>func()</code>.
  85    </p>
  86    <p>Changing that code as follows is <em>not</em> AP-friendly:
  87    </p>
  88    <pre>
  89         APMC  ap (new MyClass[22]);
  90    </pre>
  91    <p>You will get the same problems as you would without the use
  92       of AP:
  93    </p>
  94    <pre>
  95         char*  array = new char[10];       // array new...
  96         ...
  97         delete array;                      // ...but single-object delete
  98    </pre>
  99    <p>AP cannot tell whether the pointer you've passed at creation points
 100       to one or many things.  If it points to many things, you are about
 101       to die.  AP is trivial to write, however, so you could write your
 102       own <code>auto_array_ptr</code> for that situation (in fact, this has
 103       been done many times; check the mailing lists, Usenet, Boost, etc).
 104    </p>
 105    <p>Return <a href="#top">to top of page</a> or
 106       <a href="../faq/index.html">to the FAQ</a>.
 107    </p>
 108
 109 <hr />
 110 <h2><a name="2"><code>auto_ptr</code> inside container classes</a></h2>
 111    <p>All of the <a href="../23_containers/howto.html">containers</a>
 112       described in the standard library require their contained types
 113       to have, among other things, a copy constructor like this:
 114    </p>
 115    <pre>
 116     struct My_Type
 117     {
 118         My_Type (My_Type const&amp;);
 119     };
 120    </pre>
 121    <p>Note the const keyword; the object being copied shouldn't change.
 122       The template class <code>auto_ptr</code> (called AP here) does not
 123       meet this requirement.  Creating a new AP by copying an existing
 124       one transfers ownership of the pointed-to object, which means that
 125       the AP being copied must change, which in turn means that the
 126       copy ctors of AP do not take const objects.
 127    </p>
 128    <p>The resulting rule is simple:  <em>Never ever use a container of
 129       auto_ptr objects.</em>  The standard says that &quot;undefined&quot;
 130       behavior is the result, but it is guaranteed to be messy.
 131    </p>
 132    <p>To prevent you from doing this to yourself, the
 133       <a href="../19_diagnostics/howto.html#3">concept checks</a> built
 134       in to this implementation will issue an error if you try to
 135       compile code like this:
 136    </p>
 137    <pre>
 138     #include &lt;vector&gt;
 139     #include &lt;memory&gt;
 140
 141     void f()
 142     {
 143         std::vector&lt; std::auto_ptr&lt;int&gt; &gt;   vec_ap_int;
 144     }
 145    </pre>
 146    <p>Should you try this with the checks enabled, you will see an error.
 147    </p>
 148    <p>Return <a href="#top">to top of page</a> or
 149       <a href="../faq/index.html">to the FAQ</a>.
 150    </p>
 151
 152 <hr />
 153 <h2><a name="3">Functors</a></h2>
 154    <p>If you don't know what functors are, you're not alone.  Many people
 155       get slightly the wrong idea.  In the interest of not reinventing
 156       the wheel, we will refer you to the introduction to the functor
 157       concept written by SGI as part of their STL, in
 158       <a href="http://www.sgi.com/tech/stl/functors.html">their
 159       http://www.sgi.com/tech/stl/functors.html</a>.
 160    </p>
 161    <p>Return <a href="#top">to top of page</a> or
 162       <a href="../faq/index.html">to the FAQ</a>.
 163    </p>
 164
 165 <hr />
 166 <h2><a name="4">Pairs</a></h2>
 167    <p>The <code>pair&lt;T1,T2&gt;</code> is a simple and handy way to
 168       carry around a pair of objects.  One is of type T1, and another of
 169       type T2; they may be the same type, but you don't get anything
 170       extra if they are.  The two members can be accessed directly, as
 171       <code>.first</code> and <code>.second</code>.
 172    </p>
 173    <p>Construction is simple.  The default ctor initializes each member
 174       with its respective default ctor.  The other simple ctor,
 175    </p>
 176    <pre>
 177     pair (const T1&amp; x, const T2&amp; y);
 178    </pre>
 179    <p>does what you think it does, <code>first</code> getting <code>x</code>
 180       and <code>second</code> getting <code>y</code>.
 181    </p>
 182    <p>There is a copy constructor, but it requires that your compiler
 183       handle member function templates:
 184    </p>
 185    <pre>
 186     template &lt;class U, class V&gt; pair (const pair&lt;U,V&gt;&amp; p);
 187    </pre>
 188    <p>The compiler will convert as necessary from U to T1 and from
 189       V to T2 in order to perform the respective initializations.
 190    </p>
 191    <p>The comparison operators are done for you.  Equality
 192       of two <code>pair&lt;T1,T2&gt;</code>s is defined as both <code>first</code>
 193       members comparing equal and both <code>second</code> members comparing
 194       equal; this simply delegates responsibility to the respective
 195       <code>operator==</code> functions (for types like MyClass) or builtin
 196       comparisons (for types like int, char, etc).
 197    </p>
 198    <p><a name="pairlt">
 199       The less-than operator is a bit odd the first time you see it.  It
 200       is defined as evaluating to:
 201       </a>
 202    </p>
 203    <pre>
 204     x.first  &lt;  y.first  ||
 205         ( !(y.first  &lt;  x.first)  &amp;&amp;  x.second  &lt;  y.second )
 206    </pre>
 207    <p>The other operators are not defined using the <code>rel_ops</code>
 208       functions above, but their semantics are the same.
 209    </p>
 210    <p>Finally, there is a template function called <code>make_pair</code>
 211       that takes two references-to-const objects and returns an
 212       instance of a pair instantiated on their respective types:
 213    </p>
 214    <pre>
 215     pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
 216    </pre>
 217    <p>Return <a href="#top">to top of page</a> or
 218       <a href="../faq/index.html">to the FAQ</a>.
 219    </p>
 220
 221 <hr />
 222 <h2><a name="5">Memory allocators</a></h2>
 223    <p>The available free store (&quot;heap&quot;) management classes are
 224       described <a href="allocator.html">here</a>.
 225    </p>
 226    <p>Return <a href="#top">to top of page</a> or
 227       <a href="../faq/index.html">to the FAQ</a>.
 228    </p>
 229
 230
 231 <!-- ####################################################### -->
 232
 233 <hr />
 234 <p class="fineprint"><em>
 235 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
 236 Comments and suggestions are welcome, and may be sent to
 237 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 238 </em></p>
 239
 240
 241 </body>
 242 </html>