6 Pointers, Constraints, and Typemaps

• Introduction
• The SWIG Pointer Library
• Introduction to typemaps
• Managing input and output parameters
• Applying constraints to input values
• Writing new typemaps
• Common typemap methods
• Writing typemap code
• Typemaps for handling arrays
• Typemaps and the SWIG Library
• Implementing constraints with typemaps
• Typemap examples
• How to break everything with a typemap
• Typemaps and the future

Introduction

The SWIG Pointer Library

%include pointer.i 				// Grab the SWIG pointer library

swig -perl5 -lpointer.i interface.i 

Pointer Library Functions

Creates a new object and returns a pointer to it. type is a string containing the C datatype and may be one of "int","short","long","float","double","char","char *", or "void". value is the optional initial value to be assigned to the object. nitems is an optional parameter containing the number of objects to create. By default it is 1, but specifying another value allows you to create an array of values. This function is really just a wrapper around the C malloc() function.

ptrfree(ptr)

Destroys an object created by ptrcreate. It is generally unsafe to use this function on objects not created by ptrcreate. Calls the C free() function.

ptrvalue(ptr,?index?,?type?)

This dereferences a pointer and returns the value that it is pointing to. index is an optional parameter that allows array access by returning the value of ptr[index]. type is an optional parameter that explicitly specifies the datatype. Since SWIG pointers are encoded with type information, the type is usually unnecessary. The type parameter provides somewhat better performance and allows you to dereference a pointer of different type however.

Sets the value of the object a pointer is pointing to. value is the new value of the object. index is an optional parameter allowing array access by setting ptr[index] = value. type is an optional parameter that explicitly specifies the datatype as described above.

Casts a pointer to a new datatype and returns the new value. newtype is a string containing the new datatype and may either be the "mangled" version used by SWIG (such as "_Vector_p") or the C version (such as "Vector *"). This function works with any kind of pointer value. In additional to pointers, ptr may also hold an integer value in which case the integer is turned into a pointer of given type.

Adds an offset to a pointer and returns a new pointer. offset is specified as the number of objects except for unknown complex datatypes in which case it is the number of bytes. For example, is ptr is a "double *", ptradd(ptr,1) will return the next double. On the other hand, if if ptr is "Vector *", then ptradd(ptr,1) will update the pointer by 1 byte.

This performs a "runtime typedef" and makes SWIG recognize pointers of type1 and type2 as equivalent. type1 and type2 are specified as strings. Not generally needed, but sometimes useful.

A simple example

void add(double a, double b, double *result) {
	*result = a + b;
}

%module example
%include pointer.i

extern void add(double a, double b, double *result);

# Tcl 
set result [ptrcreate double]          ;# Create a double
add 4.5 3 $result                      ;# Call our C function
puts [ptrvalue $result]                ;# Print out the result
ptrfree $result                        ;# Destroy the double

# Perl5
use example;
package example;                        # Functions are in example package
$result = ptrcreate("double");          # Create a double
add(4.5,3,$result);                     # Call C function
print ptrvalue($result),"\n";           # Print the result
ptrfree($result);                       # Destroy the double

# Python
import example
result = example.ptrcreate("double")    # Create a double
example.add(4.5,3,result)               # Call C function
print example.ptrvalue(result)          # Print the result
example.ptrfree(result)                 # Destroy the double

Creating arrays

void addv(double a[], double b[], double c[], int nitems) {
	int i;
	for (i = 0; i < nitems; i++) {
		c[i] = a[i]+b[i];
	}
}

# Python function to turn a list into an "array"
def build_array(l):
	nitems = len(l)
	a = ptrcreate("double",0,nitems)
	i = 0
	for item in l:
		ptrset(a,item,i)
		i = i + 1
	return a

# Python function to turn an array into list
def build_list(a,nitems):
	l = []
	for i in range(0,nitems):
		l.append(ptrvalue(a,i))
	return l

