Sometimes it is necessary to control how luabind passes arguments and return value, to do this we have policies. All policies use an index to associate them with an argument in the function signature. These indices are result and _N (where N >= 1). When dealing with member functions _1 refers to the this pointer.
Policies currently implemented
Used to transfer ownership across language boundaries.
#include <luabind/adopt_policy.hpp>
adopt(index)
| Parameter | Purpose |
|---|---|
| index | The index which should transfer ownership, _N or result |
The dependency policy is used to create life-time dependencies between values. This is needed for example when returning internal references to some class.
#include <luabind/dependency_policy.hpp>
dependency(nurse_index, patient_index)
| Parameter | Purpose |
|---|---|
| nurse_index | The index which will keep the patient alive. |
| patient_index | The index which will be kept alive. |
struct X
{
B member;
B& get() { return member; }
};
module(L)
[
class_<X>("X")
.def("get", &X::get, dependency(result, _1))
];
This policy makes it possible to wrap functions that take non-const references or pointer to non-const as it’s parameters with the intention to write return values to them. Since it’s impossible to pass references to primitive types in lua, this policy will add another return value with the value after the call. If the function already has one return value, one instance of this policy will add another return value (read about multiple return values in the lua manual).
#include <luabind/out_value_policy.hpp>
out_value(index, policies = none)
| Parameter | Purpose |
|---|---|
| index | The index of the parameter to be used as an out parameter. |
| policies | The policies used internally to convert the out parameter to/from Lua. _1 means to C++, _2 means from C++. |
void f1(float& val) { val = val + 10.f; }
void f2(float* val) { *val = *val + 10.f; }
module(L)
[
def("f", &f, out_value(_1))
];
Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
> print(f1(10))
20
> print(f2(10))
20
This works exactly like out_value, except that it will pass a default constructed object instead of converting an argument from Lua. This means that the parameter will be removed from the lua signature.
#include <luabind/out_value_policy.hpp>
pure_out_value(index, policies = none)
| Parameter | Purpose |
|---|---|
| index | The index of the parameter to be used as an out parameter. |
| policies | The policies used internally to convert the out parameter to Lua. _1 is used as the internal index. |
Note that no values are passed to the calls to f1 and f2.
void f1(float& val) { val = 10.f; }
void f2(float\* val) { \*val = 10.f; }
module(L)
[
def("f", &f, pure_out_value(_1))
];
Lua 5.0 Copyright (C) 1994-2003 Tecgraf, PUC-Rio
> print(f1())
10
> print(f2())
10
It is very common to return references to arguments or the this-pointer to allow for chaining in C++.
struct A
{
float val;
A& set(float v)
{
val = v;
return *this;
}
};
When luabind generates code for this, it will create a new object for the return-value, pointing to the self-object. This isn’t a problem, but could be a bit inefficient. When using the return_reference_to-policy we have the ability to tell luabind that the return-value is already on the lua stack.
#include <luabind/return_reference_to_policy.hpp>
return_reference_to(index)
| Parameter | Purpose |
|---|---|
| index | The argument index to return a reference to, any argument but not result. |
struct A
{
float val;
A& set(float v)
{
val = v;
return *this;
}
};
module(L)
[
class_<A>("A")
.def(constructor<>())
.def("set", &A::set, return_reference_to(_1))
];
Warning
This policy ignores all type information and should be used only it situations where the parameter type is a perfect match to the return-type (such as in the example).
This will make a copy of the parameter. This is the default behavior when passing parameters by-value. Note that this can only be used when passing from C++ to Lua. This policy requires that the parameter type has an accessible copy constructor.
#include <luabind/copy_policy.hpp>
copy(index)
| Parameter | Purpose |
|---|---|
| index | The index to copy. result when used while wrapping C++ functions. _N when passing arguments to Lua. |
X* get()
{
static X instance;
return &instance;
}
module(L)
[
def("create", &create, copy(result))
];
This is a very simple policy which makes it possible to throw away the value returned by a C++ function, instead of converting it to Lua.
#include <luabind/discard_result_policy.hpp>
discard_result
struct X
{
X& set(T n)
{
...
return *this;
}
};
module(L)
[
class_<X>("X")
.def("set", &simple::set, discard_result)
];
This policy converts an STL container to a generator function that can be used in lua to iterate over the container. It works on any container that defines begin() and end() member functions (they have to return iterators).
#include <luabind/iterator_policy.hpp>
return_stl_iterator
struct X
{
std::vector<std::string> names;
};
module(L)
[
class_<A>("A")
.def_readwrite("names", &X::names, return_stl_iterator)
];
> a = A()
> for name in a.names do
> print(name)
> end
Note
raw() has been deprecated. lua_State* parameters are automatically handled by luabind.
This converter policy will pass through the lua_State* unmodified. This can be useful for example when binding functions that need to return a luabind::object. The parameter will be removed from the function signature, decreasing the function arity by one.
#include <luabind/raw_policy.hpp>
raw(index)
| Parameter | Purpose |
|---|---|
| index | The index of the lua_State* parameter. |
void greet(lua_State* L)
{
lua_pushstring(L, "hello");
}
module(L)
[
def("greet", &greet, raw(_1))
];
> print(greet())
hello