mirror of https://github.com/swig/swig
2748 lines
71 KiB
HTML
2748 lines
71 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>SWIG Library</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<H1><a name="Library">12 SWIG library</a></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_argcargv">argcargv.i</a>
|
|
<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 a string with length</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_c_standard_library">C standard library</a>
|
|
<ul>
|
|
<li><a href="#Library_complex">Complex floating types</a>
|
|
</ul>
|
|
<li><a href="#Library_stl_cpp_library">STL/C++ library</a>
|
|
<ul>
|
|
<li><a href="#Library_std_string">std::string</a>
|
|
<li><a href="#Library_std_string_view">std::string_view</a>
|
|
<li><a href="#Library_std_vector">std::vector</a>
|
|
<li><a href="#Library_stl_exceptions">STL exceptions</a>
|
|
<li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
|
|
<ul>
|
|
<li><a href="#Library_shared_ptr_basics">shared_ptr basics</a>
|
|
<li><a href="#Library_shared_ptr_inheritance">shared_ptr and inheritance</a>
|
|
<li><a href="#Library_shared_ptr_overloading">shared_ptr and method overloading</a>
|
|
<li><a href="#Library_shared_ptr_templates">shared_ptr and templates</a>
|
|
<li><a href="#Library_shared_ptr_directors">shared_ptr and directors</a>
|
|
</ul>
|
|
<li><a href="#Library_std_unique_ptr">unique_ptr smart pointer</a>
|
|
<ul>
|
|
<li><a href="#Library_std_unique_ptr_by_value">unique_ptr passed by value</a>
|
|
<li><a href="#Library_std_unique_ptr_by_ref">unique_ptr passed by reference</a>
|
|
</ul>
|
|
<li><a href="#Library_std_auto_ptr">auto_ptr smart pointer</a>
|
|
</ul>
|
|
<li><a href="#Library_nn16">Utility Libraries</a>
|
|
<ul>
|
|
<li><a href="#Library_nn17">exception.i</a>
|
|
<li><a href="#Library_attributes">attribute.i</a>
|
|
<ul>
|
|
<li><a href="#Library_attribute_templates">%attribute and C++ templates</a>
|
|
</ul>
|
|
</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">12.1 The %include directive and library search path</a></H2>
|
|
|
|
|
|
<p>
|
|
Library files are included using the <tt>%include</tt> directive.
|
|
When searching for files, directories are searched in the following order:
|
|
</p>
|
|
|
|
<ol>
|
|
<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.
|
|
</ol>
|
|
|
|
<p>
|
|
Within directories mentioned in points 3-5, 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">12.2 C arrays and pointers</a></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_argcargv">12.2.1 argcargv.i</a></H3>
|
|
|
|
|
|
<p>
|
|
The argcargv.i library is a simple library providing multi-argument typemaps for handling C
|
|
argc argv command line argument C string arrays.
|
|
The <tt>argc</tt> parameter contains the argument count and <tt>argv</tt> contains the argument vector array.
|
|
</p>
|
|
|
|
<p>
|
|
This library provides the following multi-argument typemap:
|
|
</p>
|
|
|
|
<p>
|
|
<b><tt>(int ARGC, char **ARGV)</tt></b>
|
|
</p>
|
|
|
|
<p>
|
|
Apply this multi-argument typemap to your use case, for example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%apply (int ARGC, char **ARGV) { (size_t argc, const char **argv) }
|
|
|
|
int mainApp(size_t argc, const char **argv);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
then from Ruby:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
$args = ["myarg1", "myarg2"]
|
|
mainApp(args);
|
|
</pre>
|
|
</div>
|
|
|
|
|
|
<H3><a name="Library_nn4">12.2.2 cpointer.i</a></H3>
|
|
|
|
|
|
<p>
|
|
The <tt>cpointer.i</tt> module defines macros that can be 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">12.2.3 carrays.i</a></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(size_t 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, size_t index)</tt>
|
|
</p>
|
|
|
|
<div class="indent"><p>
|
|
Returns the value <tt>ary[index]</tt>.
|
|
</p></div>
|
|
|
|
<p>
|
|
<tt>void name_setitem(type *ary, size_t 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="targetlang">
|
|
<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(size_t nelements); // Create an array
|
|
~name(); // Delete array
|
|
type getitem(size_t index); // Return item
|
|
void setitem(size_t 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="targetlang">
|
|
<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>.
|
|
SWIG's default handling of these types is to handle them as character strings and the two macros do not do enough to change this.
|
|
</p>
|
|
|
|
<H3><a name="Library_nn6">12.2.4 cmalloc.i</a></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">12.2.5 cdata.i</a></H3>
|
|
|
|
|
|
<p>
|
|
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from a target language type.
|
|
The target language type is either:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> A string for the scripting languages. The scripting language must support strings with embedded binary data in order for this to work.</li>
|
|
<li> A byte array for the statically typed languages; namely, <tt>byte[]</tt> for C# and Java, <tt>ubyte[]</tt> for D, <tt>[]byte</tt> for Go.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
The available APIs are:
|
|
</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 the target language type. <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>
|
|
This is actually a wrapper of the standard C library <tt>memmove</tt> function,
|
|
<b><tt>void *memmove(void *ptr, const void *src, size_t n)</tt></b>,
|
|
which copies <tt>n</tt> bytes of data from <tt>src</tt> into the destination pointed to by <tt>ptr</tt>.
|
|
Multi-argument typemaps are used so that the last two parameters, <tt>src</tt> and <tt>n</tt> are replaced by
|
|
<tt>s</tt>, a string or byte array target language type, mentioned earlier.
|
|
The string/byte array may contain embedded NULL bytes.
|
|
Unlike the C library function nothing is returned by the wrapper function.
|
|
</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">12.3 C string handling</a></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">12.3.1 Default string handling</a></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="targetlang">
|
|
<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">12.3.2 Passing a string with length</a></H3>
|
|
|
|
|
|
<p>
|
|
If you have a function that expects string with a length,
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
size_t parity(char *str, size_t len, size_t initial);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
you can wrap the parameters <tt>(char *str, size_t len)</tt> as a single
|
|
argument using a typemap. Just do this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%apply (char *STRING, size_t LENGTH) { (char *str, size_t len) };
|
|
...
|
|
size_t parity(char *str, size_t len, size_t initial);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Now, in the target language, you can use the string like this:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<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.
|
|
The <tt>(char *STRING, int LENGTH)</tt> multi-argument typemap is also available in addition to <tt>(char *STRING, size_t LENGTH)</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG also supports passing these parameters but in reverse order, for example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%apply (size_t LENGTH, char *STRING) { (size_t len, char *str) };
|
|
...
|
|
size_t parity(size_t len, char *str, size_t initial);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The usage from target language will be identical.
|
|
In the wrapper function, the supplied string will be expanded to a length parameter and pointer.
|
|
</p>
|
|
|
|
<H3><a name="Library_nn11">12.3.3 Using %newobject to release memory</a></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 if the appropriate target language support is available.
|
|
SWIG provides the appropriate "newfree" typemap for <tt>char *</tt> so that the memory is released,
|
|
however, you may need to provide your own "newfree" typemap for other types.
|
|
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details.
|
|
</p>
|
|
|
|
<H3><a name="Library_nn12">12.3.4 cstring.i</a></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 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_c_standard_library">12.4 C standard library</a></H2>
|
|
|
|
|
|
<H3><a name="Library_complex">12.4.1 Complex floating types</a></H3>
|
|
|
|
|
|
<p>
|
|
SWIG has some support for complex floating types. By default the keyword
|
|
<tt>_Complex</tt> is understood by the parser but <tt>complex</tt> is not
|
|
treated as a keyword because it may be used as an identifier.
|
|
</p>
|
|
|
|
<p>
|
|
SWIG is only able to fully wrap complex floating types for some target
|
|
languages. If you are using such a target language for complex floating types,
|
|
you should include <tt>complex.i</tt> to enable this support:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include "complex.i"
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If SWIG is in C++ code this will actually include <tt>std_complex.i</tt>
|
|
for you; otherwise it will include <tt>ccomplex.i</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
For target languages without support this will fail to find a file to
|
|
include. In this case, if you are wrapping headers which use <tt>complex</tt>
|
|
then you'll need to add a define to your SWIG interface file to get SWIG to
|
|
parse the headers:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
#define complex _Complex
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Then if wrapping as opaque types is not useful to you, you can use
|
|
<a href="SWIG.html#SWIG_ignore"><tt>%ignore</tt></a> to tell SWIG not to wrap
|
|
the functions and/or variables which use complex floating types.
|
|
</p>
|
|
|
|
<H2><a name="Library_stl_cpp_library">12.5 STL/C++ library</a></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::array (C++11)</td> <td>array</td> <td>std_array.i</td> </tr>
|
|
<tr> <td>std::auto_ptr</td> <td>memory</td> <td>std_auto_ptr.i</td> </tr>
|
|
<tr> <td>std::complex</td> <td>complex</td> <td>std_complex.i</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::multimap (C++11)</td> <td>multimap</td> <td>std_multimap.i</td> </tr>
|
|
<tr> <td>std::multiset (C++11)</td> <td>multiset</td> <td>std_multiset.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::shared_ptr (C++11)</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
|
|
<tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr>
|
|
<tr> <td>std::string_view (C++17)</td> <td>string_view</td> <td>std_string_view.i</td> </tr>
|
|
<tr> <td>std::unordered_map (C++11)</td> <td>unordered_map</td> <td>std_unordered_map.i</td> </tr>
|
|
<tr> <td>std::unordered_multimap (C++11)</td> <td>unordered_multimap</td> <td>std_unordered_multimap.i</td> </tr>
|
|
<tr> <td>std::unordered_multiset (C++11)</td> <td>unordered_multiset</td> <td>std_unordered_multiset.i</td> </tr>
|
|
<tr> <td>std::unordered_set (C++11)</td> <td>unordered_set</td> <td>std_unordered_set.i</td> </tr>
|
|
<tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
|
|
<tr> <td>std::wstring</td> <td>wstring</td> <td>std_wstring.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_std_string">12.5.1 std::string</a></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>
|
|
|
|
<H3><a name="Library_std_string_view">12.5.2 std::string_view</a></H3>
|
|
|
|
|
|
<p>
|
|
The <tt>std_string_view.i</tt> library provides typemaps for converting C++17 <tt>std::string_view</tt>
|
|
objects to and from strings in the target scripting language. For example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%module example
|
|
%include "std_string_view.i"
|
|
|
|
std::string_view foo();
|
|
void bar(std::string_view 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_view
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
For target languages for which SWIG supports directors, <tt>directorout</tt>
|
|
typemaps are provided for <tt>std::string_view</tt>, but these require extra
|
|
care to use safely. The issue is that returning <tt>std::string_view</tt>
|
|
effectively returns a pointer to string data but doesn't own the pointed to
|
|
data. For target languages where there isn't a native narrow string
|
|
representation (e.g. C#, Java) a <tt>static std::string</tt> is used to cache
|
|
the data, which works but isn't thread/reentrant safe. For target languages
|
|
where there is a native narrow string representation SWIG will return a
|
|
<tt>std::string_view</tt> pointing to that data, so you need to store the
|
|
string to return somewhere which will persist for the lifetime the caller
|
|
needs (e.g. put it in a member variable) - you can't return a temporary target
|
|
language string. In both cases SWIG will issue a warning by default.
|
|
</p>
|
|
|
|
<H3><a name="Library_std_vector">12.5.3 std::vector</a></H3>
|
|
|
|
|
|
<p>
|
|
The <tt>std_vector.i</tt> library provides support for the C++ <tt>std::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) {
|
|
for (std::vector<double>::iterator it = v.begin(); it != v.end(); ++it)
|
|
*it /= 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>
|
|
|
|
<H3><a name="Library_stl_exceptions">12.5.4 STL exceptions</a></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>
|
|
|
|
<H3><a name="Library_std_shared_ptr">12.5.5 shared_ptr smart pointer</a></H3>
|
|
|
|
|
|
<H4><a name="Library_shared_ptr_basics">12.5.5.1 shared_ptr basics</a></H4>
|
|
|
|
|
|
<p>
|
|
Some target languages have support for handling the shared_ptr reference counted smart pointer.
|
|
This smart pointer is available in the standard C++11 library as <tt>std::shared_ptr</tt>.
|
|
It was also in TR1 as <tt>std::tr1::shared_ptr</tt> before it was fully standardized.
|
|
Support for the widely used <tt>boost::shared_ptr</tt> is also available.
|
|
</p>
|
|
|
|
<p>
|
|
In order to use <tt>std::shared_ptr</tt>, the <tt>std_shared_ptr.i</tt> library file should be included:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <std_shared_ptr.i>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The pre-standard <tt>std::tr1::shared_ptr</tt> can be used by including the following macro before including the <tt>std_shared_ptr.i</tt> library file:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
#define SWIG_SHARED_PTR_SUBNAMESPACE tr1
|
|
%include <std_shared_ptr.i>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
In order to use <tt>boost::shared_ptr</tt>, the <tt>boost_shared_ptr.i</tt> library file should be included:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <boost_shared_ptr.i>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
You can only use one of these variants of shared_ptr in your interface file at a time
|
|
(also SWIG doesn't currently support using both <tt>%shared_ptr(T)</tt> and
|
|
<tt>%unique_ptr<T></tt> on the same type <tt>T</tt>).
|
|
All three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
|
|
where <tt>T</tt> is the underlying pointer type equating to usage <tt>shared_ptr<T></tt>.
|
|
The type <tt>T</tt> must be non-primitive.
|
|
A simple example demonstrates usage:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%module example
|
|
%include <boost_shared_ptr.i>
|
|
%shared_ptr(IntValue)
|
|
|
|
%inline %{
|
|
#include <boost/shared_ptr.hpp>
|
|
|
|
struct IntValue {
|
|
int value;
|
|
IntValue(int v) : value(v) {}
|
|
};
|
|
|
|
static int extractValue(const IntValue &t) {
|
|
return t.value;
|
|
}
|
|
|
|
static int extractValueSmart(boost::shared_ptr<IntValue> t) {
|
|
return t->value;
|
|
}
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Note that the <tt>%shared_ptr(IntValue)</tt> declaration occurs after the inclusion of the <tt>boost_shared_ptr.i</tt>
|
|
library which provides the macro and, very importantly, before any usage or declaration of the type, <tt>IntValue</tt>.
|
|
The <tt>%shared_ptr</tt> macro provides, a few things for handling this smart pointer, but mostly a number of
|
|
typemaps. These typemaps override the default typemaps so that the underlying proxy class is stored and passed around
|
|
as a pointer to a <tt>shared_ptr</tt> instead of a plain pointer to the underlying type.
|
|
This approach means that any instantiation of the type can be passed to methods taking the type by value, reference, pointer
|
|
or as a smart pointer.
|
|
The interested reader might want to look at the generated code, however, usage is simple and no different
|
|
handling is required from the target language.
|
|
For example, a simple use case of the above code from Java would be:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
IntValue iv = new IntValue(1234);
|
|
int val1 = example.extractValue(iv);
|
|
int val2 = example.extractValueSmart(iv);
|
|
System.out.println(val1 + " " + val2);
|
|
</pre>
|
|
</div>
|
|
|
|
<H4><a name="Library_shared_ptr_inheritance">12.5.5.2 shared_ptr and inheritance</a></H4>
|
|
|
|
|
|
<p>
|
|
The shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
|
|
<a href="SWIGPlus.html#SWIGPlus_smart_pointers">smart pointer handling</a>.
|
|
The shared_ptr library does not generate extra wrappers, just for smart pointer handling, in addition to the proxy class.
|
|
The normal proxy class including inheritance relationships is generated as usual.
|
|
The only real change introduced by the <tt>%shared_ptr</tt> macro is that the proxy class stores a pointer to the shared_ptr instance instead of a raw pointer to the instance.
|
|
A proxy class derived from a base which is being wrapped with shared_ptr can and <b>must</b> be wrapped as a shared_ptr too.
|
|
In other words all classes in an inheritance hierarchy must all be used with the <tt>%shared_ptr</tt> macro.
|
|
For example the following code can be used with the base class shown earlier:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%shared_ptr(DerivedIntValue)
|
|
%inline %{
|
|
struct DerivedIntValue : IntValue {
|
|
DerivedIntValue(int value) : IntValue(value) {}
|
|
...
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
A shared_ptr of the derived class can now be passed to a method where the base is expected in the target language, just as it can in C++:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
DerivedIntValue div = new DerivedIntValue(5678);
|
|
int val3 = example.extractValue(div);
|
|
int val4 = example.extractValueSmart(div);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If the <tt>%shared_ptr</tt> macro is omitted for any class in the inheritance hierarchy, SWIG will warn about this and the generated code may or may not result in a C++ compilation error.
|
|
For example, the following input:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include "boost_shared_ptr.i"
|
|
%shared_ptr(Parent);
|
|
|
|
%inline %{
|
|
#include <boost/shared_ptr.hpp>
|
|
struct GrandParent {
|
|
virtual ~GrandParent() {}
|
|
};
|
|
|
|
struct Parent : GrandParent {
|
|
virtual ~Parent() {}
|
|
};
|
|
|
|
struct Child : Parent {
|
|
virtual ~Child() {}
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
warns about the missing smart pointer information:
|
|
</p>
|
|
|
|
<div class="shell">
|
|
<pre>
|
|
example.i:12: Warning 520: Base class 'GrandParent' of 'Parent' is not similarly marked as a smart pointer.
|
|
example.i:16: Warning 520: Derived class 'Child' of 'Parent' is not similarly marked as a smart pointer.
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Adding the missing <tt>%shared_ptr</tt> macros will fix this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <boost_shared_ptr.i>
|
|
%shared_ptr(GrandParent);
|
|
%shared_ptr(Parent);
|
|
%shared_ptr(Child);
|
|
|
|
... as before ...
|
|
</pre>
|
|
</div>
|
|
|
|
<H4><a name="Library_shared_ptr_overloading">12.5.5.3 shared_ptr and method overloading</a></H4>
|
|
|
|
|
|
<p>
|
|
A C++ compiler can disambiguate a method overloaded by a shared_ptr and one using the raw underlying type.
|
|
For example, either one of these methods can be called in C++:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
int age(std::shared_ptr<GrandParent> num);
|
|
int age(GrandParent& num);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When wrapped by SWIG, disambiguation is not possible using the overloaded names as there is just one equivalent type (<tt>GrandParent</tt>) in the target language.
|
|
SWIG will choose to wrap just the first method by default.
|
|
<a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in overloading</a> discusses ways to control which method(s) gets wrapped using <tt>%ignore</tt> or <tt>%rename</tt>.
|
|
For the interested reader, SWIG detects that they are equivalent types via the <a href=Typemaps.html#Typemaps_typecheck_pointer>typecheck typemaps</a> in the shared_ptr library.
|
|
</p>
|
|
|
|
<H4><a name="Library_shared_ptr_templates">12.5.5.4 shared_ptr and templates</a></H4>
|
|
|
|
|
|
<p>
|
|
The <tt>%shared_ptr</tt> macro should be used for all the required instantiations
|
|
of the template before each of the <tt>%template</tt> instantiations.
|
|
For example, consider <tt>number.h</tt> containing the following illustrative template:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
#include <memory>
|
|
|
|
template<int N> struct Number {
|
|
int num;
|
|
Number() : num(N) {}
|
|
static std::shared_ptr<Number<N>> make() { return std::make_shared<Number<N>>(); }
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The SWIG code below shows the required ordering:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <std_shared_ptr.i>
|
|
|
|
%shared_ptr(Number<10>);
|
|
%shared_ptr(Number<42>);
|
|
|
|
%{
|
|
#include "number.h"
|
|
%}
|
|
%include "number.h"
|
|
|
|
%template(Number10) Number<10>;
|
|
%template(Number42) Number<42>;
|
|
</pre>
|
|
</div>
|
|
|
|
<H4><a name="Library_shared_ptr_directors">12.5.5.5 shared_ptr and directors</a></H4>
|
|
|
|
|
|
<p>
|
|
The languages that support shared_ptr also have support for using shared_ptr with directors.
|
|
</p>
|
|
|
|
<H3><a name="Library_std_unique_ptr">12.5.6 unique_ptr smart pointer</a></H3>
|
|
|
|
|
|
<p>
|
|
The <tt>std_unique_ptr.i</tt> library file provides SWIG's unique_ptr support.
|
|
It provides move semantics for the smart pointer's underlying object,
|
|
both from C++ to the target language and vice versa.
|
|
</p>
|
|
|
|
<p>
|
|
The library defines typemaps and a macro, <tt>%unique_ptr(T)</tt>, to use for handling
|
|
<tt>std::unique_ptr<T></tt> for a type <tt>T</tt>.
|
|
The type <tt>T</tt> must be non-primitive.
|
|
This macro should be used before any code declaring or using type <tt>T</tt>.
|
|
Ordering requirements for using this smart pointer macro are the same as the
|
|
equivalent <tt>%shared_ptr(T)</tt> macro covered in the previous section.
|
|
The ownership and move semantics described here can of course be modified if not suitable
|
|
by copying and customising the typemaps in the appropriate <tt>std_unique_ptr.i</tt> library file.
|
|
</p>
|
|
|
|
<p>
|
|
Note that SWIG doesn't currently support using both <tt>%shared_ptr(T)</tt> and
|
|
<tt>%unique_ptr<T></tt> on the same type <tt>T</tt>.
|
|
</p>
|
|
|
|
<H4><a name="Library_std_unique_ptr_by_value">12.5.6.1 unique_ptr passed by value</a></H4>
|
|
|
|
|
|
<p>
|
|
Example usage of a <tt>std::unique_ptr</tt> being returned from a function by value is shown below.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <std_unique_ptr.i>
|
|
|
|
%unique_ptr(Klass)
|
|
%inline %{
|
|
#include <memory>
|
|
class Klass {
|
|
public:
|
|
// Factory function creating objects of this class:
|
|
static std::unique_ptr<Klass> Create(int value) {
|
|
return std::unique_ptr<Klass>(new Klass(value));
|
|
}
|
|
|
|
int getValue() const { return m_value; }
|
|
|
|
private:
|
|
Klass(int value) : m_value(value) {}
|
|
int m_value;
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The returned objects can be used naturally from the target language, e.g. from
|
|
C#:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
Klass k = Klass.Create(17);
|
|
int value = k.getValue();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The implementation simply calls <tt>std::unique_ptr::release()</tt> to obtain
|
|
the underlying raw pointer. The pointer is then used to create a target language
|
|
proxy class in the same way that SWIG handles a C++ function returning a class by value.
|
|
The target language proxy class then owns the memory pointed to by the raw pointer
|
|
and memory handling is identical to normal SWIG proxy class handling of the underlying C++ memory.
|
|
Note that an object returned by value is first copied/moved from the stack onto the heap in order to obtain
|
|
a raw pointer on the heap, whereas the underlying raw pointer in <tt>std::unique_ptr</tt> already points to an object on the heap.
|
|
</p>
|
|
|
|
<p>
|
|
Note that the implementation is quite different to the <tt>std::shared_ptr</tt> smart pointer,
|
|
where the proxy class manages the underlying C++ memory as a pointer to a shared_ptr instead of a plain raw pointer.
|
|
</p>
|
|
|
|
<p>
|
|
A possibly less common usage of this smart pointer is as a parameter to a function.
|
|
When used like this it indicates that memory usage of the object pointed to by the underlying pointer
|
|
is transferred to the function being called.
|
|
The code that SWIG generates assumes this happens.
|
|
First, it is assumed that a proxy class already owns the underlying C++ object and is used to pass the object to the C++ function being called.
|
|
Second, the ownership is transferred from the proxy class to the C++ function being called and
|
|
lifetime is then controlled by the function.
|
|
Finally, it is assumed the lifetime of the object may not last beyond returning from the C++ function
|
|
and hence the proxy class can no longer be used.
|
|
</p>
|
|
|
|
<p>
|
|
Consider expanding the example above with a function that takes a <tt>std::unique_ptr</tt> as follows:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void take(std::unique_ptr<Klass>);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
and use from C#:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
Klass k = Klass.Create(17); // create an instance of Klass any way you like
|
|
int value = k.getValue(); // ok
|
|
example.take(k); // memory ownership passes from C# layer to C++ layer
|
|
int v = k.getValue(); // don't do this - invalid use of k
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Attempts to use <tt>k</tt> after the ownership has been passed into the <tt>take</tt> function
|
|
should not be attempted.
|
|
The implementation sets the proxy class to an invalid state by setting the class's underlying
|
|
C++ pointer to null after the return from the <tt>take</tt> function.
|
|
Subsequent use of an invalid proxy class instance is very much dependent on the implementation
|
|
in the target language and ranges from a segfault to giving a nice error.
|
|
Consider implementing additional checks via the 'check' typemap.
|
|
</p>
|
|
|
|
<p>
|
|
Attempts to pass ownership from a proxy class to a <tt>std::unique</tt> parameter more than once will result
|
|
in a "Cannot release ownership as memory is not owned" exception. For example, if <tt>example.take(k)</tt> in the example above is called twice.
|
|
</p>
|
|
|
|
<H4><a name="Library_std_unique_ptr_by_ref">12.5.6.2 unique_ptr passed by reference</a></H4>
|
|
|
|
|
|
<p>
|
|
The effect of passing a <tt>std::unique_ptr</tt> by rvalue reference into a function is identical to passing it by value.
|
|
The ownership of the memory of the object being pointed to by the underyling pointer is transferred from the proxy class to the C++ function being called. Example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void grab(std::unique_ptr<Klass> &&);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Passing non-const lvalue references into a function is a bit quirky and not perfect due to ambiguities as
|
|
to what the function may do.
|
|
The approach taken is the ownership is transferred out of the target language from the proxy class
|
|
into C++ space and the proxy class can then no longer be used after the wrapped function returns.
|
|
In summary it works much like passing a <tt>std::unique_ptr</tt> by value into a function.
|
|
The assumption is the function will not modify the <tt>std::unique_ptr</tt>.
|
|
If this is not true and the underlying pointer is changed, such as calling the member functions, <tt>swap</tt>, <tt>reset</tt> or <tt>release</tt>, then the modified <tt>std::unique_ptr</tt> will effectively be ignored.
|
|
It is destroyed when the function exits C++ space on return to the target language.
|
|
Example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void process(std::unique_ptr<Klass> &);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Passing const lvalue references into a function works much like passing any wrapped class.
|
|
The proxy class owning the underling C++ object continues to own the underying C++ object
|
|
after calling the function, the function cannot modify the <tt>std::unique_ptr</tt> or take ownership.
|
|
Example:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
void use(const std::unique_ptr<Klass> &);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Move semantics are not provided when wrapping a C++ function that returns a <tt>std::unique_ptr</tt> by reference.
|
|
The target language proxy class wrapper that is returned does not own the underlying C++ object.
|
|
This applies to all reference types, such as:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
std::unique_ptr<Klass> & LvalueRefReturn();
|
|
std::unique_ptr<Klass> && RvalueRefReturn();
|
|
</pre>
|
|
</div>
|
|
|
|
|
|
<p>
|
|
<b>Compatibility note:</b> Support for <tt>std::unique_ptr</tt> was first added in SWIG-4.1.0.
|
|
This initial support contained the move semantics when passing a <tt>std::unique_ptr</tt> around by value. Support for passing a <tt>std::unique_ptr</tt> around by reference was added in SWIG-4.3.0.
|
|
</p>
|
|
|
|
<H3><a name="Library_std_auto_ptr">12.5.7 auto_ptr smart pointer</a></H3>
|
|
|
|
|
|
<p>
|
|
While <tt>std::auto_ptr</tt> is deprecated in C++11, some existing code may
|
|
still be using it. SWIG provides support for this class which is nearly identical
|
|
to <tt>std::unique_ptr</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
The <tt>std_auto_ptr.i</tt> library file provides SWIG's auto_ptr support.
|
|
It defines typemaps and a macro, <tt>%auto_ptr(T)</tt>, to use for handling
|
|
<tt>std::auto_ptr<T></tt> for a type <tt>T</tt>.
|
|
The type <tt>T</tt> must be non-primitive.
|
|
This macro should be used before any code declaring or using type <tt>T</tt>.
|
|
Ordering requirements for using this smart pointer macro are the same as the
|
|
equivalent <tt>%shared_ptr(T)</tt> and <tt>%unique_ptr</tt> macros covered in
|
|
the previous two sections.
|
|
</p>
|
|
|
|
<p>
|
|
Example usage of a <tt>std::auto_ptr</tt> being returned from a function is shown below.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <std_auto_ptr.i>
|
|
|
|
%auto_ptr(Klass)
|
|
%inline %{
|
|
#include <memory>
|
|
class Klass {
|
|
public:
|
|
// Factory function creating objects of this class:
|
|
static std::auto_ptr<Klass> Create(int value) {
|
|
return std::auto_ptr<Klass>(new Klass(value));
|
|
}
|
|
|
|
int getValue() const { return m_value; }
|
|
|
|
private:
|
|
Klass(int value) : m_value(value) {}
|
|
int m_value;
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The returned objects can be used naturally from the target language, e.g. from
|
|
C#:
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
Klass k = Klass.Create(17);
|
|
int value = k.getValue();
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The implementation simply calls <tt>std::auto_ptr::release()</tt> to obtain the underlying raw pointer.
|
|
That is, it works the same way covered in the previous section for <tt>std::unique_ptr</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
Input parameters also work the same way as <tt>std::unique_ptr</tt> covered in the previous section.
|
|
</p>
|
|
|
|
<H2><a name="Library_nn16">12.6 Utility Libraries</a></H2>
|
|
|
|
|
|
<H3><a name="Library_nn17">12.6.1 exception.i</a></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
|
|
SWIG_NullReferenceError
|
|
</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>
|
|
|
|
|
|
<H3><a name="Library_attributes">12.6.2 attribute.i</a></H3>
|
|
|
|
|
|
<p>
|
|
The attribute library contains a set of macros to convert a pair of set/get methods
|
|
into a "native" attribute/property.
|
|
</p>
|
|
|
|
<p>
|
|
Use <tt>%attribute</tt> when you have a pair of get/set methods to a
|
|
primitive type like:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include "attribute.i"
|
|
%attribute(A, int, a, get_a, set_a);
|
|
|
|
struct A {
|
|
int get_a() const;
|
|
void set_a(int aa);
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
and you want to provide that variable as an attribute in the target
|
|
language. This example only works for primitive types, not derived
|
|
types.
|
|
Now you can use the attributes like so (in Python):
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
x = A()
|
|
x.a = 3 # calls A::set_a(3)
|
|
print(x.a) # calls A::get_a() const
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
If you don't provide a 'set' method, a 'read-only' attribute
|
|
is generated, ie, like:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%attribute(A, int, c, get_c);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Use <tt>%attributeref</tt> when you have const/non-const reference
|
|
access methods for primitive types or class/structs, like:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%attributeref(A, int, b);
|
|
|
|
struct A {
|
|
const int & b() const;
|
|
int & b();
|
|
};
|
|
|
|
%attributeref(B, int, c);
|
|
|
|
struct B {
|
|
int & c();
|
|
};
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Use the attributes like so (in Python):
|
|
</p>
|
|
|
|
<div class="targetlang">
|
|
<pre>
|
|
x = A()
|
|
x.b = 3 # calls A::b()
|
|
print(x.b) # calls A::b() const
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
You can also use
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
if the internal C++ reference methods have a different name from the
|
|
attribute you want, so
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%attributeref(B, int, d, c);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
is the same as the last example, but instead of the attribute 'c' being
|
|
called 'c', it is called 'd'.
|
|
</p>
|
|
|
|
<p>
|
|
Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> to indicate
|
|
that reference-pointer translation is required.
|
|
Use <tt>%attribute2</tt> instead of <tt>%attribute</tt> in cases like
|
|
this:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
|
|
%inline %{
|
|
struct MyFoo {
|
|
int x;
|
|
};
|
|
class MyClass {
|
|
MyFoo foo;
|
|
public:
|
|
MyFoo & GetFoo() { return foo; }
|
|
void SetFoo(const MyFoo &other) { foo = other; }
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Here, the data type of the property is a wrapped type <tt>MyFoo</tt> and on
|
|
the C++ side it is passed by reference. The problem is that the SWIG
|
|
wrapper will pass around a pointer (MyFoo *) which is not compatible
|
|
with the reference type of the accessors (MyFoo &). Therefore, if you
|
|
use <tt>%attribute</tt>, you'll get an error from your C/C++
|
|
compiler. <tt>%attribute2</tt> translates between a pointer and a
|
|
reference to eliminate the error. In case you're confused, let's make
|
|
it simple: just use <tt>%attribute</tt> at first, but if the C/C++
|
|
compiler gives an error while compiling the wrapper,
|
|
try <tt>%attribute2</tt> instead.
|
|
</p>
|
|
|
|
<p>
|
|
NOTE: remember that if the type contains commas, such as
|
|
<tt>std::pair<int, int></tt>, you need to use the macro like:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%attributeref(A, %arg(std::pair<int, int>), pval);
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
where <tt>%arg()</tt> 'normalizes' the type to be understood as a single
|
|
argument, otherwise the macro will get confused by the comma.
|
|
</p>
|
|
|
|
<p>
|
|
The <tt>%attributeval</tt> is the same as <tt>%attribute</tt>, but
|
|
should be used when the type is a class/struct (ie a non-primitive
|
|
type) and when the get and set methods return/pass by value. The
|
|
following is very similar to the above example, but note that the
|
|
access is by value rather than reference.
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
|
|
%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
|
|
%inline %{
|
|
class MyClassVal {
|
|
MyFoo foo;
|
|
public:
|
|
MyFoo GetFoo() { return foo; }
|
|
void SetFoo(MyFoo other) { foo = other; }
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The <tt>%attributestring</tt> is the same as <tt>%attributeval</tt>,
|
|
but should be used for string class types, which are unusual as they
|
|
are a class on the C++ side, but normally an immutable/primitive type
|
|
in the target language. Example usage for <tt>std::string</tt>:
|
|
</p>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
%include <std_string.i>
|
|
%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
|
|
%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
|
|
%inline %{
|
|
class MyStringyClass {
|
|
std::string str;
|
|
public:
|
|
MyStringyClass(const std::string &val) : str(val) {}
|
|
std::string GetString() { return str; }
|
|
void SetString(std::string other) { str = other; }
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The <tt>%attributestring</tt> also works for class types that
|
|
have <tt>%naturalvar</tt> turned on and so is also useful for
|
|
shared_ptr which has <tt>%naturalvar</tt> turned on in
|
|
<tt>%shared_ptr</tt>.
|
|
</p>
|
|
|
|
<H4><a name="Library_attribute_templates">12.6.2.1 %attribute and C++ templates</a></H4>
|
|
|
|
|
|
<p>
|
|
<tt>%attribute</tt> and friends have to be used on fully specified classes. For example
|
|
</p>
|
|
<div class="code">
|
|
<pre>
|
|
%attributeref(A<int>, int, a);
|
|
%inline %{
|
|
template <class T> struct A {
|
|
T a() const;
|
|
void a(T &);
|
|
};
|
|
%}
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
Note the use of a template-id (i.e., <tt>A<int></tt> not <tt>A<T></tt> or just <tt>A</tt>).
|
|
This means that <tt>%attribute</tt> statements have to be repeated for any template-id that you want to use with <tt>%template</tt>.
|
|
</p>
|
|
</body>
|
|
</html>
|