# Now use our functions
a = listtoarray([0.0,-2.0,3.0,9.0])
b = build_array([-2.0,3.5,10.0,22.0])
c = ptrcreate("double",0,4)            # For return result
add(a,b,c,4)                           # Call our C function
result = build_list(c)                 # Build a python list from the result
print result
ptrfree(a)
ptrfree(b)
ptrfree(c)

Packing a data structure

struct Point {
	double x,y;
	int color;
};

You could write a Tcl function to set the fields of the structure as follows :

proc set_point { ptr x y c } {
	set p [ptrcast $ptr "double *"]       ;# Make a double *
	ptrset $p $x                          ;# Set x component
	set p [ptradd $p 1]                   ;# Update pointer
	ptrset $p $y                          ;# Set y component
	set p [ptrcast [ptradd $p 1] "int *"] ;# Update pointer and cast
	ptrset $p $c                          ;# Set color component
}

This function could be used even if you didn't tell SWIG anything about the "Point" structure above.

Introduction to typemaps

The idea (in a nutshell)

void add(double a, double b, double *result) {
	*result = a + b;
}

It is clear to us that the result of the function is being returned in the result parameter. Unfortunately, SWIG isn't this smart--after all "result" is just like any other pointer. However, with a typemap, we can make SWIG recognize "double *result" as a special datatype and change the handling to do exactly what we want.

So, despite being a common topic of discussion on the SWIG mailing list, a typemap is really just a special processing rule that is applied to a particular datatype. Each typemap relies on two essential attributes--a datatype and a name (which is optional). When trying to match parameters, SWIG looks at both attributes. Thus, special processing applied to a parameter of "double *result" will not be applied to "double *input". On the other hand, special processing defined for a datatype of "double *" could be applied to both (since it is more general).

Using some typemaps

// Simple example using typemaps
%module example
%include typemaps.i 					// Grab the standard typemap library

%apply double *OUTPUT { double *result };
extern void add(double a, double b, double *result);

While it may sound complicated, when you compile the module and use it, you get a function that works as follows :

# Perl code to call our add function

$a = add(3,4); 		
print $a,"\n";
7

Managing input and output parameters

Input Methods

int *INPUT		
short *INPUT
long *INPUT
unsigned int *INPUT
unsigned short *INPUT
unsigned long *INPUT
double *INPUT
float *INPUT

Suppose you had a C function like this :

double add(double *a, double *b) {
	return *a+*b;
}

%module example
%include typemaps.i
...
extern double add(double *INPUT, double *INPUT);

% set result [add 3 4]
% puts $result
7

Output Methods

int *OUTPUT
short *OUTPUT
long *OUTPUT
unsigned int *OUTPUT
unsigned short *OUTPUT
unsigned long *OUTPUT
double *OUTPUT
float *OUTPUT

void add(double a, double b, double *c) {
	*c = a+b;
}

A SWIG interface file might look like this :

%module example
%include typemaps.i
...
extern void add(double a, double b, double *OUTPUT);

// Returns a status code and double
int get_double(char *str, double *result);

int get_double(char *str, double *OUTPUT);

>>> get_double("3.1415926")					# Returns both a status and value
[0, 3.1415926] 
>>>

Input/Output Methods

int *BOTH
short *BOTH
long *BOTH
unsigned int *BOTH
unsigned short *BOTH
unsigned long *BOTH
double *BOTH
float *BOTH

void negate(double *x) {
	*x = -(*x);
}

%module example
%include typemaps.i
...
extern void negate(double *BOTH);

$a = negate(3); 				# a = -3 after calling this

Using different names

// Make double *result an output value
%apply double *OUTPUT { double *result };

// Make Int32 *in an input value
%apply int *INPUT { Int32 *in };

// Make long *x both
%apply long *BOTH {long *x};

%clear double *result;
%clear Int32 *in, long *x;

Applying constraints to input values

Simple constraint example

// Interface file with constraints
%module example
%include constraints.i

double exp(double x);
double log(double POSITIVE);         // Allow only positive values
double sqrt(double NONNEGATIVE);     // Non-negative values only
double inv(double NONZERO);          // Non-zero values

