========
as_tuple
========

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

Class ``as_tuple`` is a model of `ResultConverterGenerator`_  which
can be used to wrap C++ functions returning a pointer to arrays with fixed size.
The policy will construct a Python tuple from the array and handle the array memory.

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

.. code-block:: c++

   struct vector3{
       ...

       float* clone_raw_data() const{
           float* values = new float[3];
           //copy values
           return values;
       }

       const flow* get_raw_data() const{
           return m_values;
       }

   private:
       float m_values[3];
   };

  namespace bpl = boost::python;
  namespace pypp_cp = pyplusplus::call_policies;
  BOOST_PYTHON_MODULE(my_module){
    bpl::class_< vector3 >( "vector3" )
        .def( "clone_raw_data"
              , &::vector3::clone_raw_data
              , bpl::return_value_policy< pypp_cp::arrays::as_tuple< 3, pypp_cp::memory_managers::delete_ > >() )
        .def( "get_raw_data"
              , &::vector3::get_raw_data
              , bpl::return_value_policy< pypp_cp::arrays::as_tuple< 3, pypp_cp::memory_managers::none > >() ) );
  }

------------------
``as_tuple`` class
------------------

``as_tuple`` is a template class that takes few arguments:

1. the array size - compile time constant

2. memory management policy - a class, which will manage the return value.
   There are two built-in memory managers:

   * delete\_ - the array will be deleted after it was copied to tuple, using
     ``operator delete[]``

   * none - do nothing

The :doc:`Py++ <../../../pyplusplus>` code is slightly different from the C++ one, but it is definitely shorter:

.. code-block:: python

  from pyplusplus import module_builder
  from pyplusplus.module_builder import call_policies

  mb = module_builder.module_builder_t( ... )
  mb.member_function( 'clone_raw_data' ).call_policies \
      = call_policies.convert_array_to_tuple( 3, call_policies.memory_managers.delete_ )
  mb.member_function( 'get_raw_data' ).call_policies \
      = call_policies.convert_array_to_tuple( 3, call_policies.memory_managers.none )


.. _`ResultConverterGenerator` : http://boost.org/libs/python/doc/v2/ResultConverter.html#ResultConverterGenerator-concept
.. _`CallPolicies` : http://www.boost.org/libs/python/doc/v2/CallPolicies.html#CallPolicies-concept

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

