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

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