void free(void *NONNULL);            // Non-NULL pointers only

Constraint methods

POSITIVE                     Any number > 0 (not zero)
NEGATIVE                     Any number < 0 (not zero)
NONNEGATIVE                  Any number >= 0
NONPOSITIVE                  Any number <= 0
NONZERO                      Nonzero number
NONNULL                      Non-NULL pointer (pointers only).

Applying constraints to new datatypes

// Apply a constraint to a Real variable
%apply Number POSITIVE { Real in };

// Apply a constraint to a pointer type
%apply Pointer NONNULL { Vector * };

%clear Real in;
%clear Vector *;

Writing new typemaps

Before diving in, first ask yourself do I really need to change SWIG's default behavior? The basic pointer model works pretty well most of the time and I encourage you to use it--after all, I wanted SWIG to be easy enough to use so that you didn't need to worry about low level details. If, after contemplating this for awhile, you've decided that you really want to change something, a word of caution is in order. Writing a typemap from scratch usually requires a detailed knowledge of the internal workings of a particular scripting language. It is also quite easy to break all of the output code generated by SWIG if you don't know what you're doing. On the plus side, once a typemap has been written it can be reused over and over again by putting it in the SWIG library (as has already been demonstrated). This section describes the basics of typemaps. Language specific information (which can be quite technical) is contained in the later chapters.

Motivations for using typemaps

void glLightfv(GLenum light, Glenum pname, GLfloat parms[4]);

Managing special data-types with helper functions

%inline %{
/* Create a new GLfloat [4] object */
GLfloat *newfv4(double x, double y, double z, double w) {
	GLfloat *f = (GLfloat *) malloc(4*sizeof(GLfloat));
	f[0] = x;
	f[1] = y;
	f[2] = z;
	f[3] = w;
	return f;
}

/* Destroy a GLfloat [4] object */
void delete_fv4(GLfloat *d) {
	free(d);
}
%}

When wrapped, our helper functions will show up the interface and can be used as follows :

% set light [newfv4 0.0 0.0 0.0 1.0]        # Creates a GLfloat *
% glLightfv GL_LIGHT0 GL_AMBIENT $light     # Pass it to the function
...
% delete_fv4 $light                         # Destroy it (When done) 

While not the most elegant approach, helper functions provide a simple mechanism for working with more complex datatypes. In most cases, they can be written without diving into SWIG's internals. Before typemap support was added to SWIG, helper functions were the only method for handling these kinds of problems. The pointer.i library file described earlier is an example of just this sort of approach. As a rule of thumb, I recommend that you try to use this approach before jumping into typemaps.

A Typemap Implementation

% glLightfv GL_LIGHT0 GL_AMBIENT {0.0 0.0 0.0 1.0}

What is a typemap?

%module example
%typemap(tcl,in) int {
	$target = atoi($source);
	printf("Received an integer : %d\n", $target);
}

int add(int a, int b);

In this case, we changed the processing of integers as input arguments to functions. When used in a Tcl script, we would get the following debugging information:

% set a [add 7 13]
Received an integer : 7
Received an integer : 13

Creating a new typemap

%typemap(lang,method) Datatype {
	... Conversion code ...
}

A single conversion can be applied to multiple datatypes by giving a comma separated list of datatypes. For example :

%typemap(tcl,in) int, short, long, signed char {
	$target = ($type) atol($source);
}

%typemap(perl5,in) char **argv {
	... Turn a perl array into a char ** ...
}

Finally, there is a shortened form of the typemap directive :

%typemap(method) Datatype {
	...
}

Deleting a typemap

%typemap(lang,method) Datatype;              // Deletes this typemap

Copying a typemap

%typemap(python,out) unsigned int = int;     // Copies a typemap

This is most commonly used when working with library files.

Typemap matching rules

%typemap(tcl,in) int * {
	... Convert an int * ...
}
%typemap(tcl,in) int [4] {
	... Convert an int[4] ...
}
%typemap(tcl,in) int out[4] {
	... Convert an out[4] ...
}
%typemap(tcl,in) int *status {
	... Convert an int *status ...
}

