Introduction to Typemaps
Basic typemap - Python
Given the following custom Boolean type we want to wrap:
typedef char MYBOOL;
#define TRUE 1
#define FALSE 0
A simple approach might be to write the following typemaps in our SWIG interface:
%typemap(in) MYBOOL %{
// $input is what we got passed from Python for this function argument
$1 = PyObject_IsTrue($input);
// $1 is what will be used for the C or C++ call and we are responsible for setting it
%}
%typemap(out) MYBOOL %{
// $1 is what we got from our C or C++ call
$result = PyBool_FromLong($1);
// $result is what gets given back to Python and we are responsible for setting it
%}
With these typemaps, SWIG will insert our code into the generated wrapper every time it sees a MYBOOL passed into or out of a function call.
Syntax:
- %typemap(NAME) TYPENAME %{ CODE %}
- %typemap(NAME,OPTION=VALUE) TYPENAME %{ CODE %}
- %typemap(NAME) TYPENAME VARIABLENAME %{ CODE %}
- %typemap(NAME) TYPENAME (LOCALVARTYPE LOCALVARNAME) %{ CODE %}
Parameters:
| Parameter | Details |
|---|---|
| NAME | The name of the typemap defines its role in generating a module. in and out are common and used for input (to C++ or C function calls from Python/Java etc.) and output (i.e. return values from C or C++ to Pyton/Java) |
| TYPENAME | Each typemap gets applied to one or more matching types. These need to be listed here. Type qualifiers (e.g. const) matters. |
| CODE | Every typemap needs to convert between the C or C++ type and the corresponding type in the wrapped language. You will need to write code to do that in your custom typemaps, typically making use of special variables that get substituted in. E.g. $input inside an in typemap represents the value from Python/Java, $result in an out typemap is the thing being returned to Python/Java. $1 in both in/out typemaps represents the C or C++ variable of the type used to match the typemap. So for in typemaps you would assign to $1 and for out you would read from it. (See multi-argument typemaps for more details on why it is a number) |
| VARIABLENAME | Typemaps are matched from most specific to least specific in general. You can define a typemap that will only match function arguments with specific names by using this optional form. (See typemap matching for more details) |
| (LOCALVARTYPE LOCALVARNAME) | Sometimes, particuarly for in typemaps it's useful to be able to declare extra local variables to hold objects around a call. This optional syntax allows us do do that. By using this syntax instead of writing it in CODE the scope is altered, but more importantly the variable can be automatically renamed by SWIG to avoid clashes if a function has two arguments using the same typemap. |
| OPTION=VALUE | The behaviour of some typemaps can be influenced by setting extra options using this syntax. For example a in typemap can be made to take no input from the target language by setting numinputs=0, in which case the typemap is expected to fill the input implicitly. (A common case for this might be to set something to NULL, or fill it from a global value) |
Contributors
Topic Id: 9289
Example Ids: 28771
This site is not affiliated with any of the contributors.