Software: Apache/2.0.54 (Fedora). PHP/5.0.4 

uname -a: Linux mina-info.me 2.6.17-1.2142_FC4smp #1 SMP Tue Jul 11 22:57:02 EDT 2006 i686 

uid=48(apache) gid=48(apache) groups=48(apache)
context=system_u:system_r:httpd_sys_script_t 

Safe-mode: OFF (not secure)

/usr/share/doc/swig-1.3.24/Manual/   drwxr-xr-x
Free 5.1 GB of 27.03 GB (18.86%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     Library.html (36.98 KB)      -rw-r--r--

8 SWIG library

• The %include directive and library search path
• C Arrays and Pointers
  • cpointer.i
  • carrays.i
  • cmalloc.i
  • cdata.i
• C String Handling
  • Default string handling
  • Passing binary data
  • Using %newobject to release memory
  • cstring.i
• C++ Library
  • std_string.i
  • std_vector.i
• Utility Libraries
  • exception.i

Compatibility note: Older versions of SWIG included a number of library files for manipulating pointers, arrays, and other structures. Most these files are now deprecated and have been removed from the distribution. Alternative libraries provide similar functionality. Please read this chapter carefully if you used the old libraries.

8.1 The %include directive and library search path

• The current directory
• Directories specified with the -I command line option
• ./swig_lib
• /usr/local/lib/swig_lib (or wherever you installed SWIG)
• On Windows, SWIG also looks for the library relative to the location of swig.exe.

Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., python, tcl, etc.). If found, SWIG will search the language specific directory first. This allows for language-specific implementations of library files.

You can override the location of the SWIG library by setting the SWIG_LIB environment variable.

8.2 C Arrays and Pointers

8.2.1 cpointer.i

%pointer_functions(type,name)

Generates a collection of four functions for manipulating a pointer type *:

type *new_name()

Creates a new object of type type and returns a pointer to it. In C, the object is created using calloc(). In C++, new is used.

type *copy_name(type value)

Creates a new object of type type and returns a pointer to it. An initial value is set by copying it from value. In C, the object is created using calloc(). In C++, new is used.

type *delete_name(type *obj)

Deletes an object type type.

void name_assign(type *obj, type value)

Assigns *obj = value.

type name_value(type *obj)

Returns the value of *obj.

When using this macro, type may be any type and name must be a legal identifier in the target language. name should not correspond to any other name used in the interface file.

%module example
%include "cpointer.i"

/* Create some functions for working with "int *" */
%pointer_functions(int, intp);

/* A function that uses an "int *" */
void add(int x, int y, int *result);

>>> import example
>>> c = example.new_intp()     # Create an "int" for storing result
>>> example.add(3,4,c)         # Call function   
>>> example.intp_value(c)      # Dereference
7
>>> example.delete_intp(c)     # Delete

%pointer_class(type,name)

Wraps a pointer of type * inside a class-based interface. This interface is as follows:

struct name {
   name();                            // Create pointer object
  ~name();                            // Delete pointer object
   void assign(type value);           // Assign value
   type value();                      // Get value
   type *cast();                      // Cast the pointer to original type
   static name *frompointer(type *);  // Create class wrapper from existing
                                      // pointer
};

When using this macro, type is restricted to a simple type name like int, float, or Foo. Pointers and other complicated types are not allowed. name must be a valid identifier not already in use. When a pointer is wrapped as a class, the "class" may be transparently passed to any function that expects the pointer.

If the target language does not support proxy classes, the use of this macro will produce the example same functions as %pointer_functions() macro.

It should be noted that the class interface does introduce a new object or wrap a pointer inside a special structure. Instead, the raw pointer is used directly.

%module example
%include "cpointer.i"

/* Wrap a class interface around an "int *" */
%pointer_class(int, intp);

/* A function that uses an "int *" */
void add(int x, int y, int *result);

>>> import example
>>> c = example.intp()         # Create an "int" for storing result
>>> example.add(3,4,c)         # Call function   
>>> c.value()                  # Dereference
7

%pointer_cast(type1, type2, name)

Creates a casting function that converts type1 to type2. The name of the function is name. For example:

