1[/==============================================================================
2    Copyright (C) 2001-2010 Joel de Guzman
3    Copyright (C) 2001-2005 Dan Marsden
4    Copyright (C) 2001-2010 Thomas Heller
5
6    Distributed under the Boost Software License, Version 1.0. (See accompanying
7    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8===============================================================================/]
9
10[section STL]
11
12    #include <boost/phoenix/stl.hpp>
13
14This section summarizes the lazy equivalents of C++ Standard Library functionality
15
16[section Container]
17
18    #include <boost/phoenix/stl/container.hpp>
19
20The container module predefines a set of lazy functions that work on STL
21containers. These functions provide a mechanism for the lazy evaluation of the
22public member functions of the STL containers. The lazy functions are thin
23wrappers that simply forward to their respective counterparts in the STL
24library.
25
26Lazy functions are provided for all of the member functions of the following
27containers:
28
29* deque
30* list
31* map
32* multimap
33* vector
34* set
35* multiset
36
37Indeed, should your class have member functions with the same names and
38signatures as those listed below, then it will automatically be supported. To
39summarize, lazy functions are provided for member functions:
40
41* assign
42* at
43* back
44* begin
45* capacity
46* clear
47* empty
48* end
49* erase
50* front
51* get_allocator
52* insert
53* key_comp
54* max_size
55* pop_back
56* pop_front
57* push_back
58* push_front
59* rbegin
60* rend
61* reserve
62* resize
63* size
64* splice
65* value_comp
66
67The lazy functions' names are the same as the corresponding member function. The
68difference is that the lazy functions are free functions and therefore does not
69use the member "dot" syntax.
70
71[table Sample usage
72    [["Normal" version]                 ["Lazy" version]]
73    [[`my_vector.at(5)`]                [`at(arg1, 5)`]]
74    [[`my_list.size()`]                 [`size(arg1)`]]
75    [[`my_vector1.swap(my_vector2)`]    [`swap(arg1, arg2)`]]
76]
77
78Notice that member functions with names that clash with stl algorithms are
79absent. This will be provided in Phoenix's algorithm module.
80
81No support is provided here for lazy versions of `operator+=`, `operator[]` etc.
82Such operators are not specific to STL containers and lazy versions can
83therefore be found in [link phoenix.modules.operator operators].
84
85The following table describes the container functions and their semantics.
86
87[blurb __tip__ Arguments in brackets denote optional parameters.]
88
89[table Lazy STL Container Functions
90    [[Function]                         [Semantics]]
91    [[`assign(c, a[, b, c])`]           [`c.assign(a[, b, c])`]]
92    [[`at(c, i)`]                       [`c.at(i)`]]
93    [[`back(c)`]                        [`c.back()`]]
94    [[`begin(c)`]                       [`c.begin()`]]
95    [[`capacity(c)`]                    [`c.capacity()`]]
96    [[`clear(c)`]                       [`c.clear()`]]
97    [[`empty(c)`]                       [`c.empty()`]]
98    [[`end(c)`]                         [`c.end()`]]
99    [[`erase(c, a[, b])`]               [`c.erase(a[, b])`]]
100    [[`front(c)`]                       [`c.front()`]]
101    [[`get_allocator(c)`]               [`c.get_allocator()`]]
102    [[`insert(c, a[, b, c])`]           [`c.insert(a[, b, c])`]]
103    [[`key_comp(c)`]                    [`c.key_comp()`]]
104    [[`max_size(c)`]                    [`c.max_size()`]]
105    [[`pop_back(c)`]                    [`c.pop_back()`]]
106    [[`pop_front(c)`]                   [`c.pop_front()`]]
107    [[`push_back(c, d)`]                [`c.push_back(d)`]]
108    [[`push_front(c, d)`]               [`c.push_front(d)`]]
109    [[`pop_front(c)`]                   [`c.pop_front()`]]
110    [[`rbegin(c)`]                      [`c.rbegin()`]]
111    [[`rend(c)`]                        [`c.rend()`]]
112    [[`reserve(c, n)`]                  [`c.reserve(n)`]]
113    [[`resize(c, a[, b])`]              [`c.resize(a[, b])`]]
114    [[`size(c)`]                        [`c.size()`]]
115    [[`splice(c, a[, b, c, d])`]        [`c.splice(a[, b, c, d])`]]
116    [[`value_comp(c)`]                  [`c.value_comp()`]]
117]
118
119[endsect]
120
121[section Algorithm]
122
123    #include <boost/phoenix/stl/algorithm.hpp>
124
125The algorithm module provides wrappers for the standard algorithms in the
126`<algorithm>` and `<numeric>` headers.
127
128The algorithms are divided into the categories iteration, transformation and querying,
129modeling the __boost_mpl__ library. The different algorithm classes can be
130included using the headers:
131
132    #include <boost/phoenix/stl/algorithm/iteration.hpp>
133    #include <boost/phoenix/stl/algorithm/transformation.hpp>
134    #include <boost/phoenix/stl/algorithm/querying.hpp>
135
136The functions of the algorithm module take ranges as arguments where
137appropriate. This is different to the standard
138library, but easy enough to pick up. Ranges are described in detail in the
139__boost_range__ library.
140
141For example, using the standard copy algorithm to copy between 2 arrays:
142
143    int array[] = {1, 2, 3};
144    int output[3];
145    std::copy(array, array + 3, output); // We have to provide iterators
146                                         // to both the start and end of array
147
148The analogous code using the phoenix algorithm module is:
149
150    int array[] = {1, 2, 3};
151    int output[3];
152    copy(arg1, arg2)(array, output); // Notice only 2 arguments, the end of
153                                     // array is established automatically
154
155The __boost_range__ library provides support for standard containers, strings and
156arrays, and can be extended to support additional types.
157
158The following tables describe the different categories of algorithms, and their
159semantics.
160
161[blurb __tip__ Arguments in brackets denote optional parameters.]
162
163[table Iteration Algorithms
164    [[Function]                         [stl Semantics]]
165    [[`for_each(r, f)`]                 [`for_each(begin(r), end(r), f)`]]
166    [[`accumulate(r, o[, f])`]          [`accumulate(begin(r), end(r), o[, f])`]]
167]
168
169[table Querying Algorithms
170    [[Function]                         [stl Semantics]]
171    [[`find(r, a)`]                     [`find(begin(r), end(r), a)`]]
172    [[`find_if(r, f)`]                  [`find_if(begin(r), end(r), f)`]]
173    [[`find_end(r1, r2[, f])`]          [`find_end(begin(r1), end(r1), begin(r2), end(r2)[, f])`]]
174    [[`find_first_of(r1, r2[, f])`]     [`find_first_of(begin(r1), end(r1), begin(r2), end(r2)[, f])`]]
175    [[`adjacent_find(r[, f])`]          [`adjacent_find(begin(r), end(r)[, f])`]]
176    [[`count(r, a)`]                    [`count(begin(r), end(r), a)`]]
177    [[`count_if(r, f)`]                 [`count_if(begin(r), end(r), f)`]]
178    [[`distance(r)`]                    [`distance(begin(r), end(r))`]]
179    [[`mismatch(r, i[, f])`]            [`mismatch(begin(r), end(r), i[, f])`]]
180    [[`equal(r, i[, f])`]               [`equal(begin(r), end(r), i[, f])`]]
181    [[`search(r1, r2[, f])`]            [`search(begin(r1), end(r1), begin(r2), end(r2)[, f])`]]
182    [[`lower_bound(r, a[, f])`]         [`lower_bound(begin(r), end(r), a[, f])`]]
183    [[`upper_bound(r, a[, f])`]         [`upper_bound(begin(r), end(r), a[, f])`]]
184    [[`equal_range(r, a[, f])`]         [`equal_range(begin(r), end(r), a[, f])`]]
185    [[`binary_search(r, a[, f])`]       [`binary_search(begin(r), end(r), a[, f])`]]
186    [[`includes(r1, r2[, f])`]          [`includes(begin(r1), end(r1), begin(r2), end(r2)[, f])`]]
187    [[`min_element(r[, f])`]            [`min_element(begin(r), end(r)[, f])`]]
188    [[`max_element(r[, f])`]            [`max_element(begin(r), end(r)[, f])`]]
189    [[`lexicographical_compare(r1, r2[, f])`]   [`lexicographical_compare(begin(r1), end(r1), begin(r2), end(r2)[, f])`]]
190]
191
192[table Transformation Algorithms
193    [[Function]                         [stl Semantics]                                 [Language Standards]]
194    [[`copy(r, o)`]                     [`copy(begin(r), end(r), o)`]                   []]
195    [[`copy_backward(r, o)`]            [`copy_backward(begin(r), end(r), o)`]          []]
196    [[`transform(r, o, f)`]             [`transform(begin(r), end(r), o, f)`]           []]
197    [[`transform(r, i, o, f)`]          [`transform(begin(r), end(r), i, o, f)`]        []]
198    [[`replace(r, a, b)`]               [`replace(begin(r), end(r), a, b)`]             []]
199    [[`replace_if(r, f, a)`]            [`replace(begin(r), end(r), f, a)`]             []]
200    [[`replace_copy(r, o, a, b)`]       [`replace_copy(begin(r), end(r), o, a, b)`]     []]
201    [[`replace_copy_if(r, o, f, a)`]    [`replace_copy_if(begin(r), end(r), o, f, a)`]  []]
202    [[`fill(r, a)`]                     [`fill(begin(r), end(r), a)`]                   []]
203    [[`fill_n(r, n, a)`]                [`fill_n(begin(r), n, a)`]                      []]
204    [[`generate(r, f)`]                 [`generate(begin(r), end(r), f)`]               []]
205    [[`generate_n(r, n, f)`]            [`generate_n(begin(r), n, f)`]                  []]
206    [[`remove(r, a)`]                   [`remove(begin(r), end(r), a)`]                 []]
207    [[`remove_if(r, f)`]                [`remove_if(begin(r), end(r), f)`]              []]
208    [[`remove_copy(r, o, a)`]           [`remove_copy(begin(r), end(r), o, a)`]         []]
209    [[`remove_copy_if(r, o, f)`]        [`remove_copy_if(begin(r), end(r), o, f)`]      []]
210    [[`unique(r[, f])`]                 [`unique(begin(r), end(r)[, f])`]               []]
211    [[`unique_copy(r, o[, f])`]         [`unique_copy(begin(r), end(r), o[, f])`]       []]
212    [[`reverse(r)`]                     [`reverse(begin(r), end(r))`]                   []]
213    [[`reverse_copy(r, o)`]             [`reverse_copy(begin(r), end(r), o)`]           []]
214    [[`rotate(r, m)`]                   [`rotate(begin(r), m, end(r))`]                 []]
215    [[`rotate_copy(r, m, o)`]           [`rotate_copy(begin(r), m, end(r), o)`]         []]
216    [[`random_shuffle(r[, f])`]         [`random_shuffle(begin(r), end(r), f)`]         [Until C++17]]
217    [[`partition(r, f)`]                [`partition(begin(r), end(r), f)`]              []]
218    [[`stable_partition(r, f)`]         [`stable_partition(begin(r), end(r), f)`]       []]
219    [[`sort(r[, f])`]                   [`sort(begin(r), end(r)[, f])`]                 []]
220    [[`stable_sort(r[, f])`]            [`stable_sort(begin(r), end(r)[, f])`]          []]
221    [[`partial_sort(r, m[, f])`]        [`partial_sort(begin(r), m, end(r)[, f])`]      []]
222    [[`partial_sort_copy(r1, r2[, f])`] [`partial_sort_copy(begin(r1), end(r1), begin(r2), end(r2)[, f])`]      []]
223    [[`nth_element(r, n[, f])`]         [`nth_element(begin(r), n, end(r)[, f])`]       []]
224    [[`merge(r1, r2, o[, f])`]          [`merge(begin(r1), end(r1), begin(r2), end(r2), o[, f])`]               []]
225    [[`inplace_merge(r, m[, f])`]       [`inplace_merge(begin(r), m, end(r)[, f])`]     []]
226    [[`set_union(r1, r2, o[, f])`]          [`set_union(begin(r1), end(r1), begin(r2), end(r2)[, f])`]          []]
227    [[`set_intersection(r1, r2, o[, f])`]   [`set_intersection(begin(r1), end(r1), begin(r2), end(r2)[, f])`]   []]
228    [[`set_difference(r1, r2, o[, f])`]     [`set_difference(begin(r1), end(r1), begin(r2), end(r2)[, f])`]     []]
229    [[`set_symmetric_difference(r1, r2, o[, f])`]   [`set_symmetric_difference(begin(r1), end(r1), begin(r2), end(r2)[, f])`]   []]
230    [[`push_heap(r[, f])`]              [`push_heap(begin(r), end(r)[, f])`]            []]
231    [[`pop_heap(r[, f])`]               [`pop_heap(begin(r), end(r)[, f])`]             []]
232    [[`make_heap(r[, f])`]              [`make_heap(begin(r), end(r)[, f])`]            []]
233    [[`sort_heap(r[, f])`]              [`sort_heap(begin(r), end(r)[, f])`]            []]
234    [[`next_permutation(r[, f])`]       [`next_permutation(begin(r), end(r)[, f])`]     []]
235    [[`prev_permutation(r[, f])`]       [`prev_permutation(begin(r), end(r)[, f])`]     []]
236
237    [[`inner_product(r, o, a[, f1, f2])`]   [`inner_product(begin(r), end(r), o[, f1, f2])`]    []]
238    [[`partial_sum(r, o[, f])`]             [`partial_sum(begin(r), end(r), o[, f])`]           []]
239    [[`adjacent_difference(r, o[, f])`]     [`adjacent_difference(begin(r), end(r), o[, f])`]   []]
240]
241
242[endsect]
243
244[endsect]
245