l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.4/doc/xml/manual/algorithms.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
   4 [ ]>
   5
   6 <part id="manual.algorithms" xreflabel="Algorithms">
   7 <?dbhtml filename="algorithms.html"?>
   8
   9 <partinfo>
  10   <keywordset>
  11     <keyword>
  12       ISO C++
  13     </keyword>
  14     <keyword>
  15       library
  16     </keyword>
  17     <keyword>
  18       algorithm
  19     </keyword>
  20   </keywordset>
  21 </partinfo>
  22
  23 <title>
  24   Algorithms
  25   <indexterm><primary>Algorithms</primary></indexterm>
  26 </title>
  27
  28 <preface>
  29   <title></title>
  30 <para>
  31   The neatest accomplishment of the algorithms chapter is that all the
  32   work is done via iterators, not containers directly.  This means two
  33   important things:
  34 </para>
  35 <orderedlist>
  36       <listitem>
  37         <para>
  38           Anything that behaves like an iterator can be used in one of
  39           these algorithms.  Raw pointers make great candidates, thus
  40           built-in arrays are fine containers, as well as your own iterators.
  41         </para>
  42       </listitem>
  43       <listitem>
  44         <para>
  45           The algorithms do not (and cannot) affect the container as a
  46           whole; only the things between the two iterator endpoints.  If
  47           you pass a range of iterators only enclosing the middle third of
  48           a container, then anything outside that range is inviolate.
  49         </para>
  50       </listitem>
  51    </orderedlist>
  52    <para>
  53      Even strings can be fed through the algorithms here, although the
  54      string class has specialized versions of many of these functions
  55      (for example, <code>string::find()</code>).  Most of the examples
  56      on this page will use simple arrays of integers as a playground
  57      for algorithms, just to keep things simple.  The use of
  58      <emphasis>N</emphasis> as a size in the examples is to keep
  59      things easy to read but probably won't be valid code.  You can
  60      use wrappers such as those described in the <ulink
  61      url="../23_containers/howto.html">containers chapter</ulink> to
  62      keep real code readable.
  63    </para>
  64    <para>
  65      The single thing that trips people up the most is the definition
  66      of <emphasis>range</emphasis> used with iterators; the famous
  67      &quot;past-the-end&quot; rule that everybody loves to hate.  The
  68      <ulink url="../24_iterators/howto.html#2">iterators
  69      chapter</ulink> of this document has a complete explanation of
  70      this simple rule that seems to cause so much confusion.  Once you
  71      get <emphasis>range</emphasis> into your head (it's not that
  72      hard, honest!), then the algorithms are a cakewalk.
  73    </para>
  74 </preface>
  75
  76 <!-- Chapter 01 : Non Modifying -->
  77
  78 <!-- Chapter 02 : Mutating -->
  79 <chapter id="manual.algorithms.mutating" xreflabel="Mutating">
  80   <title>Mutating</title>
  81
  82   <sect1 id="algorithms.mutating.swap" xreflabel="swap">
  83     <title><function>swap</function></title>
  84
  85     <sect2 id="algorithms.swap.specializations" xreflabel="Specializations">
  86     <title>Specializations</title>
  87
  88    <para>If you call <code> std::swap(x,y); </code> where x and y are standard
  89       containers, then the call will automatically be replaced by a call to
  90       <code> x.swap(y); </code> instead.
  91    </para>
  92    <para>This allows member functions of each container class to take over, and
  93       containers' swap functions should have O(1) complexity according to
  94       the standard.  (And while &quot;should&quot; allows implementations to
  95       behave otherwise and remain compliant, this implementation does in
  96       fact use constant-time swaps.)  This should not be surprising, since
  97       for two containers of the same type to swap contents, only some
  98       internal pointers to storage need to be exchanged.
  99    </para>
 100
 101     </sect2>
 102   </sect1>
 103 </chapter>
 104
 105 <!-- Chapter 03 : Sorting -->
 106
 107 </part>