1<?xml version="1.0" encoding="utf-8"?>
2<!--
3  Copyright 2012 Eric Niebler
4
5  Distributed under the Boost
6  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<header name="boost/proto/transform/arg.hpp">
10  <para>Contains definition of the childN transforms and friends.</para>
11  <namespace name="boost">
12    <namespace name="proto">
13      <struct name="_expr">
14        <inherit><classname>proto::transform</classname>&lt; _expr &gt;</inherit>
15        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns the current expression unmodified. </purpose>
16        <description>
17          <para>
18            Example:
19            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
20<classname>proto::terminal</classname>&lt;int&gt;::type &amp; j = proto::_expr()(i);
21assert( boost::addressof(i) == boost::addressof(j) );</programlisting>
22          </para>
23        </description>
24        <struct name="impl">
25          <template>
26            <template-type-parameter name="Expr"/>
27            <template-type-parameter name="State"/>
28            <template-type-parameter name="Data"/>
29          </template>
30          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
31          <typedef name="result_type">
32            <type>Expr</type>
33          </typedef>
34          <method-group name="public member functions">
35            <method name="operator()" cv="const">
36              <type>Expr</type>
37              <parameter name="expr">
38                <paramtype>typename impl::expr_param</paramtype>
39                <description>
40                  <para>The current expression. </para>
41                </description>
42              </parameter>
43              <parameter name="">
44                <paramtype>typename impl::state_param</paramtype>
45              </parameter>
46              <parameter name="">
47                <paramtype>typename impl::data_param</paramtype>
48              </parameter>
49              <description>
50                <para>
51                  Returns the current expression.
52                </para>
53              </description>
54              <returns>
55                <para>
56                  <computeroutput>expr</computeroutput>
57                </para>
58              </returns>
59              <throws>
60                <simpara>Will not throw.</simpara>
61              </throws>
62            </method>
63          </method-group>
64        </struct>
65      </struct>
66
67      <struct name="_state">
68        <inherit><classname>proto::transform</classname>&lt; _state &gt;</inherit>
69        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns the current state unmodified. </purpose>
70        <description>
71          <para>
72            Example:
73            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
74char ch = proto::_state()(i, 'a');
75assert( ch == 'a' );</programlisting>
76          </para>
77        </description>
78        <struct name="impl">
79          <template>
80            <template-type-parameter name="Expr"/>
81            <template-type-parameter name="State"/>
82            <template-type-parameter name="Data"/>
83          </template>
84          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
85          <typedef name="result_type">
86            <type>State</type>
87          </typedef>
88          <method-group name="public member functions">
89            <method name="operator()" cv="const">
90              <type>State</type>
91              <parameter name="">
92                <paramtype>typename impl::expr_param</paramtype>
93              </parameter>
94              <parameter name="state">
95                <paramtype>typename impl::state_param</paramtype>
96                <description>
97                  <para>The current state. </para>
98                </description>
99              </parameter>
100              <parameter name="">
101                <paramtype>typename impl::data_param</paramtype>
102              </parameter>
103              <description>
104                <para>
105                  Returns the current state.
106                </para>
107              </description>
108              <returns>
109                <para>
110                  <computeroutput>state</computeroutput>
111                </para>
112              </returns>
113              <throws>
114                <simpara>Will not throw.</simpara>
115              </throws>
116            </method>
117          </method-group>
118        </struct>
119      </struct>
120
121      <struct name="_data">
122        <inherit><classname>proto::transform</classname>&lt; _data &gt;</inherit>
123        <purpose>
124          A <conceptname>PrimitiveTransform</conceptname> that returns the current data unmodified.
125          If the data (third) parameter is a transform environment, it returns the value associated
126          with the <code><classname>proto::data_type</classname></code> key. Otherwise, it returns
127          the data parameter unmodified.
128        </purpose>
129        <description>
130          <para>
131            If the data (third) parameter is a transform environment, it returns the value associated
132            with the <code><classname>proto::data_type</classname></code> key. Otherwise, it returns
133            the data parameter unmodified.
134          </para>
135          <para>
136            <emphasis role="bold">Example:</emphasis>
137            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
138std::string str("hello");
139std::string &amp; d1 = proto::_data()(i, 'a', str);
140assert( &amp;str == &amp;d1 );
141
142std::string &amp; d2 = proto::_data()(i, 'a', (<globalname>proto::data</globalname> = boost::ref(str)));
143assert( &amp;str == &amp;d2 );</programlisting>
144          </para>
145        </description>
146        <struct name="impl">
147          <template>
148            <template-type-parameter name="Expr"/>
149            <template-type-parameter name="State"/>
150            <template-type-parameter name="Data"/>
151          </template>
152          <inherit><type>
153    mpl::if_c&lt;
154      <classname>proto::is_env</classname>&lt;Data&gt;::value,
155      <classname>proto::_env_var</classname>&lt;<classname>proto::data_type</classname>&gt;,
156      <classname>proto::_env</classname>
157    &gt;::type::template impl&lt;Expr, State, Data&gt;</type></inherit>
158        </struct>
159      </struct>
160
161      <struct name="_child_c">
162        <template>
163          <template-nontype-parameter name="N">
164            <type>int</type>
165          </template-nontype-parameter>
166        </template>
167        <inherit><classname>proto::transform</classname>&lt; _child_c&lt;N&gt; &gt;</inherit>
168        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns N-th child of the current expression. </purpose>
169        <description>
170          <para>
171            Example:
172            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
173<classname>proto::terminal</classname>&lt;int&gt;::type &amp; j = proto::_child_c&lt;0&gt;()(-i);
174assert( boost::addressof(i) == boost::addressof(j) );</programlisting>
175          </para>
176        </description>
177        <struct name="impl">
178          <template>
179            <template-type-parameter name="Expr"/>
180            <template-type-parameter name="State"/>
181            <template-type-parameter name="Data"/>
182          </template>
183          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
184          <typedef name="result_type">
185            <type>typename <classname>proto::result_of::child_c</classname>&lt; Expr, N &gt;::type</type>
186          </typedef>
187          <method-group name="public member functions">
188            <method name="operator()" cv="const">
189              <type>typename <classname>proto::result_of::child_c</classname>&lt; Expr, N &gt;::type</type>
190              <parameter name="expr">
191                <paramtype>typename impl::expr_param</paramtype>
192                <description>
193                  <para>The current expression. </para>
194                </description>
195              </parameter>
196              <parameter name="">
197                <paramtype>typename impl::state_param</paramtype>
198              </parameter>
199              <parameter name="">
200                <paramtype>typename impl::data_param</paramtype>
201              </parameter>
202              <description>
203                <para>
204                  Returns the N-th child of <computeroutput>expr</computeroutput>
205                </para>
206              </description>
207              <requires>
208                <para>
209                  <computeroutput>Expr::proto_arity::value &gt; N</computeroutput>
210                </para>
211              </requires>
212              <returns>
213                <para>
214                  <computeroutput><functionname>proto::child_c</functionname>&lt;N&gt;(expr)</computeroutput>
215                </para>
216              </returns>
217              <throws>
218                <simpara>Will not throw.</simpara>
219              </throws>
220            </method>
221          </method-group>
222        </struct>
223      </struct>
224
225      <struct name="_value">
226        <inherit><classname>proto::transform</classname>&lt; _value &gt;</inherit>
227        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns the value of the current terminal expression. </purpose>
228        <description>
229          <para>
230            Example:
231            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
232int j = proto::_value()(i);
233assert( 42 == j );</programlisting>
234          </para>
235        </description>
236        <struct name="impl">
237          <template>
238            <template-type-parameter name="Expr"/>
239            <template-type-parameter name="State"/>
240            <template-type-parameter name="Data"/>
241          </template>
242          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
243          <typedef name="result_type">
244            <type>typename <classname>proto::result_of::value</classname>&lt; Expr &gt;::type</type>
245          </typedef>
246          <method-group name="public member functions">
247            <method name="operator()" cv="const">
248              <type>typename <classname>proto::result_of::value</classname>&lt; Expr &gt;::type</type>
249              <parameter name="expr">
250                <paramtype>typename impl::expr_param</paramtype>
251                <description>
252                  <para>The current expression. </para>
253                </description>
254              </parameter>
255              <parameter name="">
256                <paramtype>typename impl::state_param</paramtype>
257              </parameter>
258              <parameter name="">
259                <paramtype>typename impl::data_param</paramtype>
260              </parameter>
261              <description>
262                <para>
263                  Returns the value of the specified terminal expression.
264                </para>
265              </description>
266              <requires>
267                <para>
268                  <computeroutput>Expr::proto_arity::value == 0</computeroutput>.
269                </para>
270              </requires>
271              <returns>
272                <para>
273                  <computeroutput><functionname>proto::value</functionname>(expr)</computeroutput>
274                </para>
275              </returns>
276              <throws>
277                <simpara>Will not throw.</simpara>
278              </throws>
279            </method>
280          </method-group>
281        </struct>
282      </struct>
283
284      <struct name="_void">
285        <inherit><classname>proto::transform</classname>&lt; _void &gt;</inherit>
286        <purpose>A <conceptname>PrimitiveTransform</conceptname> that does nothing and returns void. </purpose>
287        <struct name="impl">
288          <template>
289            <template-type-parameter name="Expr"/>
290            <template-type-parameter name="State"/>
291            <template-type-parameter name="Data"/>
292          </template>
293          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
294          <typedef name="result_type">
295            <type>void</type>
296          </typedef>
297          <method-group name="public member functions">
298            <method name="operator()" cv="const">
299              <type>void</type>
300              <parameter name="">
301                <paramtype>typename impl::expr_param</paramtype>
302              </parameter>
303              <parameter name="">
304                <paramtype>typename impl::state_param</paramtype>
305              </parameter>
306              <parameter name="">
307                <paramtype>typename impl::data_param</paramtype>
308              </parameter>
309              <description>
310                <para>
311                  Does nothing.
312                </para>
313              </description>
314              <throws>
315                <simpara>Will not throw.</simpara>
316              </throws>
317            </method>
318          </method-group>
319        </struct>
320      </struct>
321
322      <struct name="_byref">
323        <inherit><classname>proto::callable</classname></inherit>
324        <purpose>A unary callable <conceptname>PolymorphicFunctionObject</conceptname> that wraps its argument
325          in a <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput>.</purpose>
326        <description>
327          <para>
328            Example:
329            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
330boost::reference_wrapper&lt;<classname>proto::terminal</classname>&lt;int&gt;::type&gt; j
331  = <classname>proto::when</classname>&lt;<classname>proto::_</classname>, proto::_byref(_)&gt;()(i);
332assert( boost::addressof(i) == boost::addressof(j.get()) );</programlisting>
333          </para>
334        </description>
335        <struct-specialization name="result">
336          <template>
337            <template-type-parameter name="This"/>
338            <template-type-parameter name="T"/>
339          </template>
340          <specialization>
341            <template-arg>This(T &amp;)</template-arg>
342          </specialization>
343          <typedef name="type">
344            <type>boost::reference_wrapper&lt; T &gt; const</type>
345          </typedef>
346        </struct-specialization>
347        <struct-specialization name="result">
348          <template>
349            <template-type-parameter name="This"/>
350            <template-type-parameter name="T"/>
351          </template>
352          <specialization>
353            <template-arg>This(T)</template-arg>
354          </specialization>
355          <typedef name="type">
356            <type>boost::reference_wrapper&lt; T const  &gt; const</type>
357          </typedef>
358        </struct-specialization>
359        <method-group name="public member functions">
360          <method name="operator()" cv="const">
361            <type>boost::reference_wrapper&lt; T &gt; const</type>
362            <template>
363              <template-type-parameter name="T"/>
364            </template>
365            <parameter name="t">
366              <paramtype>T &amp;</paramtype>
367              <description>
368                <para>The object to wrap </para>
369              </description>
370            </parameter>
371            <description>
372              <para>
373                Wrap the parameter <computeroutput>t</computeroutput> in a
374                <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput>
375              </para>
376            </description>
377            <returns>
378              <para>
379                <computeroutput>boost::ref(t)</computeroutput>
380              </para>
381            </returns>
382            <throws>
383              <simpara>Will not throw.</simpara>
384            </throws>
385          </method>
386          <method name="operator()" cv="const">
387            <type>boost::reference_wrapper&lt; T const &gt; const</type>
388            <template>
389              <template-type-parameter name="T"/>
390            </template>
391            <parameter name="t">
392              <paramtype>T const &amp;</paramtype>
393            </parameter>
394            <description>
395              <para>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </para>
396            </description>
397          </method>
398        </method-group>
399      </struct>
400
401      <struct name="_byval">
402        <inherit><classname>proto::callable</classname></inherit>
403        <purpose>
404          A unary callable <conceptname>PolymorphicFunctionObject</conceptname> that strips references and
405          <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput> from its argument.
406        </purpose>
407        <description>
408          <para>
409            Example:
410            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
411int j = 67;
412int k = <classname>proto::when</classname>&lt;<classname>proto::_</classname>, proto::_byval(<classname>proto::_state</classname>)&gt;()(i, boost::ref(j));
413assert( 67 == k );</programlisting>
414          </para>
415        </description>
416        <struct-specialization name="result">
417          <template>
418            <template-type-parameter name="This"/>
419            <template-type-parameter name="T"/>
420          </template>
421          <specialization>
422            <template-arg>This(boost::reference_wrapper&lt; T &gt;)</template-arg>
423          </specialization>
424          <inherit>result&lt;This(T)&gt;</inherit>
425        </struct-specialization>
426        <struct-specialization name="result">
427          <template>
428            <template-type-parameter name="This"/>
429            <template-type-parameter name="T"/>
430          </template>
431          <specialization>
432            <template-arg>This(T &amp;)</template-arg>
433          </specialization>
434          <inherit>result&lt;This(T)&gt;</inherit>
435        </struct-specialization>
436        <struct-specialization name="result">
437          <template>
438            <template-type-parameter name="This"/>
439            <template-type-parameter name="T"/>
440          </template>
441          <specialization>
442            <template-arg>This(T)</template-arg>
443          </specialization>
444          <typedef name="type">
445            <type>T</type>
446          </typedef>
447        </struct-specialization>
448        <method-group name="public member functions">
449          <method name="operator()" cv="const">
450            <type>T</type>
451            <template>
452              <template-type-parameter name="T"/>
453            </template>
454            <parameter name="t">
455              <paramtype>T const &amp;</paramtype>
456              <description>
457                <para>The object to unref </para>
458              </description>
459            </parameter>
460            <returns>
461              <para>
462                <computeroutput>t</computeroutput>
463              </para>
464            </returns>
465            <throws>
466              <simpara>Will not throw.</simpara>
467            </throws>
468          </method>
469          <method name="operator()" cv="const">
470            <type>T</type>
471            <template>
472              <template-type-parameter name="T"/>
473            </template>
474            <parameter name="t">
475              <paramtype>boost::reference_wrapper&lt; T &gt; const &amp;</paramtype>
476            </parameter>
477            <description>
478              <para>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </para>
479            </description>
480          </method>
481        </method-group>
482      </struct>
483    </namespace>
484  </namespace>
485</header>
486