%pointer_cast(int *, unsigned int *, int_to_uint);

In this example, the function int_to_uint() would be used to cast types in the target language.

Note: None of these macros can be used to safely work with strings (char * or char **).

Note: When working with simple pointers, typemaps can often be used to provide more seamless operation.

8.2.2 carrays.i

%array_functions(type,name)

Creates four functions.

type *new_name(int nelements)

Creates a new array of objects of type type. In C, the array is allocated using calloc(). In C++, new [] is used.

type *delete_name(type *ary)

Deletes an array. In C, free() is used. In C++, delete [] is used.

type name_getitem(type *ary, int index)

Returns the value ary[index].

void name_setitem(type *ary, int index, type value)

Assigns ary[index] = value.

When using this macro, type may be any type and name must be a legal identifier in the target language. name should not correspond to any other name used in the interface file.

Here is an example of %array_functions(). Suppose you had a function like this:

void print_array(double x[10]) {
   int i;
   for (i = 0; i < 10; i++) {
      printf("[%d] = %g\n", i, x[i]);
   }
}

%module example

%include "carrays.i"
%array_functions(double, doubleArray);

void print_array(double x[10]);

a = new_doubleArray(10)           # Create an array
for i in range(0,10):
    doubleArray_setitem(a,i,2*i)  # Set a value
print_array(a)                    # Pass to C
delete_doubleArray(a)             # Destroy array

Wraps a pointer of type * inside a class-based interface. This interface is as follows:

struct name {
   name(int nelements);               // Create an array
  ~name();                            // Delete array
   type getitem(int index);           // Return item
   void setitem(index, type value);   // Set item
   type *cast();                      // Cast to original type
   static name *frompointer(type *);  // Create class wrapper from
                                      // existing pointer
};

When using this macro, type is restricted to a simple type name like int or float. Pointers and other complicated types are not allowed. name must be a valid identifier not already in use. When a pointer is wrapped as a class, it can be transparently passed to any function that expects the pointer.

When combined with proxy classes, the %array_class() macro can be especially useful. For example:

%module example
%include "carrays.i"
%array_class(double, doubleArray);

void print_array(double x[10]);

import example
c = example.doubleArray(10)  # Create double[10]
for i in range(0,10):
    c[i] = 2*i               # Assign values
example.print_array(c)       # Pass to C

Note: These macros do not encapsulate C arrays inside a special data structure or proxy. There is no bounds checking or safety of any kind. If you want this, you should consider using a special array object rather than a bare pointer.

Note: %array_functions() and %array_class() should not be used with types of char or char *.

8.2.3 cmalloc.i

%malloc(type [,name=type])

Creates a wrapper around malloc() with the following prototype:

type *malloc_name(int nbytes = sizeof(type));

If type is void, then the size parameter nbytes is required. The name parameter only needs to be specified when wrapping a type that is not a valid identifier (e.g., "int *", "double **", etc.).

%calloc(type [,name=type])

Creates a wrapper around calloc() with the following prototype:

type *calloc_name(int nobj =1, int sz = sizeof(type));

If type is void, then the size parameter sz is required.

%realloc(type [,name=type])

Creates a wrapper around realloc() with the following prototype:

type *realloc_name(type *ptr, int nitems);

Note: unlike the C realloc(), the wrapper generated by this macro implicitly includes the size of the corresponding type. For example, realloc_int(p, 100) reallocates p so that it holds 100 integers.

%free(type [,name=type])

Creates a wrapper around free() with the following prototype:

void free_name(type *ptr);

%sizeof(type [,name=type])

Creates the constant:

%constant int sizeof_name = sizeof(type);

%allocators(type [,name=type])

Generates wrappers for all five of the above operations.

Here is a simple example that illustrates the use of these macros:

// SWIG interface
%module example
%include "cmalloc.i"

%malloc(int);
%free(int);

%malloc(int *, intp);
%free(int *, intp);

%allocators(double);

>>> from example import *
>>> a = malloc_int()
>>> a
'_000efa70_p_int'
>>> free_int(a)    
>>> b = malloc_intp()
>>> b
'_000efb20_p_p_int'
>>> free_intp(b)
>>> c = calloc_double(50)
>>> c
'_000fab98_p_double'
>>> c = realloc_double(100000)
>>> free_double(c)
>>> print sizeof_double
8
>>>

