// Set an item in the array and perform bounds checking. void setitem(int i, double val) {

if ((i >= 0) && (i < n)) ptr[i] = val;

else {

throw RangeError();

}

}

};

The functions associated with this class can throw a range exception for an out-of-bounds array access. We can catch this in our Perl extension by specifying the following in an interface file :

}

catch (RangeError) {

croak("Array index out-of-bounds");

}

}

Now, when the C++ class throws a RangeError exception, our wrapper functions will catch it, turn it into a Perl exception, and allow a graceful death as opposed to just having some sort of mysterious program crash. Since SWIG’s exception handling is user-definable, we are not limited to C++ exception handling. It is also possible to write a language-independent exception handler that works with other scripting languages. Please see the chapter on exception handling for more details.

Remapping datatypes with typemaps

While SWIG does a reasonable job with most C/C++ datatypes, it doesn’t always do what you want. However, you can remap SWIG’s treatment of just about any datatype using a typemap. A typemap simply specifies a conversion between Perl and C datatypes and can be used to process function arguments, function return values, and more. A similiar mechanism is used by the xsubpp compiler provided with Perl although the SWIG version provides many more options.

A simple typemap example

The following example shows how a simple typemap can be written :

%module example

%typemap(perl5,in) int {

$target = (int) SvIV($source); printf(“Received an integer : %d\n”, $target);

}

...

extern int fact(int n);

Typemap specifications require a language name, method name, datatype, and conversion code. For Perl5, “perl5” should be used as the language name. The “in” method refers to the input arguments of a function. The ‘int’ datatype tells SWIG that we are remapping integers. The conversion code is used to convert from a Perl scalar value to the corresponding datatype. Within

Version 1.1, June 24, 1997

the support code, the variable $source contains the source data (a Perl object) and $target contains the destination of the conversion (a C local variable).

When this example is used in Perl5, it will operate as follows :

use example;

$n = example::fact(6); print “$n\n”;

...

Output :

Received an integer : 6 720

General discussion of typemaps can be found in the main SWIG users reference.

Perl5 typemaps

The following typemap methods are available to Perl5 modules

Typemap variables

The following variables may be used within the C code used in a typemap :

Name based type conversion

Typemaps are based both on the datatype and an optional name attached to a datatype. For example :

%module foo

//This typemap will be applied to all char ** function arguments %typemap(perl5,in) char ** { ... }

//This typemap is applied only to char ** arguments named ‘argv’ %typemap(perl5,in) char **argv { ... }

Version 1.1, June 24, 1997

In this example, two typemaps are applied to the char ** datatype. However, the second typemap will only be applied to arguments named ‘argv’. A named typemap will always override an unnamed typemap.

Due to the name matching scheme, typemaps do not follow typedef declarations. For example :

Is is odd behavior to be sure, but you can work around the problem using the %apply directive as follows :

Named typemaps are extremely useful for managing special cases. It is also possible to use named typemaps to process output arguments (ie. function arguments that have values returned in them).

Converting a Perl5 array to a char **

A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. The following SWIG interface file allows a Perl5 array reference to be used as a char ** datatype.

%module argv

// This tells SWIG to treat char ** as a special case %typemap(perl5,in) char ** {

AV *tempav; I32 len; int i;

SV **tv;

if (!SvROK($source))

croak("$source is not a reference."); if (SvTYPE(SvRV($source)) != SVt_PVAV)

croak("$source is not an array."); tempav = (AV*)SvRV($source);

len = av_len(tempav);

$target = (char **) malloc((len+2)*sizeof(char *)); for (i = 0; i <= len; i++) {

tv = av_fetch(tempav, i, 0); $target[i] = (char *) SvPV(*tv,na);

}

$target[i] = 0;

Version 1.1, June 24, 1997

};

//This cleans up our char ** array after the function call %typemap(perl5,freearg) char ** {

free($source);

}

//Creates a new Perl array and places a char ** into it %typemap(perl5,out) char ** {

AV *myav; SV **svs;

int i = 0,len = 0;

/* Figure out how many elements we have */ while ($source[len])

len++;

svs = (SV **) malloc(len*sizeof(SV *)); for (i = 0; i < len ; i++) {

svs[i] = sv_newmortal(); sv_setpv((SV*)svs[i],$source[i]);

};

myav = av_make(len,svs); free(svs);

$target = newRV((SV*)myav); sv_2mortal($target);

}

//Now a few test functions

%inline %{

int print_args(char **argv) { int i = 0;

while (argv[i]) {

printf("argv[%d] = %s\n", i,argv[i]); i++;

}

return i;

}

// Returns a char ** list char **get_args() {

static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0}; return &values[0];

}

%}

When this module is compiled, our wrapped C functions can be used in a Perl script as follows :

Of course, there are many other possibilities. As an alternative to array references, we could pass in strings separated by some delimeter and perform a splitting operation in C.

Using typemaps to return values

Sometimes it is desirable for a function to return a value in one of its arguments. A named

Version 1.1, June 24, 1997