10 Typemaps

• Introduction
  • Type conversion
  • Typemaps
  • Pattern matching
  • Reusing typemaps
  • What can be done with typemaps?
  • What can't be done with typemaps?
  • The rest of this chapter
• Typemap specifications
  • Defining a typemap
  • Typemap scope
  • Copying a typemap
  • Deleting a typemap
  • Placement of typemaps
• Pattern matching rules
  • Basic matching rules
  • Typedef reductions
  • Default typemaps
  • Mixed default typemaps
  • Multi-arguments typemaps
• Code generation rules
  • Scope
  • Declaring new local variables
  • Special variables
• Common typemap methods
  • "in" typemap
  • "typecheck" typemap
  • "out" typemap
  • "arginit" typemap
  • "default" typemap
  • "check" typemap
  • "argout" typemap
  • "freearg" typemap
  • "newfree" typemap
  • "memberin" typemap
  • "varin" typemap
  • "varout" typemap
  • "throws" typemap
• Some typemap examples
  • Typemaps for arrays
  • Implementing constraints with typemaps
• Multi-argument typemaps
• The run-time type checker
• Typemaps and overloading
• More about %apply and %clear
• Reducing wrapper code size
• Passing data between typemaps
• Where to go for more information?

10.1 Introduction

10.1.1 Type conversion

One of the most important problems in wrapper code generation is the conversion of datatypes between programming languages. Specifically, for every C/C++ declaration, SWIG must somehow generate wrapper code that allows values to be passed back and forth between languages. Since every programming language represents data differently, this is not a simple of matter of simply linking code together with the C linker. Instead, SWIG has to know something about how data is represented in each language and how it can be manipulated.

To illustrate, suppose you had a simple C function like this:

int factorial(int n);

long PyInt_AsLong(PyObject *obj);      /* Python --> C */
PyObject *PyInt_FromLong(long x);      /* C --> Python */

Inside the wrapper function, you might see these functions used like this:

PyObject *wrap_factorial(PyObject *self, PyObject *args) {
    int       arg1;
    int       result;
    PyObject *obj1;
    PyObject *resultobj;

    if (!PyArg_ParseTuple("O:factorial", &obj1)) return NULL;
    arg1 = PyInt_AsLong(obj1);
    result = factorial(arg1);
    resultobj = PyInt_FromLong(result);
    return resultobj;
}

Every target language supported by SWIG has functions that work in a similar manner. For example, in Perl, the following functions are used:

IV SvIV(SV *sv);                     /* Perl --> C */
void sv_setiv(SV *sv, IV val);       /* C --> Perl */

int Tcl_GetLongFromObj(Tcl_Interp *interp, Tcl_Obj *obj, long *value);
Tcl_Obj *Tcl_NewIntObj(long value);

10.1.2 Typemaps

/* Convert from Python --> C */
%typemap(in) int {
    $1 = PyInt_AsLong($input);
}

/* Convert from C --> Python */
%typemap(out) int {
    $result = PyInt_FromLong($1);
}

A short example might make this a little more clear. If you were wrapping a function like this:

int gcd(int x, int y);

PyObject *wrap_gcd(PyObject *self, PyObject *args) {
   int arg1;
   int arg2;
   int result;
   PyObject *obj1;
   PyObject *obj2;
   PyObject *resultobj;

   if (!PyArg_ParseTuple("OO:gcd", &obj1, &obj2)) return NULL;

   /* "in" typemap, argument 1 */   
   {
      arg1 = PyInt_AsLong(obj1);
   }

   /* "in" typemap, argument 2 */   
   {
      arg2 = PyInt_AsLong(obj2);
   }

   result = gcd(arg1,arg2);

   /* "out" typemap, return value */
   {
      resultobj = PyInt_FromLong(result);
   }

   return resultobj;
}

10.1.3 Pattern matching

/* Convert from Perl --> C */
%typemap(in) int {
   $1 = SvIV($input);
}

...
int factorial(int n);
int gcd(int x, int y);
int count(char *s, char *t, int max);

/* Convert from Ruby--> C */
%typemap(in) int {
   $1 = NUM2INT($input);
}
...
typedef int Integer;
namespace foo {
    typedef Integer Number;
};

int foo(int x);
int bar(Integer y);
int spam(foo::Number a, foo::Number b);

In addition to tracking typenames, typemaps may also be specialized to match against a specific argument name. For example, you could write a typemap like this:

%typemap(in) double nonnegative {
   $1 = PyFloat_AsDouble($input);
   if ($1 < 0) {
        PyErr_SetString(PyExc_ValueError,"argument must be nonnegative.");
        return NULL;
   }
}

...
double sin(double x);
double cos(double x);
double sqrt(double nonnegative);

typedef double Real;
double log(Real nonnegative);
...

%typemap(in) (char *str, int len) {
    $1 = PyString_AsString($input);   /* char *str */
    $2 = PyString_Size($input);       /* int len   */
}
...
int count(char *str, int len, char c);

10.1.4 Reusing typemaps

%typemap(in) Integer = int;   
%typemap(in) (char *buffer, int size) = (char *str, int len);

%typemap(in) int {
   /* Convert an integer argument */
   ...
}
%typemap(out) int {
   /* Return an integer value */
   ...
}

/* Apply all of the integer typemaps to size_t */
%apply int { size_t };    

It should be noted that it is not necessary to copy typemaps for types that are related by typedef. For example, if you have this,

typedef int size_t;

10.1.5 What can be done with typemaps?

Argument handling

int foo(int x, double y, char *s);