8.2.4 cdata.i

char *cdata(void *ptr, int nbytes)

Converts nbytes of data at ptr into a string. ptr can be any pointer.

void memmove(void *ptr, char *s)

Copies all of the string data in s into the memory pointed to by ptr. The string may contain embedded NULL bytes. The length of the string is implicitly determined in the underlying wrapper code.

// SWIG interface
%module example
%include "carrays.i"
%include "cdata.i"

%array_class(int, intArray);

>>> a = intArray(10)
>>> for i in range(0,10):
...    a[i] = i
>>> b = cdata(a,40)
>>> b
'\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04
\x00\x00\x00\x05\x00\x00\x00\x06\x00\x00\x00\x07\x00\x00\x00\x08\x00\x00\x00\t'
>>> c = intArray(10)
>>> memmove(c,b)
>>> print c[4]
4
>>> 

%cdata(type [,name=type])

Generates the following function for extracting C data for a given type.

char *cdata_name(int nitems)

nitems is the number of items of the given type to extract.

8.3 C String Handling

The problems (and perils) of using char * are well-known. However, SWIG is not in the business of enforcing morality. The modules in this section provide basic functionality for manipulating raw C strings.

8.3.1 Default string handling

char *foo(char *s);

% foo Hello

There are obvious problems with the default behavior. First, since a char * argument points to data inside the target language, it is NOT safe for a function to modify this data (doing so may corrupt the interpreter and lead to a crash). Furthermore, the default behavior does not work well with binary data. Instead, strings are assumed to be NULL-terminated.

8.3.2 Passing binary data

int parity(char *str, int len, int initial);

%apply (char *STRING, int LENGTH) { (char *str, int len) };
...
int parity(char *str, int len, int initial);

>>> s = "H\x00\x15eg\x09\x20"
>>> parity(s,0)

8.3.3 Using %newobject to release memory

char *foo() {
   char *result = (char *) malloc(...);
   ...
   return result;
}

To fix the memory leak, use the %newobject directive.

%newobject foo;
...
char *foo();

8.3.4 cstring.i

void get_path(char *s) {
    // Potential buffer overflow---uh, oh.
    sprintf(s,"%s/%s", base_directory, sub_directory);
}
...
// Somewhere else in the C program
{
    char path[1024];
    ...
    get_path(path);
    ...
}

The macros defined in this module all expand to various combinations of typemaps. Therefore, the same pattern matching rules and ideas apply.

%cstring_bounded_output(parm, maxsize)

Turns parameter parm into an output value. The output string is assumed to be NULL-terminated and smaller than maxsize characters. Here is an example:

%cstring_bounded_output(char *path, 1024);
...
void get_path(char *path);

In the target language:

>>> get_path()
/home/beazley/packages/Foo/Bar
>>>

Internally, the wrapper function allocates a small buffer (on the stack) of the requested size and passes it as the pointer value. Data stored in the buffer is then returned as a function return value. If the function already returns a value, then the return value and the output string are returned together (multiple return values). If more than maxsize bytes are written, your program will crash with a buffer overflow!

%cstring_chunk_output(parm, chunksize)

Turns parameter parm into an output value. The output string is always chunksize and may contain binary data. Here is an example:

%cstring_chunk_output(char *packet, PACKETSIZE);
...
void get_packet(char *packet);

In the target language:

>>> get_packet()
'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
>>>

This macro is essentially identical to %cstring_bounded_output. The only difference is that the result is always chunksize characters. Furthermore, the result can contain binary data. If more than maxsize bytes are written, your program will crash with a buffer overflow!

%cstring_bounded_mutable(parm, maxsize)

Turns parameter parm into a mutable string argument. The input string is assumed to be NULL-terminated and smaller than maxsize characters. The output string is also assumed to be NULL-terminated and less than maxsize characters.

%cstring_bounded_mutable(char *ustr, 1024);
...
void make_upper(char *ustr);

In the target language:

>>> make_upper("hello world")
'HELLO WORLD'
>>>

