boost/libs/proto/doc/reference/transform/arg.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
  Copyright 2012 Eric Niebler

  Distributed under the Boost
  Software License, Version 1.0. (See accompanying
  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  -->
<header name="boost/proto/transform/arg.hpp">
  <para>Contains definition of the childN transforms and friends.</para>
  <namespace name="boost">
    <namespace name="proto">
      <struct name="_expr">
        <inherit><classname>proto::transform</classname>&lt; _expr &gt;</inherit>
        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns the current expression unmodified. </purpose>
        <description>
          <para>
            Example:
            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
<classname>proto::terminal</classname>&lt;int&gt;::type &amp; j = proto::_expr()(i);
assert( boost::addressof(i) == boost::addressof(j) );</programlisting>
          </para>
        </description>
        <struct name="impl">
          <template>
            <template-type-parameter name="Expr"/>
            <template-type-parameter name="State"/>
            <template-type-parameter name="Data"/>
          </template>
          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
          <typedef name="result_type">
            <type>Expr</type>
          </typedef>
          <method-group name="public member functions">
            <method name="operator()" cv="const">
              <type>Expr</type>
              <parameter name="expr">
                <paramtype>typename impl::expr_param</paramtype>
                <description>
                  <para>The current expression. </para>
                </description>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::state_param</paramtype>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::data_param</paramtype>
              </parameter>
              <description>
                <para>
                  Returns the current expression.
                </para>
              </description>
              <returns>
                <para>
                  <computeroutput>expr</computeroutput>
                </para>
              </returns>
              <throws>
                <simpara>Will not throw.</simpara>
              </throws>
            </method>
          </method-group>
        </struct>
      </struct>

      <struct name="_state">
        <inherit><classname>proto::transform</classname>&lt; _state &gt;</inherit>
        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns the current state unmodified. </purpose>
        <description>
          <para>
            Example:
            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
char ch = proto::_state()(i, 'a');
assert( ch == 'a' );</programlisting>
          </para>
        </description>
        <struct name="impl">
          <template>
            <template-type-parameter name="Expr"/>
            <template-type-parameter name="State"/>
            <template-type-parameter name="Data"/>
          </template>
          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
          <typedef name="result_type">
            <type>State</type>
          </typedef>
          <method-group name="public member functions">
            <method name="operator()" cv="const">
              <type>State</type>
              <parameter name="">
                <paramtype>typename impl::expr_param</paramtype>
              </parameter>
              <parameter name="state">
                <paramtype>typename impl::state_param</paramtype>
                <description>
                  <para>The current state. </para>
                </description>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::data_param</paramtype>
              </parameter>
              <description>
                <para>
                  Returns the current state.
                </para>
              </description>
              <returns>
                <para>
                  <computeroutput>state</computeroutput>
                </para>
              </returns>
              <throws>
                <simpara>Will not throw.</simpara>
              </throws>
            </method>
          </method-group>
        </struct>
      </struct>

      <struct name="_data">
        <inherit><classname>proto::transform</classname>&lt; _data &gt;</inherit>
        <purpose>
          A <conceptname>PrimitiveTransform</conceptname> that returns the current data unmodified.
          If the data (third) parameter is a transform environment, it returns the value associated
          with the <code><classname>proto::data_type</classname></code> key. Otherwise, it returns
          the data parameter unmodified.
        </purpose>
        <description>
          <para>
            If the data (third) parameter is a transform environment, it returns the value associated
            with the <code><classname>proto::data_type</classname></code> key. Otherwise, it returns
            the data parameter unmodified.
          </para>
          <para>
            <emphasis role="bold">Example:</emphasis>
            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
std::string str("hello");
std::string &amp; d1 = proto::_data()(i, 'a', str);
assert( &amp;str == &amp;d1 );

std::string &amp; d2 = proto::_data()(i, 'a', (<globalname>proto::data</globalname> = boost::ref(str)));
assert( &amp;str == &amp;d2 );</programlisting>
          </para>
        </description>
        <struct name="impl">
          <template>
            <template-type-parameter name="Expr"/>
            <template-type-parameter name="State"/>
            <template-type-parameter name="Data"/>
          </template>
          <inherit><type>
    mpl::if_c&lt;
      <classname>proto::is_env</classname>&lt;Data&gt;::value,
      <classname>proto::_env_var</classname>&lt;<classname>proto::data_type</classname>&gt;,
      <classname>proto::_env</classname>
    &gt;::type::template impl&lt;Expr, State, Data&gt;</type></inherit>
        </struct>
      </struct>

      <struct name="_child_c">
        <template>
          <template-nontype-parameter name="N">
            <type>int</type>
          </template-nontype-parameter>
        </template>
        <inherit><classname>proto::transform</classname>&lt; _child_c&lt;N&gt; &gt;</inherit>
        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns N-th child of the current expression. </purpose>
        <description>
          <para>
            Example:
            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
<classname>proto::terminal</classname>&lt;int&gt;::type &amp; j = proto::_child_c&lt;0&gt;()(-i);
assert( boost::addressof(i) == boost::addressof(j) );</programlisting>
          </para>
        </description>
        <struct name="impl">
          <template>
            <template-type-parameter name="Expr"/>
            <template-type-parameter name="State"/>
            <template-type-parameter name="Data"/>
          </template>
          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
          <typedef name="result_type">
            <type>typename <classname>proto::result_of::child_c</classname>&lt; Expr, N &gt;::type</type>
          </typedef>
          <method-group name="public member functions">
            <method name="operator()" cv="const">
              <type>typename <classname>proto::result_of::child_c</classname>&lt; Expr, N &gt;::type</type>
              <parameter name="expr">
                <paramtype>typename impl::expr_param</paramtype>
                <description>
                  <para>The current expression. </para>
                </description>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::state_param</paramtype>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::data_param</paramtype>
              </parameter>
              <description>
                <para>
                  Returns the N-th child of <computeroutput>expr</computeroutput>
                </para>
              </description>
              <requires>
                <para>
                  <computeroutput>Expr::proto_arity::value &gt; N</computeroutput>
                </para>
              </requires>
              <returns>
                <para>
                  <computeroutput><functionname>proto::child_c</functionname>&lt;N&gt;(expr)</computeroutput>
                </para>
              </returns>
              <throws>
                <simpara>Will not throw.</simpara>
              </throws>
            </method>
          </method-group>
        </struct>
      </struct>

      <struct name="_value">
        <inherit><classname>proto::transform</classname>&lt; _value &gt;</inherit>
        <purpose>A <conceptname>PrimitiveTransform</conceptname> that returns the value of the current terminal expression. </purpose>
        <description>
          <para>
            Example:
            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
int j = proto::_value()(i);
assert( 42 == j );</programlisting>
          </para>
        </description>
        <struct name="impl">
          <template>
            <template-type-parameter name="Expr"/>
            <template-type-parameter name="State"/>
            <template-type-parameter name="Data"/>
          </template>
          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
          <typedef name="result_type">
            <type>typename <classname>proto::result_of::value</classname>&lt; Expr &gt;::type</type>
          </typedef>
          <method-group name="public member functions">
            <method name="operator()" cv="const">
              <type>typename <classname>proto::result_of::value</classname>&lt; Expr &gt;::type</type>
              <parameter name="expr">
                <paramtype>typename impl::expr_param</paramtype>
                <description>
                  <para>The current expression. </para>
                </description>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::state_param</paramtype>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::data_param</paramtype>
              </parameter>
              <description>
                <para>
                  Returns the value of the specified terminal expression.
                </para>
              </description>
              <requires>
                <para>
                  <computeroutput>Expr::proto_arity::value == 0</computeroutput>.
                </para>
              </requires>
              <returns>
                <para>
                  <computeroutput><functionname>proto::value</functionname>(expr)</computeroutput>
                </para>
              </returns>
              <throws>
                <simpara>Will not throw.</simpara>
              </throws>
            </method>
          </method-group>
        </struct>
      </struct>

      <struct name="_void">
        <inherit><classname>proto::transform</classname>&lt; _void &gt;</inherit>
        <purpose>A <conceptname>PrimitiveTransform</conceptname> that does nothing and returns void. </purpose>
        <struct name="impl">
          <template>
            <template-type-parameter name="Expr"/>
            <template-type-parameter name="State"/>
            <template-type-parameter name="Data"/>
          </template>
          <inherit><classname>proto::transform_impl</classname>&lt; Expr, State, Data &gt;</inherit>
          <typedef name="result_type">
            <type>void</type>
          </typedef>
          <method-group name="public member functions">
            <method name="operator()" cv="const">
              <type>void</type>
              <parameter name="">
                <paramtype>typename impl::expr_param</paramtype>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::state_param</paramtype>
              </parameter>
              <parameter name="">
                <paramtype>typename impl::data_param</paramtype>
              </parameter>
              <description>
                <para>
                  Does nothing.
                </para>
              </description>
              <throws>
                <simpara>Will not throw.</simpara>
              </throws>
            </method>
          </method-group>
        </struct>
      </struct>

      <struct name="_byref">
        <inherit><classname>proto::callable</classname></inherit>
        <purpose>A unary callable <conceptname>PolymorphicFunctionObject</conceptname> that wraps its argument
          in a <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput>.</purpose>
        <description>
          <para>
            Example:
            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
boost::reference_wrapper&lt;<classname>proto::terminal</classname>&lt;int&gt;::type&gt; j
  = <classname>proto::when</classname>&lt;<classname>proto::_</classname>, proto::_byref(_)&gt;()(i);
assert( boost::addressof(i) == boost::addressof(j.get()) );</programlisting>
          </para>
        </description>
        <struct-specialization name="result">
          <template>
            <template-type-parameter name="This"/>
            <template-type-parameter name="T"/>
          </template>
          <specialization>
            <template-arg>This(T &amp;)</template-arg>
          </specialization>
          <typedef name="type">
            <type>boost::reference_wrapper&lt; T &gt; const</type>
          </typedef>
        </struct-specialization>
        <struct-specialization name="result">
          <template>
            <template-type-parameter name="This"/>
            <template-type-parameter name="T"/>
          </template>
          <specialization>
            <template-arg>This(T)</template-arg>
          </specialization>
          <typedef name="type">
            <type>boost::reference_wrapper&lt; T const  &gt; const</type>
          </typedef>
        </struct-specialization>
        <method-group name="public member functions">
          <method name="operator()" cv="const">
            <type>boost::reference_wrapper&lt; T &gt; const</type>
            <template>
              <template-type-parameter name="T"/>
            </template>
            <parameter name="t">
              <paramtype>T &amp;</paramtype>
              <description>
                <para>The object to wrap </para>
              </description>
            </parameter>
            <description>
              <para>
                Wrap the parameter <computeroutput>t</computeroutput> in a
                <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput>
              </para>
            </description>
            <returns>
              <para>
                <computeroutput>boost::ref(t)</computeroutput>
              </para>
            </returns>
            <throws>
              <simpara>Will not throw.</simpara>
            </throws>
          </method>
          <method name="operator()" cv="const">
            <type>boost::reference_wrapper&lt; T const &gt; const</type>
            <template>
              <template-type-parameter name="T"/>
            </template>
            <parameter name="t">
              <paramtype>T const &amp;</paramtype>
            </parameter>
            <description>
              <para>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </para>
            </description>
          </method>
        </method-group>
      </struct>

      <struct name="_byval">
        <inherit><classname>proto::callable</classname></inherit>
        <purpose>
          A unary callable <conceptname>PolymorphicFunctionObject</conceptname> that strips references and
          <computeroutput>boost::reference_wrapper&lt;&gt;</computeroutput> from its argument.
        </purpose>
        <description>
          <para>
            Example:
            <programlisting><classname>proto::terminal</classname>&lt;int&gt;::type i = {42};
int j = 67;
int k = <classname>proto::when</classname>&lt;<classname>proto::_</classname>, proto::_byval(<classname>proto::_state</classname>)&gt;()(i, boost::ref(j));
assert( 67 == k );</programlisting>
          </para>
        </description>
        <struct-specialization name="result">
          <template>
            <template-type-parameter name="This"/>
            <template-type-parameter name="T"/>
          </template>
          <specialization>
            <template-arg>This(boost::reference_wrapper&lt; T &gt;)</template-arg>
          </specialization>
          <inherit>result&lt;This(T)&gt;</inherit>
        </struct-specialization>
        <struct-specialization name="result">
          <template>
            <template-type-parameter name="This"/>
            <template-type-parameter name="T"/>
          </template>
          <specialization>
            <template-arg>This(T &amp;)</template-arg>
          </specialization>
          <inherit>result&lt;This(T)&gt;</inherit>
        </struct-specialization>
        <struct-specialization name="result">
          <template>
            <template-type-parameter name="This"/>
            <template-type-parameter name="T"/>
          </template>
          <specialization>
            <template-arg>This(T)</template-arg>
          </specialization>
          <typedef name="type">
            <type>T</type>
          </typedef>
        </struct-specialization>
        <method-group name="public member functions">
          <method name="operator()" cv="const">
            <type>T</type>
            <template>
              <template-type-parameter name="T"/>
            </template>
            <parameter name="t">
              <paramtype>T const &amp;</paramtype>
              <description>
                <para>The object to unref </para>
              </description>
            </parameter>
            <returns>
              <para>
                <computeroutput>t</computeroutput>
              </para>
            </returns>
            <throws>
              <simpara>Will not throw.</simpara>
            </throws>
          </method>
          <method name="operator()" cv="const">
            <type>T</type>
            <template>
              <template-type-parameter name="T"/>
            </template>
            <parameter name="t">
              <paramtype>boost::reference_wrapper&lt; T &gt; const &amp;</paramtype>
            </parameter>
            <description>
              <para>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. </para>
            </description>
          </method>
        </method-group>
      </struct>
    </namespace>
  </namespace>
</header>