• Named arrays
• Unnamed arrays
• Named datatypes
• Unnamed datatypes

The following interface file shows how these rules are applied.

void foo1(int *); 				// Apply int * typemap
void foo2(int a[4]);         // Apply int[4] typemap
void foo3(int out[4]);       // Apply int out[4] typemap
void foo4(int *status);      // Apply int *status typemap
void foo5(int a[20]);        // Apply int * typemap (because int [20] is an int *)

Common typemap methods

Understanding how some of these methods are applied takes a little practice and better understanding of what SWIG does when it creates a wrapper function. The next few diagrams show the anatomy of a wrapper function and how the typemaps get applied. More detailed examples of typemaps can be found on the chapters for each target language.

Writing typemap code

Scope

Creating local variables

%typemap(tcl,in) int *INPUT(int temp) {
	temp = atoi($source);
	$target = &temp;
}

It is perfectly safe to use multiple typemaps involving local variables in the same function. For example, we could declare a function as :

void foo(int *INPUT, int *INPUT, int *INPUT);

Some typemaps do not recognize local variables (or they may simply not apply). At this time, only the "in", "argout", "default", and "ignore" typemaps use local variables.

Special variables

When found in the conversion code, these variables will be replaced with the correct values. Not all values are used in all typemaps. Please refer to the SWIG reference manual for the precise usage.

Typemaps for handling arrays

struct Person {
	char name[32];
	char address[64];
	int id;
};

swig -python  example.i
Generating wrappers for Python
example.i : Line 2. Warning. Array member will be read-only.
example.i : Line 3. Warning. Array member will be read-only.

These warning messages indicate that SWIG does not know how you want to set the name and address fields. As a result, you will only be able to query their value.

To fix this, we could supply two typemaps in the file such as the following :

%typemap(memberin) char [32] {
	strncpy($target,$source,32);
}
%typemap(memberin) char [64] {
	strncpy($target,$source,64);
}

// A better typemap for char arrays
%typemap(memberin) char [ANY] {
	strncpy($target,$source,$dim0);
}

Multidimensional arrays can also be handled by typemaps. For example :

// A typemap for handling any int [][] array
%typemap(memberin) int [ANY][ANY] {
	int i,j;
	for (i = 0; i < $dim0; i++)
		for (j = 0; j < $dim1; j++) {
			$target[i][j] = *($source+$dim1*i+j);
		}
}

The ANY keyword can be combined with any specific dimension. For example :

%typemap(python,in) int [ANY][4] {
	...
}

Typemaps and the SWIG Library

// file : stdmap.i
// A file containing a variety of useful typemaps

%typemap(tcl,in) int INTEGER {
	...
}
%typemap(tcl,in) double DOUBLE {
	...
}
%typemap(tcl,out) int INT {
	...
}
%typemap(tcl,out) double DOUBLE {
	...
}
%typemap(tcl,argout) double DOUBLE {
	...
}
// and so on...

// interface.i
// My interface file

%include stdmap.i                         // Load the typemap library

// Now grab the typemaps we want to use
%apply double DOUBLE {double};

// Rest of your declarations

In this case, stdmap.i contains a variety of standard mappings. The %apply directive lets us apply specific versions of these to new datatypes without knowing the underlying implementation details.

To clear a typemap that has been applied, you can use the %clear directive. For example :

%clear double x; 			// Clears any typemaps being applied to double x

Implementing constraints with typemaps

%module math

%typemap(perl5,check) double *posdouble {
	if ($target < 0) {
		croak("Expecting a positive number");
	}
}

...
double sqrt(double posdouble);

This kind of checking can be particularly useful when working with pointers. For example :

%typemap(python,check) Vector * {
	if ($target == 0) {
		PyErr_SetString(PyExc_TypeError,"NULL Pointer not allowed");
		return NULL;
	}
}

Typemap examples

How to break everything with a typemap

Typemaps and the future