/Doc/Manual/Library.html
HTML | 1781 lines | 1421 code | 358 blank | 2 comment | 0 complexity | 586f3cdaab8fe36f058badf1728f6214 MD5 | raw file
Possible License(s): 0BSD, GPL-2.0, LGPL-2.1
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <title>SWIG Library</title>
- <link rel="stylesheet" type="text/css" href="style.css">
- </head>
- <body bgcolor="#ffffff">
- <H1><a name="Library"></a>8 SWIG library</H1>
- <!-- INDEX -->
- <div class="sectiontoc">
- <ul>
- <li><a href="#Library_nn2">The %include directive and library search path</a>
- <li><a href="#Library_nn3">C Arrays and Pointers</a>
- <ul>
- <li><a href="#Library_nn4">cpointer.i</a>
- <li><a href="#Library_carrays">carrays.i</a>
- <li><a href="#Library_nn6">cmalloc.i</a>
- <li><a href="#Library_nn7">cdata.i</a>
- </ul>
- <li><a href="#Library_nn8">C String Handling</a>
- <ul>
- <li><a href="#Library_nn9">Default string handling</a>
- <li><a href="#Library_nn10">Passing binary data</a>
- <li><a href="#Library_nn11">Using %newobject to release memory</a>
- <li><a href="#Library_nn12">cstring.i</a>
- </ul>
- <li><a href="#Library_stl_cpp_library">STL/C++ Library</a>
- <ul>
- <li><a href="#Library_nn14">std_string.i</a>
- <li><a href="#Library_nn15">std_vector.i</a>
- <li><a href="#Library_stl_exceptions">STL exceptions</a>
- </ul>
- <li><a href="#Library_nn16">Utility Libraries</a>
- <ul>
- <li><a href="#Library_nn17">exception.i</a>
- </ul>
- </ul>
- </div>
- <!-- INDEX -->
- <p>
- To help build extension modules, SWIG is packaged with a library of
- support files that you can include in your own interfaces. These
- files often define new SWIG directives or provide utility
- functions that can be used to access parts of the standard C and C++ libraries.
- This chapter provides a reference to the current set of supported library files.
- </p>
- <p>
- <b>Compatibility note:</b> 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.
- </p>
- <H2><a name="Library_nn2"></a>8.1 The %include directive and library search path</H2>
- <p>
- Library files are included using the <tt>%include</tt> directive.
- When searching for files, directories are searched in the following order:
- </p>
- <ul>
- <li>The current directory
- <li>Directories specified with the <tt>-I</tt> command line option
- <li>.<tt>/swig_lib</tt>
- <li>SWIG library install location as reported by <tt>swig -swiglib</tt>, for example <tt>/usr/local/share/swig/1.3.30</tt>
- <li>On Windows, a directory <tt>Lib</tt> relative to the location of <tt>swig.exe</tt> is also searched.
- </ul>
- <p>
- Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., <tt>python</tt>,
- <tt>tcl</tt>, etc.). If found, SWIG will search the language specific directory first. This allows
- for language-specific implementations of library files.
- </p>
- <p>
- You can ignore the installed SWIG library by setting the <tt>SWIG_LIB</tt> environment variable.
- Set the environment variable to hold an alternative library directory.
- </p>
- <p>
- The directories that are searched are displayed when using <tt>-verbose</tt> commandline option.
- </p>
- <H2><a name="Library_nn3"></a>8.2 C Arrays and Pointers</H2>
- <p>
- This section describes library modules for manipulating low-level C arrays and pointers.
- The primary use of these modules is in supporting C declarations that manipulate bare
- pointers such as <tt>int *</tt>, <tt>double *</tt>, or <tt>void *</tt>. The modules can be
- used to allocate memory, manufacture pointers, dereference memory, and wrap
- pointers as class-like objects. Since these functions provide direct access to
- memory, their use is potentially unsafe and you should exercise caution.
- </p>
- <H3><a name="Library_nn4"></a>8.2.1 cpointer.i</H3>
- <p>
- The <tt>cpointer.i</tt> module defines macros that can be used to used
- to generate wrappers around simple C pointers. The primary use of
- this module is in generating pointers to primitive datatypes such as
- <tt>int</tt> and <tt>double</tt>.
- </p>
- <p>
- <b><tt>%pointer_functions(type,name)</tt></b>
- </p>
- <div class="indent">
- <p>Generates a collection of four functions for manipulating a pointer <tt>type *</tt>:</p>
- <p>
- <tt>type *new_name()</tt>
- </p>
- <div class="indent"><p>
- Creates a new object of type <tt>type</tt> and returns a pointer to it. In C, the
- object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used.
- </p></div>
- <p>
- <tt>type *copy_name(type value)</tt>
- </p>
- <div class="indent"><p>
- Creates a new object of type <tt>type</tt> and returns a pointer to it.
- An initial value is set by copying it from <tt>value</tt>. In C, the
- object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used.
- </p></div>
- <p>
- <tt>type *delete_name(type *obj)</tt>
- </p>
- <div class="indent"><p>
- Deletes an object type <tt>type</tt>.
- </p></div>
- <p>
- <tt>void name_assign(type *obj, type value)</tt>
- </p>
- <div class="indent"><p>
- Assigns <tt>*obj = value</tt>.
- </p></div>
- <p>
- <tt>type name_value(type *obj)</tt>
- </p>
- <div class="indent"><p>
- Returns the value of <tt>*obj</tt>.
- </p></div>
- <p>
- When using this macro, <tt>type</tt> may be any type and <tt>name</tt> must be a legal identifier in the target
- language. <tt>name</tt> should not correspond to any other name used in the interface file.
- </p>
- <p>
- Here is a simple example of using <tt>%pointer_functions()</tt>:
- </p>
- <div class="code">
- <pre>
- %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);
- </pre>
- </div>
- <p>
- Now, in Python:
- </p>
- <div class="targetlang">
- <pre>
- >>> 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
- </pre>
- </div>
- </div>
- <p>
- <b><tt>%pointer_class(type,name)</tt></b>
- </p>
- <div class="indent">
- <p>
- Wraps a pointer of <tt>type *</tt> inside a class-based interface. This
- interface is as follows:
- </p>
- <div class="code">
- <pre>
- 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
- };
- </pre>
- </div>
- <p>
- When using this macro, <tt>type</tt> is restricted to a simple type
- name like <tt>int</tt>, <tt>float</tt>, or <tt>Foo</tt>. Pointers and
- other complicated types are not allowed. <tt>name</tt> 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.
- </p>
- <p>
- If the target language does not support proxy classes, the use of this macro will produce the example
- same functions as <tt>%pointer_functions()</tt> macro.
- </p>
- <p>
- 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.
- </p>
- <p>
- Here is the same example using a class instead:
- </p>
- <div class="code">
- <pre>
- %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);
- </pre>
- </div>
- <p>
- Now, in Python (using proxy classes)
- </p>
- <div class="targetlang">
- <pre>
- >>> import example
- >>> c = example.intp() # Create an "int" for storing result
- >>> example.add(3,4,c) # Call function
- >>> c.value() # Dereference
- 7
- </pre>
- </div>
- <p>
- Of the two macros, <tt>%pointer_class</tt> is probably the most convenient when working with simple
- pointers. This is because the pointers are access like objects and they can be easily garbage collected
- (destruction of the pointer object destroys the underlying object).
- </p>
- </div>
- <p>
- <b><tt>%pointer_cast(type1, type2, name)</tt></b>
- </p>
- <div class="indent">
- <p>
- Creates a casting function that converts <tt>type1</tt> to <tt>type2</tt>. The name of the function is <tt>name</tt>.
- For example:
- </p>
- <div class="code">
- <pre>
- %pointer_cast(int *, unsigned int *, int_to_uint);
- </pre>
- </div>
- <p>
- In this example, the function <tt>int_to_uint()</tt> would be used to cast types in the target language.
- </p>
- </div>
- <p>
- <b>Note:</b> None of these macros can be used to safely work with strings (<tt>char *</tt> or <tt>char **</tt>).
- </p>
- <P>
- <b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation.
- </p>
- <H3><a name="Library_carrays"></a>8.2.2 carrays.i</H3>
- <p>
- This module defines macros that assist in wrapping ordinary C pointers as arrays.
- The module does not provide any safety or an extra layer of wrapping--it merely
- provides functionality for creating, destroying, and modifying the contents of
- raw C array data.
- </p>
- <p>
- <b><tt>%array_functions(type,name)</tt></b>
- </p>
- <div class="indent">
- <p>Creates four functions.</p>
- <p>
- <tt>type *new_name(int nelements)</tt>
- </p>
- <div class="indent"><p>
- Creates a new array of objects of type <tt>type</tt>. In C, the array is allocated using
- <tt>calloc()</tt>. In C++, <tt>new []</tt> is used.
- </p></div>
- <p>
- <tt>type *delete_name(type *ary)</tt>
- </p>
- <div class="indent"><p>
- Deletes an array. In C, <tt>free()</tt> is used. In C++, <tt>delete []</tt> is used.
- </p></div>
- <p>
- <tt>type name_getitem(type *ary, int index)</tt>
- </p>
- <div class="indent"><p>
- Returns the value <tt>ary[index]</tt>.
- </p></div>
- <p>
- <tt>void name_setitem(type *ary, int index, type value)</tt>
- </p>
- <div class="indent"><p>
- Assigns <tt>ary[index] = value</tt>.
- </p></div>
- <p>
- When using this macro, <tt>type</tt> may be any type and <tt>name</tt>
- must be a legal identifier in the target language. <tt>name</tt>
- should not correspond to any other name used in the interface file.
- </p>
- <p>
- Here is an example of <tt>%array_functions()</tt>. Suppose you had a
- function like this:
- </p>
- <div class="code">
- <pre>
- void print_array(double x[10]) {
- int i;
- for (i = 0; i < 10; i++) {
- printf("[%d] = %g\n", i, x[i]);
- }
- }
- </pre>
- </div>
- <p>
- To wrap it, you might write this:
- </p>
- <div class="code">
- <pre>
- %module example
- %include "carrays.i"
- %array_functions(double, doubleArray);
- void print_array(double x[10]);
- </pre>
- </div>
- <p>
- Now, in a scripting language, you might write this:
- </p>
- <div class="code">
- <pre>
- 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
- </pre>
- </div>
- </div>
- <p>
- <b><tt>%array_class(type,name)</tt></b>
- </p>
- <div class="indent">
- <p>
- Wraps a pointer of <tt>type *</tt> inside a class-based interface. This
- interface is as follows:
- </p>
- <div class="code">
- <pre>
- struct name {
- name(int nelements); // Create an array
- ~name(); // Delete array
- type getitem(int index); // Return item
- void setitem(int index, type value); // Set item
- type *cast(); // Cast to original type
- static name *frompointer(type *); // Create class wrapper from
- // existing pointer
- };
- </pre>
- </div>
- <p>
- When using this macro, <tt>type</tt> is restricted to a simple type
- name like <tt>int</tt> or <tt>float</tt>. Pointers and
- other complicated types are not allowed. <tt>name</tt> 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.
- </p>
- <p>
- When combined with proxy classes, the <tt>%array_class()</tt> macro can be especially useful.
- For example:
- </p>
- <div class="code">
- <pre>
- %module example
- %include "carrays.i"
- %array_class(double, doubleArray);
- void print_array(double x[10]);
- </pre>
- </div>
- <p>
- Allows you to do this:
- </p>
- <div class="code">
- <pre>
- 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
- </pre>
- </div>
- </div>
- <p>
- <b>Note:</b> 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.
- </p>
- <p>
- <b>Note:</b> <tt>%array_functions()</tt> and <tt>%array_class()</tt> should not be
- used with types of <tt>char</tt> or <tt>char *</tt>.
- </p>
- <H3><a name="Library_nn6"></a>8.2.3 cmalloc.i</H3>
- <p>
- This module defines macros for wrapping the low-level C memory allocation functions
- <tt>malloc()</tt>, <tt>calloc()</tt>, <tt>realloc()</tt>, and <tt>free()</tt>.
- </p>
- <p>
- <b><tt>%malloc(type [,name=type])</tt></b>
- </p>
- <div class="indent">
- <p>
- Creates a wrapper around <tt>malloc()</tt> with the following prototype:
- </p>
- <div class="code"><pre>
- <em>type</em> *malloc_<em>name</em>(int nbytes = sizeof(<em>type</em>));
- </pre>
- </div>
- <p>
- If <tt>type</tt> is <tt>void</tt>, then the size parameter <tt>nbytes</tt> is required.
- The <tt>name</tt> parameter only needs to be specified when wrapping a type that
- is not a valid identifier (e.g., "<tt>int *</tt>", "<tt>double **</tt>", etc.).
- </p>
- </div>
- <p>
- <b><tt>%calloc(type [,name=type])</tt></b>
- </p>
- <div class="indent">
- <p>
- Creates a wrapper around <tt>calloc()</tt> with the following prototype:
- </p>
- <div class="code"><pre>
- <em>type</em> *calloc_<em>name</em>(int nobj =1, int sz = sizeof(<em>type</em>));
- </pre>
- </div>
- <p>
- If <tt>type</tt> is <tt>void</tt>, then the size parameter <tt>sz</tt> is required.
- </p>
- </div>
- <p>
- <b><tt>%realloc(type [,name=type])</tt></b>
- </p>
- <div class="indent">
- <p>
- Creates a wrapper around <tt>realloc()</tt> with the following prototype:
- </p>
- <div class="code"><pre>
- <em>type</em> *realloc_<em>name</em>(<em>type</em> *ptr, int nitems);
- </pre>
- </div>
- <p>
- Note: unlike the C <tt>realloc()</tt>, the wrapper generated by this macro implicitly includes the
- size of the corresponding type. For example, <tt>realloc_int(p, 100)</tt> reallocates <tt>p</tt> so that
- it holds 100 integers.
- </p>
- </div>
- <p>
- <b><tt>%free(type [,name=type])</tt></b>
- </p>
- <div class="indent">
- <p>
- Creates a wrapper around <tt>free()</tt> with the following prototype:
- </p>
- <div class="code"><pre>
- void free_<em>name</em>(<em>type</em> *ptr);
- </pre>
- </div>
- </div>
- <p>
- <b><tt>%sizeof(type [,name=type])</tt></b>
- </p>
- <div class="indent">
- <p>
- Creates the constant:
- </p>
- <div class="code"><pre>
- %constant int sizeof_<em>name</em> = sizeof(<em>type</em>);
- </pre>
- </div>
- </div>
- <p>
- <b><tt>%allocators(type [,name=type])</tt></b>
- </p>
- <div class="indent"><p>
- Generates wrappers for all five of the above operations.
- </p></div>
- <p>
- Here is a simple example that illustrates the use of these macros:
- </p>
- <div class="code">
- <pre>
- // SWIG interface
- %module example
- %include "cmalloc.i"
- %malloc(int);
- %free(int);
- %malloc(int *, intp);
- %free(int *, intp);
- %allocators(double);
- </pre>
- </div>
- <p>
- Now, in a script:
- </p>
- <div class="targetlang">
- <pre>
- >>> 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
- >>>
- </pre>
- </div>
- <H3><a name="Library_nn7"></a>8.2.4 cdata.i</H3>
- <p>
- The <tt>cdata.i</tt> module defines functions for converting raw C data to and from strings
- in the target language. The primary applications of this module would be packing/unpacking of
- binary data structures---for instance, if you needed to extract data from a buffer.
- The target language must support strings with embedded binary data
- in order for this to work.
- </p>
- <p>
- <b><tt>const char *cdata(void *ptr, size_t nbytes)</tt></b>
- </p>
- <div class="indent"><p>
- Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any
- pointer.
- </p></div>
- <p>
- <b><tt>void memmove(void *ptr, const char *s)</tt></b>
- </p>
- <div class="indent"><p>
- Copies all of the string data in <tt>s</tt> into the memory pointed to by
- <tt>ptr</tt>. The string may contain embedded NULL bytes. The length of
- the string is implicitly determined in the underlying wrapper code.
- </p></div>
- <p>
- One use of these functions is packing and unpacking data from memory.
- Here is a short example:
- </p>
- <div class="code">
- <pre>
- // SWIG interface
- %module example
- %include "carrays.i"
- %include "cdata.i"
- %array_class(int, intArray);
- </pre>
- </div>
- <p>
- Python example:
- </p>
- <div class="targetlang">
- <pre>
- >>> 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
- >>>
- </pre>
- </div>
- <p>
- Since the size of data is not always known, the following macro is also defined:
- </p>
- <p>
- <b><tt>%cdata(type [,name=type])</tt></b>
- </p>
- <div class="indent">
- <p>
- Generates the following function for extracting C data for a given type.
- </p>
- <div class="code">
- <pre>
- char *cdata_<em>name</em>(type* ptr, int nitems)
- </pre>
- </div>
- <p>
- <tt>nitems</tt> is the number of items of the given type to extract.
- </p>
- </div>
- <p>
- <b>Note:</b> These functions provide direct access to memory and can be used to overwrite data.
- Clearly they are unsafe.
- </p>
- <H2><a name="Library_nn8"></a>8.3 C String Handling</H2>
- <p>
- A common problem when working with C programs is dealing with
- functions that manipulate raw character data using <tt>char *</tt>.
- In part, problems arise because there are different interpretations of
- <tt>char *</tt>---it could be a NULL-terminated string or it could
- point to binary data. Moreover, functions that manipulate raw strings
- may mutate data, perform implicit memory allocations, or utilize
- fixed-sized buffers.
- </p>
- <p>
- The problems (and perils) of using <tt>char *</tt> 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.
- </p>
- <H3><a name="Library_nn9"></a>8.3.1 Default string handling</H3>
- <p>
- Suppose you have a C function with this prototype:
- </p>
- <div class="code">
- <pre>
- char *foo(char *s);
- </pre>
- </div>
- <p>
- The default wrapping behavior for this function is to set <tt>s</tt>
- to a raw <tt>char *</tt> that refers to the internal string data in the
- target language. In other words, if you were using a language like Tcl,
- and you wrote this,
- </p>
- <div class="code">
- <pre>
- % foo Hello
- </pre>
- </div>
- <p>
- then <tt>s</tt> would point to the representation of "Hello" inside
- the Tcl interpreter. When returning a <tt>char *</tt>, SWIG assumes
- that it is a NULL-terminated string and makes a copy of it. This
- gives the target language its own copy of the result.
- </p>
- <p>
- There are obvious problems with the default behavior. First, since
- a <tt>char *</tt> argument points to data inside the target language, it is
- <b>NOT</b> 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.
- </p>
- <H3><a name="Library_nn10"></a>8.3.2 Passing binary data</H3>
- <p>
- If you have a function that expects binary data,
- </p>
- <div class="code">
- <pre>
- int parity(char *str, int len, int initial);
- </pre>
- </div>
- <p>
- you can wrap the parameters <tt>(char *str, int len)</tt> as a single
- argument using a typemap. Just do this:
- </p>
- <div class="code">
- <pre>
- %apply (char *STRING, int LENGTH) { (char *str, int len) };
- ...
- int parity(char *str, int len, int initial);
- </pre>
- </div>
- <p>
- Now, in the target language, you can use binary string data like this:
- </p>
- <div class="code">
- <pre>
- >>> s = "H\x00\x15eg\x09\x20"
- >>> parity(s,0)
- </pre>
- </div>
- <p>
- In the wrapper function, the passed string will be expanded to a pointer and length parameter.
- </p>
- <H3><a name="Library_nn11"></a>8.3.3 Using %newobject to release memory</H3>
- <p>
- If you have a function that allocates memory like this,
- </p>
- <div class="code">
- <pre>
- char *foo() {
- char *result = (char *) malloc(...);
- ...
- return result;
- }
- </pre>
- </div>
- <p>
- then the SWIG generated wrappers will have a memory leak--the returned data will be copied
- into a string object and the old contents ignored.
- </p>
- <p>
- To fix the memory leak, use the <tt>%newobject</tt> directive.
- </p>
- <div class="code">
- <pre>
- %newobject foo;
- ...
- char *foo();
- </pre>
- </div>
- <p>
- This will release the result.
- </p>
- <H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>
- <p>
- The <tt>cstring.i</tt> library file provides a collection of macros
- for dealing with functions that either mutate string arguments or
- which try to output string data through their arguments. An
- example of such a function might be this rather questionable
- implementation:
- </p>
- <div class="code">
- <pre>
- 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);
- ...
- }
- </pre>
- </div>
- <p>
- (Off topic rant: If your program really has functions like this, you
- would be well-advised to replace them with safer alternatives
- involving bounds checking).
- </p>
- <p>
- The macros defined in this module all expand to various combinations of
- typemaps. Therefore, the same pattern matching rules and ideas apply.
- </p>
- <p>
- <b>%cstring_bounded_output(parm, maxsize)</b>
- </p>
- <div class="indent">
- <p>
- Turns parameter <tt><em>parm</em></tt> into an output value. The
- output string is assumed to be NULL-terminated and smaller than
- <tt><em>maxsize</em></tt> characters. Here is an example:
- </p>
- <div class="code">
- <pre>
- %cstring_bounded_output(char *path, 1024);
- ...
- void get_path(char *path);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> get_path()
- /home/beazley/packages/Foo/Bar
- >>>
- </pre>
- </div>
- <p>
- 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). <b>If more than <tt><em>maxsize</em></tt>
- bytes are written, your program will crash with a buffer overflow!</b>
- </p>
- </div>
- <p>
- <b>%cstring_chunk_output(parm, chunksize)</b>
- </p>
- <div class="indent">
- <p>
- Turns parameter <tt><em>parm</em></tt> into an output value. The
- output string is always <tt><em>chunksize</em></tt> and may contain
- binary data. Here is an example:
- </p>
- <div class="code">
- <pre>
- %cstring_chunk_output(char *packet, PACKETSIZE);
- ...
- void get_packet(char *packet);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> get_packet()
- '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88'
- >>>
- </pre>
- </div>
- <p>
- This macro is essentially identical to <tt>%cstring_bounded_output</tt>. The
- only difference is that the result is always <tt><em>chunksize</em></tt> characters.
- Furthermore, the result can contain binary data.
- <b>If more than <tt><em>maxsize</em></tt>
- bytes are written, your program will crash with a buffer overflow!</b>
- </p>
- </div>
- <p>
- <b>%cstring_bounded_mutable(parm, maxsize)</b>
- </p>
- <div class="indent">
- <p>
- Turns parameter <tt><em>parm</em></tt> into a mutable string argument.
- The input string is assumed to be NULL-terminated and smaller than
- <tt><em>maxsize</em></tt> characters. The output string is also assumed
- to be NULL-terminated and less than <tt><em>maxsize</em></tt> characters.
- </p>
- <div class="code">
- <pre>
- %cstring_bounded_mutable(char *ustr, 1024);
- ...
- void make_upper(char *ustr);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> make_upper("hello world")
- 'HELLO WORLD'
- >>>
- </pre>
- </div>
- <p>
- Internally, this macro is almost exactly the same as
- <tt>%cstring_bounded_output</tt>. 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.
- <b>If more than <tt><em>maxsize</em></tt> bytes are
- written, your program will crash with a buffer overflow!</b>
- </p>
- </div>
- <p>
- <b>%cstring_mutable(parm [, expansion])</b>
- </p>
- <div class="indent">
- <p>
- Turns parameter <tt><em>parm</em></tt> into a mutable string argument.
- The input string is assumed to be NULL-terminated. An optional
- parameter <tt><em>expansion</em></tt> 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.
- </p>
- <div class="code">
- <pre>
- %cstring_mutable(char *ustr);
- ...
- void make_upper(char *ustr);
- %cstring_mutable(char *hstr, HEADER_SIZE);
- ...
- void attach_header(char *hstr);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> make_upper("hello world")
- 'HELLO WORLD'
- >>> attach_header("Hello world")
- 'header: Hello world'
- >>>
- </pre>
- </div>
- <p>
- This macro differs from <tt>%cstring_bounded_mutable()</tt> in that a
- buffer is dynamically allocated (on the heap using
- <tt>malloc/new</tt>). 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.
- <b>If the function expands the result by more than <tt><em>expansion</em></tt> extra
- bytes, then the program will crash with a buffer overflow!</b>
- </p>
- </div>
- <p>
- <b>%cstring_output_maxsize(parm, maxparm)</b>
- </p>
- <div class="indent">
- <p>
- This macro is used to handle bounded character output functions where
- both a <tt>char *</tt> 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.
- </p>
- <div class="code">
- <pre>
- %cstring_output_maxsize(char *path, int maxpath);
- ...
- void get_path(char *path, int maxpath);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> get_path(1024)
- '/home/beazley/Packages/Foo/Bar'
- >>>
- </pre>
- </div>
- <p>
- 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.
- </p>
- </div>
- <p>
- <b>%cstring_output_withsize(parm, maxparm)</b>
- </p>
- <div class="indent">
- <p>
- This macro is used to handle bounded character output functions where
- both a <tt>char *</tt> and a pointer <tt>int *</tt> are passed. Initially,
- the <tt>int *</tt> 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.
- </p>
- <div class="code">
- <pre>
- %cstring_output_withsize(char *data, int *maxdata);
- ...
- void get_data(char *data, int *maxdata);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> get_data(1024)
- 'x627388912'
- >>> get_data(1024)
- 'xyzzy'
- >>>
- </pre>
- </div>
- <p>
- This macro is a somewhat more powerful version of <tt>%cstring_output_chunk()</tt>. 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 <tt>maxparm</tt> argument.
- </p>
- </div>
- <p>
- <b>%cstring_output_allocate(parm, release)</b>
- </p>
- <div class="indent">
- <p>
- This macro is used to return strings that are allocated within the program and
- returned in a parameter of type <tt>char **</tt>. For example:
- </p>
- <div class="code">
- <pre>
- void foo(char **s) {
- *s = (char *) malloc(64);
- sprintf(*s, "Hello world\n");
- }
- </pre>
- </div>
- <p>
- The returned string is assumed to be NULL-terminated. <tt><em>release</em></tt>
- specifies how the allocated memory is to be released (if applicable). Here is an
- example:
- </p>
- <div class="code">
- <pre>
- %cstring_output_allocate(char **s, free(*$1));
- ...
- void foo(char **s);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> foo()
- 'Hello world\n'
- >>>
- </pre>
- </div>
- </div>
- <p>
- <b>%cstring_output_allocate_size(parm, szparm, release)</b>
- </p>
- <div class="indent">
- <p>
- This macro is used to return strings that are allocated within the program and
- returned in two parameters of type <tt>char **</tt> and <tt>int *</tt>. For example:
- </p>
- <div class="code">
- <pre>
- void foo(char **s, int *sz) {
- *s = (char *) malloc(64);
- *sz = 64;
- // Write some binary data
- ...
- }
- </pre>
- </div>
- <p>
- The returned string may contain binary data. <tt><em>release</em></tt>
- specifies how the allocated memory is to be released (if applicable). Here is an
- example:
- </p>
- <div class="code">
- <pre>
- %cstring_output_allocate_size(char **s, int *slen, free(*$1));
- ...
- void foo(char **s, int *slen);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- >>> foo()
- '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88'
- >>>
- </pre>
- </div>
- <p>
- 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:
- </p>
- <div class="code">
- <pre>
- char *get_data(int *len);
- </pre>
- </div>
- <p>
- You could wrap it with a function like this:
- </p>
- <div class="code">
- <pre>
- void my_get_data(char **result, int *len) {
- *result = get_data(len);
- }
- </pre>
- </div>
- </div>
- <p>
- <b>Comments:</b>
- </p>
- <ul>
- <li>Support for the <tt>cstring.i</tt> module depends on the target language. Not all
- SWIG modules currently support this library.
- </li>
- <li>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.
- </li>
- <li>If used in C++, this library uses <tt>new</tt> and <tt>delete []</tt> for memory
- allocation. If using ANSI C, the library uses <tt>malloc()</tt> and <tt>free()</tt>.
- </li>
- <li>Rather than manipulating <tt>char *</tt> directly, you might consider using a special string
- structure or class instead.
- </li>
- </ul>
- <H2><a name="Library_stl_cpp_library"></a>8.4 STL/C++ Library</H2>
- <p>
- The library modules in this section provide access to parts of the standard C++ library including the STL.
- SWIG support for the STL is an ongoing effort. Support is quite comprehensive for some language modules
- but some of the lesser used modules do not have quite as much library code written.
- </p>
- <p>
- The following table shows which C++ classes are supported and the equivalent SWIG interface library file for the C++ library.
- </p>
- <table BORDER summary="SWIG C++ library files">
- <tr VALIGN=TOP>
- <td><b>C++ class</b></td>
- <td><b>C++ Library file</b></td>
- <td><b>SWIG Interface library file</b></td>
- </tr>
- <tr> <td>std::deque</td> <td>deque</td> <td>std_deque.i</td> </tr>
- <tr> <td>std::list</td> <td>list</td> <td>std_list.i</td> </tr>
- <tr> <td>std::map</td> <td>map</td> <td>std_map.i</td> </tr>
- <tr> <td>std::pair</td> <td>utility</td> <td>std_pair.i</td> </tr>
- <tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr>
- <tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr>
- <tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
- </table>
- <p>
- The list is by no means complete; some language modules support a subset of the above and some support additional STL classes.
- Please look for the library files in the appropriate language library directory.
- </p>
- <H3><a name="Library_nn14"></a>8.4.1 std_string.i</H3>
- <p>
- The <tt>std_string.i</tt> library provides typemaps for converting C++ <tt>std::string</tt>
- objects to and from strings in the target scripting language. For example:
- </p>
- <div class="code">
- <pre>
- %module example
- %include "std_string.i"
- std::string foo();
- void bar(const std::string &x);
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- x = foo(); # Returns a string object
- bar("Hello World"); # Pass string as std::string
- </pre>
- </div>
- <p>
- A common problem that people encounter is that of classes/structures
- containing a <tt>std::string</tt>. This can be overcome by defining a typemap.
- For example:
- </p>
- <div class="code">
- <pre>
- %module example
- %include "std_string.i"
- %apply const std::string& {std::string* foo};
- struct my_struct
- {
- std::string foo;
- };
- </pre>
- </div>
- <p>
- In the target language:
- </p>
- <div class="targetlang">
- <pre>
- x = my_struct();
- x.foo="Hello World"; # assign with string
- print x.foo; # print as string
- </pre>
- </div>
- <p>
- This module only supports types <tt>std::string</tt> and
- <tt>const std::string &</tt>. Pointers and non-const references
- are left unmodified and returned as SWIG pointers.
- </p>
- <p>
- This library file is fully aware of C++ namespaces. If you export <tt>std::string</tt> or rename
- it with a typedef, make sure you include those declarations in your interface. For example:
- </p>
- <div class="code">
- <pre>
- %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
- </pre>
- </div>
- <p>
- <b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms.
- We're looking into it.
- </p>
- <H3><a name="Library_nn15"></a>8.4.2 std_vector.i</H3>
- <p>
- The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL.
- Using this library involves the use of the <tt>%template</tt> directive. All you need to do is to
- instantiate different versions of <tt>vector</tt> for the types that you want to use. For example:
- </p>
- <div class="code">
- <pre>
- %module example
- %include "std_vector.i"
- namespace std {
- %template(vectori) vector<int>;
- %template(vectord) vector<double>;
- };
- </pre>
- </div>
- <p>
- When a template <tt>vector<X></tt> is instantiated a number of things happen:
- </p>
- <ul>
- <li>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.
- </li>
- <li>Input typemaps are defined for <tt>vector<X></tt>, <tt>const vector<X> &</tt>, and
- <tt>const vector<X> *</tt>. For each of these, a pointer <tt>vector<X> *</tt> may be passed or
- a native list object in the target language.
- </li>
- <li>An output typemap is defined for <tt>vector<X></tt>. In this case, the values in the
- vector are expanded into a list object in the target language.
- </li>
- <li>For all other variations of the type, the wrappers expect to receive a <tt>vector<X> *</tt>
- object in the usual manner.
- </li>
- <li>An exception handler for <tt>std::out_of_range</tt> is defined.
- </li>
- <li>Optionally, special methods for indexing, item retrieval, slicing, and element assignment
- may be defined. This depends on the target language.
- </li>
- </ul>
- <p>
- To illustrate the use of this library, consider the following functions:
- </p>
- <div class="code">
- <pre>
- /* 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));
- }
- </pre>
- </div>
- <p>
- To wrap with SWIG, you might write the following:
- </p>
- <div class="code">
- <pre>
- %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"
- </pre>
- </div>
- <p>
- Now, to illustrate the behavior in the scripting interpreter, consider this Python example:
- </p>
- <div class="targetlang">
- <pre>
- >>> 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
- >>>
- </pre>
- </div>
- <p>
- This library module is fully aware of C++ namespaces. If you use vectors with other names,
- make sure you include the appropriate <tt>using</tt> or typedef directives. For example:
- </p>
- <div class="code">
- <pre>
- %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);
- </pre>
- </div>
- <p>
- <b>Note:</b> This module makes use of several advanced SWIG features including templatized typemaps
- and template partial specialization. If you are trying to wrap other C++ code with templates, you
- might look at the code contained in <tt>std_vector.i</tt>. Alternatively, you can show them the code
- if you want to make their head explode.
- </p>
- <p>
- <b>Note:</b> This module is defined for all SWIG target languages. However argument conversion
- details and the public API exposed to the interpreter vary.
- </p>
- <p>
- <b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio.
- </p>
- <H3><a name="Library_stl_exceptions"></a>8.4.3 STL exceptions</H3>
- <p>
- Many of the STL wrapper functions add parameter checking and will throw a language dependent error/exception
- should the values not be valid. The classic example is array bounds checking.
- The library wrappers are written to throw a C++ exception in the case of error.
- The C++ exception in turn gets converted into an appropriate error/exception for the target language.
- By and large this handling should not need customising, however, customisation can easily be achieved by supplying appropriate "throws" typemaps.
- For example:
- </p>
- <div class="code">
- <pre>
- %module example
- %include "std_vector.i"
- %typemap(throws) std::out_of_range {
- // custom exception handler
- }
- %template(VectInt) std::vector<int>;
- </pre>
- </div>
- <p>
- The custom exception handler might, for example, log the exception then convert it into a specific error/exception for the target language.
- </p>
- <p>
- When using the STL it is advisable to add in an exception handler to catch all STL exceptions.
- The <tt>%exception</tt> directive can be used by placing the following code before any other methods or libraries to be wrapped:
- </p>
- <div class="code">
- <pre>
- %include "exception.i"
- %exception {
- try {
- $action
- } catch (const std::exception& e) {
- SWIG_exception(SWIG_RuntimeError, e.what());
- }
- }
- </pre>
- </div>
- <p>
- Any thrown STL exceptions will then be gracefully handled instead of causing a crash.
- </p>
- <H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2>
- <H3><a name="Library_nn17"></a>8.5.1 exception.i</H3>
- <p>
- The <tt>exception.i</tt> library provides a language-independent function for raising a run-time
- exception in the target language. This library is largely used by the SWIG library writers.
- If possible, use the error handling scheme available to your target language as there is greater
- flexibility in what errors/exceptions can be thrown.
- </p>
- <p>
- <b><tt>SWIG_exception(int code, const char *message)</tt></b>
- </p>
- <div class="indent">
- <p>
- Raises an exception in the target language. <tt>code</tt> is one of the following symbolic
- constants:
- </p>
- <div class="code">
- <pre>
- SWIG_MemoryError
- SWIG_IOError
- SWIG_RuntimeError
- SWIG_IndexError
- SWIG_TypeError
- SWIG_DivisionByZero
- SWIG_OverflowError
- SWIG_SyntaxError
- SWIG_ValueError
- SWIG_SystemError
- </pre>
- </div>
- <p>
- <tt>message</tt> is a string indicating more information about the problem.
- </p>
- </div>
- <p>
- The primary use of this module is in writing language-independent exception handlers.
- For example:
- </p>
- <div class="code">
- <pre>
- %include "exception.i"
- %exception std::vector::getitem {
- try {
- $action
- } catch (std::out_of_range& e) {
- SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
- }
- }
- </pre>
- </div>
- </body>
- </html>