Internally, this macro is almost exactly the same as %cstring_bounded_output. The only difference is that the parameter accepts an input value that is used to initialize the internal buffer. It is important to emphasize that this function does not mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If more than maxsize bytes are written, your program will crash with a buffer overflow!

%cstring_mutable(parm [, expansion])

Turns parameter parm into a mutable string argument. The input string is assumed to be NULL-terminated. An optional parameter expansion specifies the number of extra characters by which the string might grow when it is modified. The output string is assumed to be NULL-terminated and less than the size of the input string plus any expansion characters.

%cstring_mutable(char *ustr);
...
void make_upper(char *ustr);

%cstring_mutable(char *hstr, HEADER_SIZE);
...
void attach_header(char *hstr);

In the target language:

>>> make_upper("hello world")
'HELLO WORLD'
>>> attach_header("Hello world")
'header: Hello world'
>>>

This macro differs from %cstring_bounded_mutable() in that a buffer is dynamically allocated (on the heap using malloc/new). This buffer is always large enough to store a copy of the input value plus any expansion bytes that might have been requested. It is important to emphasize that this function does not directly mutate the string value passed---instead it makes a copy of the input value, mutates it, and returns it as a result. If the function expands the result by more than expansion extra bytes, then the program will crash with a buffer overflow!

%cstring_output_maxsize(parm, maxparm)

This macro is used to handle bounded character output functions where both a char * and a maximum length parameter are provided. As input, a user simply supplies the maximum length. The return value is assumed to be a NULL-terminated string.

%cstring_output_maxsize(char *path, int maxpath);
...
void get_path(char *path, int maxpath);

In the target language:

>>> get_path(1024)
'/home/beazley/Packages/Foo/Bar'
>>>

This macro provides a safer alternative for functions that need to write string data into a buffer. User supplied buffer size is used to dynamically allocate memory on heap. Results are placed into that buffer and returned as a string object.

%cstring_output_withsize(parm, maxparm)

This macro is used to handle bounded character output functions where both a char * and a pointer int * are passed. Initially, the int * parameter points to a value containing the maximum size. On return, this value is assumed to contain the actual number of bytes. As input, a user simply supplies the maximum length. The output value is a string that may contain binary data.

%cstring_output_withsize(char *data, int *maxdata);
...
void get_data(char *data, int *maxdata);

In the target language:

>>> get_data(1024)
'x627388912'
>>> get_data(1024)
'xyzzy'
>>>

This macro is a somewhat more powerful version of %cstring_output_chunk(). Memory is dynamically allocated and can be arbitrary large. Furthermore, a function can control how much data is actually returned by changing the value of the maxparm argument.

%cstring_output_allocate(parm, release)

This macro is used to return strings that are allocated within the program and returned in a parameter of type char **. For example:

void foo(char **s) {
    *s = (char *) malloc(64);
    sprintf(*s, "Hello world\n");
}

The returned string is assumed to be NULL-terminated. release specifies how the allocated memory is to be released (if applicable). Here is an example:

%cstring_output_allocate(char **s, free(*$1));
...
void foo(char **s);

In the target language:

>>> foo()
'Hello world\n'
>>>

%cstring_output_allocate_size(parm, szparm, release)

This macro is used to return strings that are allocated within the program and returned in two parameters of type char ** and int *. For example:

void foo(char **s, int *sz) {
    *s = (char *) malloc(64);
    *sz = 64;
    // Write some binary data
    ...
}

The returned string may contain binary data. release specifies how the allocated memory is to be released (if applicable). Here is an example:

%cstring_output_allocate_size(char **s, int *slen, free(*$1));
...
void foo(char **s, int *slen);

In the target language:

>>> foo()
'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
>>>

This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:

char  *get_data(int *len);

You could wrap it with a function like this:

void my_get_data(char **result, int *len) {
   *result = get_data(len);
}

• Support for the cstring.i module depends on the target language. Not all SWIG modules currently support this library.
• Reliable handling of raw C strings is a delicate topic. There are many ways to accomplish this in SWIG. This library provides support for a few common techniques.
• If used in C++, this library uses new and delete [] for memory allocation. If using ANSI C, the library uses malloc() and free().
• Rather than manipulating char * directly, you might consider using a special string structure or class instead.

