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

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