libstdc++-v3/doc/xml/manual/utilities.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
   4 [ ]>
   5
   6 <chapter id="std.util" xreflabel="Utilities">
   7 <?dbhtml filename="utilities.html"?>
   8
   9 <chapterinfo>
  10   <keywordset>
  11     <keyword>
  12       ISO C++
  13     </keyword>
  14     <keyword>
  15       library
  16     </keyword>
  17   </keywordset>
  18 </chapterinfo>
  19
  20 <title>
  21   Utilities
  22   <indexterm><primary>Utilities</primary></indexterm>
  23 </title>
  24
  25 <!-- Section 01 : Functors -->
  26 <section id="std.util.functors" xreflabel="Functors">
  27 <?dbhtml filename="functors.html"?>
  28   <title>Functors</title>
  29    <para>If you don't know what functors are, you're not alone.  Many people
  30       get slightly the wrong idea.  In the interest of not reinventing
  31       the wheel, we will refer you to the introduction to the functor
  32       concept written by SGI as chapter of their STL, in
  33       <ulink url="http://www.sgi.com/tech/stl/functors.html">their
  34       http://www.sgi.com/tech/stl/functors.html</ulink>.
  35    </para>
  36 </section>
  37
  38 <!-- Section 02 : Pairs -->
  39 <section id="std.util.pairs" xreflabel="Pairs">
  40 <?dbhtml filename="pairs.html"?>
  41   <title>Pairs</title>
  42    <para>The <code>pair&lt;T1,T2&gt;</code> is a simple and handy way to
  43       carry around a pair of objects.  One is of type T1, and another of
  44       type T2; they may be the same type, but you don't get anything
  45       extra if they are.  The two members can be accessed directly, as
  46       <code>.first</code> and <code>.second</code>.
  47    </para>
  48    <para>Construction is simple.  The default ctor initializes each member
  49       with its respective default ctor.  The other simple ctor,
  50    </para>
  51    <programlisting>
  52     pair (const T1&amp; x, const T2&amp; y);
  53    </programlisting>
  54    <para>does what you think it does, <code>first</code> getting <code>x</code>
  55       and <code>second</code> getting <code>y</code>.
  56    </para>
  57    <para>There is a copy constructor, but it requires that your compiler
  58       handle member function templates:
  59    </para>
  60    <programlisting>
  61     template &lt;class U, class V&gt; pair (const pair&lt;U,V&gt;&amp; p);
  62    </programlisting>
  63    <para>The compiler will convert as necessary from U to T1 and from
  64       V to T2 in order to perform the respective initializations.
  65    </para>
  66    <para>The comparison operators are done for you.  Equality
  67       of two <code>pair&lt;T1,T2&gt;</code>s is defined as both <code>first</code>
  68       members comparing equal and both <code>second</code> members comparing
  69       equal; this simply delegates responsibility to the respective
  70       <code>operator==</code> functions (for types like MyClass) or builtin
  71       comparisons (for types like int, char, etc).
  72    </para>
  73    <para>
  74       The less-than operator is a bit odd the first time you see it.  It
  75       is defined as evaluating to:
  76    </para>
  77    <programlisting>
  78     x.first  &lt;  y.first  ||
  79         ( !(y.first  &lt;  x.first)  &amp;&amp;  x.second  &lt;  y.second )
  80    </programlisting>
  81    <para>The other operators are not defined using the <code>rel_ops</code>
  82       functions above, but their semantics are the same.
  83    </para>
  84    <para>Finally, there is a template function called <function>make_pair</function>
  85       that takes two references-to-const objects and returns an
  86       instance of a pair instantiated on their respective types:
  87    </para>
  88    <programlisting>
  89     pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
  90    </programlisting>
  91
  92 </section>
  93
  94 <!-- Section 03 : Memory -->
  95 <section id="std.util.memory" xreflabel="Memory">
  96 <?dbhtml filename="memory.html"?>
  97   <title>Memory</title>
  98   <para>
  99     Memory contains three general areas. First, function and operator
 100     calls via <function>new</function> and <function>delete</function>
 101     operator or member function calls.  Second, allocation via
 102     <classname>allocator</classname>. And finally, smart pointer and
 103     intelligent pointer abstractions.
 104   </para>
 105
 106   <!--  Section 01 : allocator -->
 107   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 108               parse="xml" href="allocator.xml">
 109   </xi:include>
 110
 111   <!--  Section 02 : auto_ptr -->
 112   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 113               parse="xml" href="auto_ptr.xml">
 114   </xi:include>
 115
 116   <!--  Section 03 : shared_ptr -->
 117   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 118               parse="xml" href="shared_ptr.xml">
 119   </xi:include>
 120
 121 </section>
 122
 123 <!-- Section 04 : Traits -->
 124 <section id="std.util.traits" xreflabel="Traits">
 125 <?dbhtml filename="traits.html"?>
 126   <title>Traits</title>
 127   <para>
 128   </para>
 129 </section>
 130
 131 </chapter>