• Input argument conversion ("in" typemap).
• Input argument type checking ("typecheck" typemap).
• Output argument handling ("argout" typemap).
• Input argument value checking ("check" typemap).
• Input argument initialization ("arginit" typemap).
• Default arguments ("default" typemap).
• Input argument resource management ("freearg" typemap).

Return value handling

int foo(int x, double y, char *s);

• Function return value conversion ("out" typemap).
• Return value resource management ("ret" typemap).
• Resource management for newly allocated objects ("newfree" typemap).

Exception handling

int foo(int x, double y, char *s) throw(MemoryError, IndexError);

• Handling of C++ exception specifiers. ("throw" typemap).

Global variables

int foo;

• Assignment of a global variable. ("varin" typemap).
• Reading a global variable. ("varout" typemap).

Member variables

struct Foo {
    int x[20];
};

• Assignment of data to a class/structure member. ("memberin" typemap).

Constant creation

#define FOO 3
%constant int BAR = 42;
enum { ALE, LAGER, STOUT };

• Creation of constant values. ("consttab" or "constcode" typemap).

10.1.6 What can't be done with typemaps?

Foo *make_Foo();

Typemaps also can't be used to rearrange or transform the order of arguments. For example, if you had a function like this:

void foo(int, char *);

foo("hello",3)          # Reversed arguments

%rename(foo) wrap_foo;
%inline %{
void wrap_foo(char *s, int x) {
   foo(x,s);
}
%}

10.1.7 The rest of this chapter

Since typemaps are strongly tied to the underlying C++ type system, subsequent sections assume that you are reasonably familiar with the basic details of values, pointers, references, arrays, type qualifiers (e.g., const), structures, namespaces, templates, and memory management in C/C++. If not, you would be well-advised to consult a copy of "The C Programming Language" by Kernighan and Ritchie or "The C++ Programming Language" by Stroustrup before going any further.

10.2 Typemap specifications

10.2.1 Defining a typemap

%typemap(method [, modifiers]) typelist code ;

modifiers is an optional comma separated list of name="value" values. These are sometimes to attach extra information to a typemap and is often target-language dependent.

typelist is a list of the C++ type patterns that the typemap will match. The general form of this list is as follows:

typelist    :  typepattern [, typepattern, typepattern, ... ] ;

typepattern :  type [ (parms) ]
            |  type name [ (parms) ]
            |  ( typelist ) [ (parms) ]

code specifies the C code used in the typemap. It can take any one of the following forms:

code       : { ... }
           | " ... "
           | %{ ... %}

/* Simple typemap declarations */
%typemap(in) int {
   $1 = PyInt_AsLong($input);
}
%typemap(in) int "$1 = PyInt_AsLong($input);";
%typemap(in) int %{ 
   $1 = PyInt_AsLong($input);
%}

/* Typemap with extra argument name */
%typemap(in) int nonnegative {
   ...
}

/* Multiple types in one typemap */
%typemap(in) int, short, long { 
   $1 = SvIV($input);
}

/* Typemap with modifiers */
%typemap(in,doc="integer") int "$1 = gh_scm2int($input);";

/* Typemap applied to patterns of multiple arguments */
%typemap(in) (char *str, int len),
             (char *buffer, int size)
{
   $1 = PyString_AsString($input);
   $2 = PyString_Size($input);
}

/* Typemap with extra pattern parameters */
%typemap(in, numinputs=0) int *output (int temp),
                          long *output (long temp)
{
   $1 = &temp;
}

10.2.2 Typemap scope

// typemap1
%typemap(in) int {
...
}

int fact(int);                    // typemap1
int gcd(int x, int y);            // typemap1

// typemap2
%typemap(in) int {
...
}

int isprime(int);                 // typemap2

class Foo {
   ...
};

%typemap(in) int {
 ...
}

%extend Foo {
   int blah(int x);    // typemap has no effect.  Declaration is attached to Foo which 
                       // appears before the %typemap declaration.
};

10.2.3 Copying a typemap

%typemap(in) Integer = int;

%typemap(in) Integer, Number, int32_t = int;

%typemap(in)     int { ... }
%typemap(out)    int { ... }
%typemap(varin)  int { ... }
%typemap(varout) int { ... }

%apply int { Integer };            // Copy all int typemaps to Integer
%apply int { Integer, Number };    // Copy all int typemaps to both Integer and Number

%apply int *output { Integer *output };                    // Typemap with name
%apply (char *buf, int len) { (char *buffer, int size) };  // Multiple arguments

10.2.4 Deleting a typemap

%typemap(in) int;               // Clears typemap for int
%typemap(in) int, long, short;  // Clears typemap for int, long, short
%typemap(in) int *output;       

%clear int;                     // Removes all types for int
%clear int *output, long *output;

10.2.5 Placement of typemaps

%typemap(in) int {
   ...
}

namespace std {
    class string;
    %typemap(in) string {
        ...
    }
}

class Bar {
public:
    typedef const int & const_reference;
    %typemap(out) const_reference {
         ...
    }
};

namespace std {
    class string;
    %typemap(in) string {
       ...
    }
}

namespace std {
    class string;
    %typemap(in) string {          /* std::string */
       ...
    }
}

namespace Foo {
    class string;
    %typemap(in) string {          /* Foo::string */
       ...
    }
}

It should be noted that for scoping to work, SWIG has to know that string is a typename defined within a particular namespace. In this example, this is done using the class declaration class string.

10.3 Pattern matching rules

10.3.1 Basic matching rules