1 files changed, 101 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/xml/manual/algorithms.xml b/libstdc++-v3/doc/xml/manual/algorithms.xml
new file mode 100644
index 000000000..831fe5fe6
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/algorithms.xml
@@ -0,0 +1,101 @@
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" 
+	 xml:id="std.algorithms" xreflabel="Algorithms">
+<?dbhtml filename="algorithms.html"?>
+
+<info><title>
+  Algorithms
+  <indexterm><primary>Algorithms</primary></indexterm>
+</title>
+  <keywordset>
+    <keyword>
+      ISO C++
+    </keyword>
+    <keyword>
+      library
+    </keyword>
+    <keyword>
+      algorithm
+    </keyword>
+  </keywordset>
+</info>
+
+
+
+<para>
+  The neatest accomplishment of the algorithms sect1 is that all the
+  work is done via iterators, not containers directly.  This means two
+  important things:
+</para>
+<orderedlist inheritnum="ignore" continuation="restarts">
+  <listitem>
+    <para>
+      Anything that behaves like an iterator can be used in one of
+      these algorithms.  Raw pointers make great candidates, thus
+      built-in arrays are fine containers, as well as your own
+      iterators.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      The algorithms do not (and cannot) affect the container as a
+      whole; only the things between the two iterator endpoints.  If
+      you pass a range of iterators only enclosing the middle third of
+      a container, then anything outside that range is inviolate.
+    </para>
+  </listitem>
+</orderedlist>
+<para>
+  Even strings can be fed through the algorithms here, although the
+  string class has specialized versions of many of these functions
+  (for example, <code>string::find()</code>).  Most of the examples
+  on this page will use simple arrays of integers as a playground
+  for algorithms, just to keep things simple.  The use of
+  <emphasis>N</emphasis> as a size in the examples is to keep things
+  easy to read but probably won't be valid code.  You can use wrappers
+  such as those described in
+  the <link linkend="std.containers">containers sect1</link> to keep
+  real code readable.
+</para>
+<para>
+  The single thing that trips people up the most is the definition
+  of <emphasis>range</emphasis> used with iterators; the famous
+  "past-the-end" rule that everybody loves to hate.  The
+  <link linkend="std.iterators">iterators sect1</link> of this
+    document has a complete explanation of this simple rule that seems
+    to cause so much confusion.  Once you
+    get <emphasis>range</emphasis> into your head (it's not that hard,
+    honest!), then the algorithms are a cakewalk.
+</para>
+
+<!-- Sect1 01 : Non Modifying -->
+
+<!-- Sect1 02 : Mutating -->
+<section xml:id="std.algorithms.mutating" xreflabel="Mutating"><info><title>Mutating</title></info>
+  
+
+  <section xml:id="algorithms.mutating.swap" xreflabel="swap"><info><title><function>swap</function></title></info>
+    
+
+    <section xml:id="algorithms.swap.specializations" xreflabel="Specializations"><info><title>Specializations</title></info>
+    
+
+   <para>If you call <code> std::swap(x,y); </code> where x and y are standard
+      containers, then the call will automatically be replaced by a call to
+      <code> x.swap(y); </code> instead.
+   </para>
+   <para>This allows member functions of each container class to take over, and
+      containers' swap functions should have O(1) complexity according to
+      the standard.  (And while "should" allows implementations to
+      behave otherwise and remain compliant, this implementation does in
+      fact use constant-time swaps.)  This should not be surprising, since
+      for two containers of the same type to swap contents, only some
+      internal pointers to storage need to be exchanged.
+   </para>
+
+    </section>
+  </section>
+</section>
+
+<!-- Sect1 03 : Sorting -->
+
+</chapter>