swig Introduction to Typemaps
Introduction
Typemaps are the very heart of what SWIG does. When you want to pass data between languages the behaviours for doing so depend upon the type that SWIG sees. The power of typemaps is that the chunks of code are applied many times.
SWIG itself includes many useful typemaps in the core library it is supplied with, e.g. for primitive types, C++ standard library containers, boost etc. so often you won't even need to write any typemaps to expose your code, however that list is by no means complete.
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) |
