UT/UT_LHSTuple.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * COMMENTS:
 *      This file defines a number of functions named UTlhsTuple() (tuples
 *      that are valid left hand sides in assignments).  These functions
 *      are inspired by python, where it's very easy to return multiple values
 *      from a function:
 *
 *          def foo():
 *              return ([0, 1, 2], 6)
 *
 *          (a, b) = foo()
 *          ...do something with a and b...
 *
 *      The C++ equivalent works with boost tuples, and looks like:
 *
 *          static boost::tuple<UT_Vector3, int> foo()
 *          { return boost::make_tuple(UT_Vector3(0, 1, 2), 6); }
 *
 *          UT_Vector3 a;
 *          int b;
 *          UTlhsTuple(a, b) = foo();
 *          ...do something with a and b...
 *
 *      One handy use of these functions is when you want to pass multiple
 *      values into a callback function that takes a void *.  Instead of
 *      creating a struct to hold the values, pass in a pointer to a
 *      boost::tuple:
 *          void iterateOverSomething(
 *              void (*callback)(void *), void *callback_data));
 *
 *          static void my_callback(void *data)
 *          {
 *              UT_Vector3 a;
 *              int b;
 *              UTlhsTuple(a, b) = *(boost::tuple<UT_Vector3, int>*)data;
 *              ...do something with a and b...
 *          }
 *
 *          boost::tuple<UT_Vector3, int> data(UT_Vector3(1,2,3), 4);
 *          iterateOverSomething(my_callback, &data);
 */

#ifndef BOOST_PP_IS_ITERATING
#ifndef __UT_LHSTuple_h__
#define __UT_LHSTuple_h__

#include <boost/preprocessor/repetition.hpp>
#include <boost/preprocessor/iteration/iterate.hpp>
#include <boost/preprocessor/punctuation/comma_if.hpp>
#include <boost/preprocessor/arithmetic/sub.hpp>
#include <boost/preprocessor/comparison/less.hpp>
#include <boost/preprocessor/repetition/enum_params.hpp>
#include <boost/preprocessor/repetition/enum_binary_params.hpp>

#include <boost/tuple/tuple.hpp>

// Including BOOST_PP_ITERATE() will make this file get included again
// over and over, with BOOST_PP_IS_ITERATING set and BOOST_PP_ITERATION()
// set to a different value each time.
//
// We need to use different includes depending on whether we're being
// included from UT or not.
#define BOOST_PP_ITERATION_LIMITS (2, 10)
#ifdef EXPORT_UT
#define BOOST_PP_FILENAME_1 "UT_LHSTuple.h"
#else
#define BOOST_PP_FILENAME_1 <UT/UT_LHSTuple.h>
#endif
#include BOOST_PP_ITERATE()

#endif // __UT_LHSTuple_h__


#else // BOOST_PP_IS_ITERATING


#define n BOOST_PP_ITERATION()

// This macro creates output of the form:
//     T1&, T2&, T3&
#define TYPE_REF_LIST(z, num, p) T ## num & \
        BOOST_PP_COMMA_IF(BOOST_PP_LESS(num, BOOST_PP_SUB(n, 1)))

// This macro creates output of the form:
//     boost::ref(parm1), boost::ref(parm2), boost::ref(parm3)
// boost::ref ensures that make_tuple creates a tuple of references.
#define PARAMS_AS_REF_LIST(z, num, p) boost::ref(parm ## num) \
        BOOST_PP_COMMA_IF(BOOST_PP_LESS(num, BOOST_PP_SUB(n, 1)))

// Overload a function named UTlhsTuple() that takes different numbers of
// arguments of any type and returns a boost::tuple of references to the
// parameters passed it.  You can then assign another tuple to the return
// value of this function, causing it to assign to each of the variables
// that were passed into the function.
template <BOOST_PP_ENUM_PARAMS(n, typename T)>
boost::tuple<BOOST_PP_REPEAT(n, TYPE_REF_LIST, _)>
UTlhsTuple(BOOST_PP_ENUM_BINARY_PARAMS(n, T, &parm))
{
    return boost::make_tuple(BOOST_PP_REPEAT(n, PARAMS_AS_REF_LIST, _));
}

#undef TYPE_REF_LIST
#undef PARAMS_AS_REF_LIST
#undef n

#endif // BOOST_PP_IS_ITERATING

---