======================
``inout`` transformer
======================

.. contents:: Table of contents

----------
Definition
----------

``inout`` transformer is a combination of `input`_ and `output`_ transformers.
It removes a "reference" type from the function argument and then adds the
"returned", by the original function, value to the return statement of the
function-wrapper.

``inout`` transformer takes as argument name or index of the original function
argument. The argument should have "reference" type. Support for "pointer" type
will be added pretty soon.

.. _`input` : input.html
.. _`output` : output.html

-------
Example
-------

.. code-block:: C++

  #include <string>

  inline void hello_world( std::string& hw ){
      hw = "hello world!";
  }

Lets say that you need to expose ``hello_world`` function. As you know
``std::string`` is mapped to `Python`_ string, which is immutable type, so you
have to create small wrapper for the function. The following `Py++`_ code does it for you:

  .. code-block:: Python

     from pyplusplus import module_builder
     from pyplusplus import function_transformers as FT

     mb = module_builder.module_builder_t( ... )
     hw = mb.mem_fun( 'hello_world' )
     hw.add_transformation( FT.inout(0) )

What you see below is the relevant pieces of generated code:

  .. code-block:: C++

     namespace bp = boost::python;

     static boost::python::object hello_world_a3478182294a057b61508c30b1361318( ::std::string hw ){
         ::hello_world(hw);
         return bp::object( hw );
     }

     BOOST_PYTHON_MODULE(...){
         ...
         bp::def( "hello_world", &hello_world_a3478182294a057b61508c30b1361318 );
     }

.. _`Py++` : ./../../../pyplusplus.html
.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
.. _`Python`: http://www.python.org
.. _`GCC-XML`: http://www.gccxml.org