8.4 C++ Library

8.4.1 std_string.i

%module example
%include "std_string.i"

std::string foo();
void        bar(const std::string &x);

x = foo();                # Returns a string object
bar("Hello World");       # Pass string as std::string

This library file is fully aware of C++ namespaces. If you export std::string or rename it with a typedef, make sure you include those declarations in your interface. For example:

%module example
%include "std_string.i"

using namespace std;
typedef std::string String;
...
void foo(string s, const String &t);     // std_string typemaps still applied

8.4.2 std_vector.i

%module example
%include "std_vector.i"

namespace std {
   %template(vectori) vector<int>;
   %template(vectord) vector<double>;
};

• A class that exposes the C++ API is created in the target language . This can be used to create objects, invoke methods, etc. This class is currently a subset of the real STL vector class.
• Input typemaps are defined for vector<X>, const vector<X> &, and const vector<X> *. For each of these, a pointer vector<X> * may be passed or a native list object in the target language.
• An output typemap is defined for vector<X>. In this case, the values in the vector are expanded into a list object in the target language.
• For all other variations of the type, the wrappers expect to receive a vector<X> * object in the usual manner.
• An exception handler for std::out_of_range is defined.
• Optionally, special methods for indexing, item retrieval, slicing, and element assignment may be defined. This depends on the target language.

/* File : example.h */

#include <vector>
#include <algorithm>
#include <functional>
#include <numeric>

double average(std::vector<int> v) {
    return std::accumulate(v.begin(),v.end(),0.0)/v.size();
}

std::vector<double> half(const std::vector<double>& v) {
    std::vector<double> w(v);
    for (unsigned int i=0; i<w.size(); i++)
        w[i] /= 2.0;
    return w;
}

void halve_in_place(std::vector<double>& v) {
    std::transform(v.begin(),v.end(),v.begin(),
                   std::bind2nd(std::divides<double>(),2.0));
}

%module example
%{
#include "example.h"
%}

%include "std_vector.i"
// Instantiate templates used by example
namespace std {
   %template(IntVector) vector<int>;
   %template(DoubleVector) vector<double>;
}

// Include the header file with above prototypes
%include "example.h"

>>> from example import *
>>> iv = IntVector(4)         # Create an vector<int>
>>> for i in range(0,4):
...      iv[i] = i
>>> average(iv)               # Call method
1.5
>>> average([0,1,2,3])        # Call with list
1.5
>>> half([1,2,3])             # Half a list
(0.5,1.0,1.5)
>>> halve_in_place([1,2,3])   # Oops
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: Type error. Expected _p_std__vectorTdouble_t
>>> dv = DoubleVector(4)
>>> for i in range(0,4):
...       dv[i] = i
>>> halve_in_place(dv)       # Ok
>>> for i in dv:
...       print i
...
0.0
0.5
1.0
1.5
>>> dv[20] = 4.5
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "example.py", line 81, in __setitem__
    def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args)
IndexError: vector index out of range
>>>

%include "std_vector.i"

namespace std {
    %template(IntVector) vector<int>;
}

using namespace std;
typedef std::vector Vector;

void foo(vector<int> *x, const Vector &x);

Note: This module makes use of several advanced SWIG features including templatized typemaps and template partial specialization. If you are tring to wrap other C++ code with templates, you might look at the code contained in std_vector.i. Alternatively, you can show them the code if you want to make their head explode.

Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.

Note: std_vector.i was written by Luigi "The Amazing" Ballabio.

8.5 Utility Libraries

8.5.1 exception.i

SWIG_exception(int code, const char *message)

Raises an exception in the target language. code is one of the following symbolic constants:

SWIG_MemoryError
SWIG_IOError
SWIG_RuntimeError
SWIG_IndexError
SWIG_TypeError
SWIG_DivisionByZero
SWIG_OverflowError
SWIG_SyntaxError
SWIG_ValueError
SWIG_SystemError

message is a string indicating more information about the problem.

%include "exception.i"
%exception std::vector::getitem {
    try {
        $action
    } catch (std::out_of_range& e) {
        SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
    }
}