###

# Boost.Python

## Header <boost/python/return_arg.hpp>

## Contents

Introduction
Classes
  Class Template `return_arg`
    Class Template `return_arg` synopsis
    Class `return_arg` static functions
  Class Template `return_self`
Example

## Introduction

`return_arg` and `return_self` instantiations are models of CallPolicies which return the specified argument parameter (usually `*this`) of a wrapped (member) function.

## Classes

### Class template `return_arg`

`return_arg` template parameters
Parameter | Requirements | Description | Default
--- | --- | --- | ---
`arg_pos` | A positive compile-time constant of type `std::size_t`. | the position of the argument to be returned. | 1
`Base` | A model of CallPolicies | Used for policy composition. Any `result_converter` it supplies will be overridden by `return_arg`, but its `precall` and `postcall` policies are composed as described here CallPolicies. | `default_call_policies`

#### Class template `return_arg` synopsis

    namespace boost { namespace python
    {
       template <size_t arg_pos=1, class Base = default_call_policies>
       struct return_arg : Base
       {
          static PyObject* postcall(PyObject*, PyObject* result);
          struct result_converter{ template <class T> struct apply; };
       };
    }}

#### Class `return_arg` static functions

    PyObject* postcall(PyObject* args, PyObject* result);

Requires: `PyTuple_Check(args) != 0` and `PyTuple_Size(args) != 0`
Returns: `PyTuple_GetItem(args,arg_pos-1)`

### Class template `return_self`

#### Class template `return_self` synopsis:

    namespace boost { namespace python
    {
       template <class Base = default_call_policies>
       struct return_self
         : return_arg<1,Base>
       {};
    }}

## Example

### C++ module definition

    #include <boost/python/module.hpp>
    #include <boost/python/class.hpp>
    #include <boost/python/return_arg.hpp>

    struct Widget
    {
       Widget() :sensitive_(true){}
       bool get_sensitive() const { return sensitive_; }
       void set_sensitive(bool s) { this->sensitive_ = s; }
     private:
       bool sensitive_;
    };

    struct Label : Widget
    {
       Label() {}

       std::string  get_label() const { return label_; }
       void set_label(const std::string &l){ label_ = l; }

     private:
       std::string label_;
    };

    using namespace boost::python;
    BOOST_PYTHON_MODULE(return_self_ext)
    {
       class_<widget>("Widget")
          .def("sensitive", &Widget::get_sensitive)
          .def("sensitive", &Widget::set_sensitive, return_self<>())
          ;

       class_<Label, bases<Widget> >("Label")
          .def("label", &Label::get_label)
          .def("label", &Label::set_label, return_self<>())
          ;
    }

### Python code

    >>> from return_self_ext import *
    >>> l1 = Label().label("foo").sensitive(false)
    >>> l2 = Label().sensitive(false).label("foo")

Revised 19 July, 2003

© Copyright Dave Abrahams and Nikolay Mladenov 2003.