Merge from trunk

[SVN r74791]

doc/algorithm.qbk

@@ -10,18 +10,20 @@
 
 [heading Lazy Evaluation]
 
-Unlike __mpl__, Fusion algorithms are lazy and non sequence-type
-preserving. What does that mean? It means that when you operate on a
-sequence through a Fusion algorithm that returns a sequence, the sequence
-returned may not be of the same class as the original. This is by design.
-Runtime efficiency is given a high priority. Like __mpl__, and unlike
-__stl__, fusion algorithms are functional in nature such that algorithms
+Unlike __mpl__, Fusion algorithms are lazy[footnote Except for some
+special cases such as __for_each__ and __copy__ which are inherently
+imperative algorithms.] and non sequence-type preserving [footnote What
+does that mean? It means that when you operate on a sequence through a
+Fusion algorithm that returns a sequence, the sequence returned may not
+be of the same class as the original]. This is by design. Runtime
+efficiency is given a high priority. Like __mpl__, and unlike __stl__,
+fusion algorithms are mostly functional in nature such that algorithms
 are non mutating (no side effects). However, due to the high cost of
 returning full sequences such as vectors and lists, /Views/ are returned
 from Fusion algorithms instead. For example, the __transform__ algorithm
 does not actually return a transformed version of the original sequence.
-__transform__ returns a __transform_view__. This view holds a reference to
-the original sequence plus the transform function. Iteration over the
+__transform__ returns a __transform_view__. This view holds a reference
+to the original sequence plus the transform function. Iteration over the
 __transform_view__ will apply the transform function over the sequence
 elements on demand. This /lazy/ evaluation scheme allows us to chain as
 many algorithms as we want without incurring a high runtime penalty.
@@ -37,6 +39,7 @@ the original sequence `s` and the value `x`. Functions that were once
 sequence specific and need to be implemented N times over N different
 sequences are now implemented only once. That is to say that Fusion
 sequences are cheaply extensible.
+
 To regain the original sequence, __conversion__ functions are provided. You
 may use one of the __conversion__ functions to convert back to the original
 sequence type.
@@ -46,6 +49,61 @@ sequence type.
     #include <boost/fusion/algorithm.hpp>
     #include <boost/fusion/include/algorithm.hpp>
 
+[section Auxiliary]
+
+The auxiliary algorithms provide the utility algorithms for sequences.
+
+[heading Header]
+
+    #include <boost/fusion/algorithm/auxiliary.hpp>
+    #include <boost/fusion/include/auxiliary.hpp>
+
+[section Functions]
+
+[section copy]
+
+[heading Description]
+Copy a sequence `src` to a sequence `dest`.
+It is also used to convert sequence into other.
+
+[heading Synopsis]
+    template <typename Seq1, typename Seq2>
+    void copy(Seq1 const& src, Seq2& dest);
+
+[table Parameters
+    [[Parameter][Requirement][Description]]
+    [[`src`][A model of __forward_sequence__, all elements contained in the `src` sequence should be convertible into the element contained in the `dest` sequence.][Operation's argument]]
+    [[`dest`][A model of __forward_sequence__, `e2 = e1` is valid expression for each pair of elements `e1` of `src` and `e2` of `dest`.][Operation's argument]]
+]
+
+[heading Expression Semantics]
+    __copy__(src, dest);
+
+[*Return type]: `void`
+
+[*Semantics]: `e2 = e1` for each element `e1` in `src` and `e2` in `dest`.
+
+[heading Complexity]
+Linear, exactly `__result_of_size__<Sequence>::value`.
+
+[heading Header]
+
+    #include <boost/fusion/algorithm/auxiliary/copy.hpp>
+    #include <boost/fusion/include/copy.hpp>
+
+[heading Example]
+    __vector__<int,int> vec(1,2);
+    __list__<int,int> ls;
+    __copy__(vec, ls);
+    assert(ls == __make_list__(1,2));
+
+[endsect]
+
+[endsect]
+
+[endsect]
+
+
 [section Iteration]
 
 The iteration algorithms provide the fundamental algorithms for traversing