Thousands of changes to correct incorrect HTML. HTML is now valid (transitional 4.01).
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@6074 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton
parent
7cb896a5f4
commit
aa4d1d907d
31 changed files with 6754 additions and 4801 deletions
|
|
@ -5,32 +5,32 @@
|
|||
</head>
|
||||
|
||||
<body bgcolor="#ffffff">
|
||||
<a name="n1"></a><H1>13 SWIG library</H1>
|
||||
<H1><a name="Library"></a>8 SWIG library</H1>
|
||||
<!-- INDEX -->
|
||||
<ul>
|
||||
<li><a href="#n2">The %include directive and library search path</a>
|
||||
<li><a href="#n3">C Arrays and Pointers</a>
|
||||
<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="#n4">cpointer.i</a>
|
||||
<li><a href="#n5">carrays.i</a>
|
||||
<li><a href="#n6">cmalloc.i</a>
|
||||
<li><a href="#n7">cdata.i</a>
|
||||
<li><a href="#Library_nn4">cpointer.i</a>
|
||||
<li><a href="#Library_nn5">carrays.i</a>
|
||||
<li><a href="#Library_nn6">cmalloc.i</a>
|
||||
<li><a href="#Library_nn7">cdata.i</a>
|
||||
</ul>
|
||||
<li><a href="#n8">C String Handling</a>
|
||||
<li><a href="#Library_nn8">C String Handling</a>
|
||||
<ul>
|
||||
<li><a href="#n9">Default string handling</a>
|
||||
<li><a href="#n10">Passing binary data</a>
|
||||
<li><a href="#n11">Using %newobject to release memory</a>
|
||||
<li><a href="#n12">cstring.i</a>
|
||||
<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="#n13">C++ Library</a>
|
||||
<li><a href="#Library_nn13">C++ Library</a>
|
||||
<ul>
|
||||
<li><a href="#n14">std_string.i</a>
|
||||
<li><a href="#n15">std_vector.i</a>
|
||||
<li><a href="#Library_nn14">std_string.i</a>
|
||||
<li><a href="#Library_nn15">std_vector.i</a>
|
||||
</ul>
|
||||
<li><a href="#n16">Utility Libraries</a>
|
||||
<li><a href="#Library_nn16">Utility Libraries</a>
|
||||
<ul>
|
||||
<li><a href="#n17">exception.i</a>
|
||||
<li><a href="#Library_nn17">exception.i</a>
|
||||
</ul>
|
||||
</ul>
|
||||
<!-- INDEX -->
|
||||
|
|
@ -49,14 +49,14 @@ 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>
|
||||
|
||||
<a name="n2"></a><H2>13.1 The %include directive and library search path</H2>
|
||||
<H2><a name="Library_nn2"></a>8.1 The %include directive and library search path</H2>
|
||||
|
||||
|
||||
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
|
||||
|
|
@ -64,16 +64,19 @@ When searching for files, directories are searched in the following order:
|
|||
<li><tt>/usr/local/lib/swig_lib</tt> (or wherever you installed SWIG)
|
||||
<li>On Windows, SWIG also looks for the library relative to the location of <tt>swig.exe</tt>.
|
||||
</ul>
|
||||
<p>
|
||||
|
||||
<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 override the location of the SWIG library by setting the
|
||||
<tt>SWIG_LIB</tt> environment variable.<p>
|
||||
<tt>SWIG_LIB</tt> environment variable.
|
||||
</p>
|
||||
|
||||
<a name="n3"></a><H2>13.2 C Arrays and Pointers</H2>
|
||||
<H2><a name="Library_nn3"></a>8.2 C Arrays and Pointers</H2>
|
||||
|
||||
|
||||
This section describes library modules for manipulating low-level C arrays and pointers.
|
||||
|
|
@ -83,7 +86,7 @@ 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.
|
||||
|
||||
<a name="n4"></a><H3>13.2.1 cpointer.i</H3>
|
||||
<H3><a name="Library_nn4"></a>8.2.1 cpointer.i</H3>
|
||||
|
||||
|
||||
The <tt>cpointer.i</tt> module defines macros that can be used to used
|
||||
|
|
@ -93,11 +96,15 @@ this module is in generating pointers to primitive datatypes such as
|
|||
|
||||
<p>
|
||||
<b><tt>%pointer_functions(type,name)</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Generates a collection of four functions for manipulating a pointer <tt>type *</tt>:
|
||||
|
||||
<p>
|
||||
<tt>type *new_name()</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
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.
|
||||
|
|
@ -105,6 +112,8 @@ object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used.
|
|||
|
||||
<p>
|
||||
<tt>type *copy_name(type value)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
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
|
||||
|
|
@ -113,18 +122,24 @@ object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used.
|
|||
|
||||
<p>
|
||||
<tt>type *delete_name(type *obj)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Deletes an object type <tt>type</tt>.
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
<tt>void name_assign(type *obj, type value)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Assigns <tt>*obj = value</tt>.
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
<tt>type name_value(type *obj)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Returns the value of <tt>*obj</tt>.
|
||||
</blockquote>
|
||||
|
|
@ -151,18 +166,19 @@ Now, in Python:
|
|||
|
||||
<blockquote>
|
||||
<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
|
||||
>>> 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
|
||||
>>> example.delete_intp(c) # Delete
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
<b><tt>%pointer_class(type,name)</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Wraps a pointer of <tt>type *</tt> inside a class-based interface. This
|
||||
interface is as follows:
|
||||
|
|
@ -190,10 +206,14 @@ the "class" may be transparently passed to any function that expects the pointe
|
|||
<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>
|
||||
|
||||
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -216,10 +236,10 @@ Now, in Python (using proxy classes)
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> import example
|
||||
>>> c = example.intp() # Create an "int" for storing result
|
||||
>>> example.add(3,4,c) # Call function
|
||||
>>> c.value() # Dereference
|
||||
>>> import example
|
||||
>>> c = example.intp() # Create an "int" for storing result
|
||||
>>> example.add(3,4,c) # Call function
|
||||
>>> c.value() # Dereference
|
||||
7
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
|
@ -228,9 +248,10 @@ Of the two macros, <tt>%pointer_class</tt> is probably the most convenient when
|
|||
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>
|
||||
<p>
|
||||
<b><tt>%pointer_cast(type1, type2, name)</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Creates a casting function that converts <tt>type1</tt> to <tt>type2</tt>. The name of the function is <tt>name</tt>.
|
||||
For example:
|
||||
|
|
@ -247,11 +268,13 @@ In this example, the function <tt>int_to_uint()</tt> would be used to cast type
|
|||
|
||||
<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>
|
||||
|
||||
<a name="n5"></a><H3>13.2.2 carrays.i</H3>
|
||||
<H3><a name="Library_nn5"></a>8.2.2 carrays.i</H3>
|
||||
|
||||
|
||||
This module defines macros that assist in wrapping ordinary C pointers as arrays.
|
||||
|
|
@ -261,11 +284,15 @@ raw C array data.
|
|||
|
||||
<p>
|
||||
<b><tt>%array_functions(type,name)</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Creates four functions.
|
||||
|
||||
<p>
|
||||
<tt>type *new_name(int nelements)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
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.
|
||||
|
|
@ -273,18 +300,24 @@ Creates a new array of objects of type <tt>type</tt>. In C, the array is alloc
|
|||
|
||||
<p>
|
||||
<tt>type *delete_name(type *ary)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Deletes an array. In C, <tt>free()</tt> is used. In C++, <tt>delete []</tt> is used.
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
<tt>type name_getitem(type *ary, int index)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Returns the value <tt>ary[index]</tt>.
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
<tt>void name_setitem(type *ary, int index, type value)</tt>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Assigns <tt>ary[index] = value</tt>.
|
||||
</blockquote>
|
||||
|
|
@ -296,6 +329,7 @@ should not correspond to any other name used in the interface file.
|
|||
<p>
|
||||
Here is an example of <tt>%array_functions()</tt>. Suppose you had a
|
||||
function like this:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
|
|
@ -333,8 +367,6 @@ delete_doubleArray(a) # Destroy array
|
|||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
<b><tt>%array_class(type,name)</tt></b>
|
||||
<blockquote>
|
||||
Wraps a pointer of <tt>type *</tt> inside a class-based interface. This
|
||||
|
|
@ -365,6 +397,7 @@ it can be transparently passed to any function that expects the pointer.
|
|||
<p>
|
||||
When combined with proxy classes, the <tt>%array_class()</tt> macro can be especially useful.
|
||||
For example:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
|
|
@ -392,12 +425,14 @@ example.print_array(c) # Pass to C
|
|||
<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>
|
||||
|
||||
<a name="n6"></a><H3>13.2.3 cmalloc.i</H3>
|
||||
<H3><a name="Library_nn6"></a>8.2.3 cmalloc.i</H3>
|
||||
|
||||
|
||||
This module defines macros for wrapping the low-level C memory allocation functions
|
||||
|
|
@ -405,6 +440,8 @@ This module defines macros for wrapping the low-level C memory allocation functi
|
|||
|
||||
<p>
|
||||
<b><tt>%malloc(type [,name=type])</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Creates a wrapper around <tt>malloc()</tt> with the following prototype:
|
||||
<blockquote><pre>
|
||||
|
|
@ -418,6 +455,8 @@ is not a valid identifier (e.g., "<tt>int *</tt>", "<tt>double **</tt>", etc.).
|
|||
|
||||
<p>
|
||||
<b><tt>%calloc(type [,name=type])</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Creates a wrapper around <tt>calloc()</tt> with the following prototype:
|
||||
<blockquote><pre>
|
||||
|
|
@ -429,6 +468,8 @@ If <tt>type</tt> is <tt>void</tt>, then the size parameter <tt>sz</tt> is requir
|
|||
|
||||
<p>
|
||||
<b><tt>%realloc(type [,name=type])</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Creates a wrapper around <tt>realloc()</tt> with the following prototype:
|
||||
<blockquote><pre>
|
||||
|
|
@ -442,6 +483,8 @@ it holds 100 integers.
|
|||
|
||||
<p>
|
||||
<b><tt>%free(type [,name=type])</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Creates a wrapper around <tt>free()</tt> with the following prototype:
|
||||
<blockquote><pre>
|
||||
|
|
@ -452,6 +495,8 @@ void free_<em>name</em>(<em>type</em> *ptr);
|
|||
|
||||
<p>
|
||||
<b><tt>%sizeof(type [,name=type])</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Creates the constant:
|
||||
<blockquote><pre>
|
||||
|
|
@ -462,12 +507,15 @@ Creates the constant:
|
|||
|
||||
<p>
|
||||
<b><tt>%allocators(type [,name=type])</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Generates wrappers for all five of the above operations.
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
Here is a simple example that illustrates the use of these macros:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
|
|
@ -489,27 +537,27 @@ Now, in a script:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> from example import *
|
||||
>>> a = malloc_int()
|
||||
>>> a
|
||||
>>> from example import *
|
||||
>>> a = malloc_int()
|
||||
>>> a
|
||||
'_000efa70_p_int'
|
||||
>>> free_int(a)
|
||||
>>> b = malloc_intp()
|
||||
>>> b
|
||||
>>> free_int(a)
|
||||
>>> b = malloc_intp()
|
||||
>>> b
|
||||
'_000efb20_p_p_int'
|
||||
>>> free_intp(b)
|
||||
>>> c = calloc_double(50)
|
||||
>>> c
|
||||
>>> free_intp(b)
|
||||
>>> c = calloc_double(50)
|
||||
>>> c
|
||||
'_000fab98_p_double'
|
||||
>>> c = realloc_double(100000)
|
||||
>>> free_double(c)
|
||||
>>> print sizeof_double
|
||||
>>> c = realloc_double(100000)
|
||||
>>> free_double(c)
|
||||
>>> print sizeof_double
|
||||
8
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<a name="n7"></a><H3>13.2.4 cdata.i</H3>
|
||||
<H3><a name="Library_nn7"></a>8.2.4 cdata.i</H3>
|
||||
|
||||
|
||||
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from strings
|
||||
|
|
@ -520,6 +568,8 @@ in order for this to work.
|
|||
|
||||
<p>
|
||||
<b><tt>char *cdata(void *ptr, int nbytes)</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any
|
||||
pointer.
|
||||
|
|
@ -527,6 +577,8 @@ pointer.
|
|||
|
||||
<p>
|
||||
<b><tt>void memmove(void *ptr, char *s)</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
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
|
||||
|
|
@ -551,18 +603,18 @@ Python example:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> a = intArray(10)
|
||||
>>> for i in range(0,10):
|
||||
>>> a = intArray(10)
|
||||
>>> for i in range(0,10):
|
||||
... a[i] = i
|
||||
>>> b = cdata(a,40)
|
||||
>>> b
|
||||
>>> 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]
|
||||
>>> c = intArray(10)
|
||||
>>> memmove(c,b)
|
||||
>>> print c[4]
|
||||
4
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -570,6 +622,8 @@ Since the size of data is not always known, the following macro is also defined:
|
|||
|
||||
<p>
|
||||
<b><tt>%cdata(type [,name=type])</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Generates the following function for extracting C data for a given type.
|
||||
<blockquote>
|
||||
|
|
@ -583,7 +637,7 @@ char *cdata_<em>name</em>(int nitems)
|
|||
<b>Note:</b> These functions provide direct access to memory and can be used to overwrite data.
|
||||
Clearly they are unsafe.
|
||||
|
||||
<a name="n8"></a><H2>13.3 C String Handling</H2>
|
||||
<H2><a name="Library_nn8"></a>8.3 C String Handling</H2>
|
||||
|
||||
|
||||
A common problem when working with C programs is dealing with
|
||||
|
|
@ -599,8 +653,9 @@ 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>
|
||||
|
||||
<a name="n9"></a><H3>13.3.1 Default string handling</H3>
|
||||
<H3><a name="Library_nn9"></a>8.3.1 Default string handling</H3>
|
||||
|
||||
|
||||
Suppose you have a C function with this prototype:
|
||||
|
|
@ -633,8 +688,9 @@ 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>
|
||||
|
||||
<a name="n10"></a><H3>13.3.2 Passing binary data</H3>
|
||||
<H3><a name="Library_nn10"></a>8.3.2 Passing binary data</H3>
|
||||
|
||||
|
||||
If you have a function that expects binary data,
|
||||
|
|
@ -660,14 +716,14 @@ Now, in the target language, you can use binary string data like this:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> s = "H\x00\x15eg\x09\x20"
|
||||
>>> parity(s,0)
|
||||
>>> s = "H\x00\x15eg\x09\x20"
|
||||
>>> parity(s,0)
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
In the wrapper function, the passed string will be expanded to a pointer and length parameter.
|
||||
|
||||
<a name="n11"></a><H3>13.3.3 Using %newobject to release memory</H3>
|
||||
<H3><a name="Library_nn11"></a>8.3.3 Using %newobject to release memory</H3>
|
||||
|
||||
|
||||
If you have a function that allocates memory like this,
|
||||
|
|
@ -687,6 +743,7 @@ into a string object and the old contents ignored.
|
|||
|
||||
<p>
|
||||
To fix the memory leak, use the <tt>%newobject</tt> directive.
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
|
|
@ -698,7 +755,7 @@ char *foo();
|
|||
|
||||
This will release the result.
|
||||
|
||||
<a name="n12"></a><H3>13.3.4 cstring.i</H3>
|
||||
<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>
|
||||
|
||||
|
||||
The <tt>cstring.i</tt> library file provides a collection of macros
|
||||
|
|
@ -731,9 +788,12 @@ involving bounds checking).
|
|||
<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>
|
||||
|
||||
<blockquote>
|
||||
Turns parameter <tt><em>parm</em></tt> into an output value. The
|
||||
output string is assumed to be NULL-terminated and smaller than
|
||||
|
|
@ -751,9 +811,9 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> get_path()
|
||||
>>> get_path()
|
||||
/home/beazley/packages/Foo/Bar
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -768,6 +828,8 @@ bytes are written, your program will crash with a buffer overflow!</b>
|
|||
|
||||
<p>
|
||||
<b>%cstring_chunk_output(parm, chunksize)</b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Turns parameter <tt><em>parm</em></tt> into an output value. The
|
||||
output string is always <tt><em>chunksize</em></tt> and may contain
|
||||
|
|
@ -785,9 +847,9 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> get_packet()
|
||||
>>> get_packet()
|
||||
'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -801,6 +863,8 @@ bytes are written, your program will crash with a buffer overflow!</b>
|
|||
|
||||
<p>
|
||||
<b>%cstring_bounded_mutable(parm, maxsize)</b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Turns parameter <tt><em>parm</em></tt> into a mutable string argument.
|
||||
The input string is assumed to be NULL-terminated and smaller than
|
||||
|
|
@ -819,9 +883,9 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> make_upper("hello world")
|
||||
>>> make_upper("hello world")
|
||||
'HELLO WORLD'
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -837,6 +901,8 @@ written, your program will crash with a buffer overflow!</b>
|
|||
|
||||
<p>
|
||||
<b>%cstring_mutable(parm [, expansion])</b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Turns parameter <tt><em>parm</em></tt> into a mutable string argument.
|
||||
The input string is assumed to be NULL-terminated. An optional
|
||||
|
|
@ -861,11 +927,11 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> make_upper("hello world")
|
||||
>>> make_upper("hello world")
|
||||
'HELLO WORLD'
|
||||
>>> attach_header("Hello world")
|
||||
>>> attach_header("Hello world")
|
||||
'header: Hello world'
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -884,6 +950,8 @@ bytes, then the program will crash with a buffer overflow!</b>
|
|||
|
||||
<p>
|
||||
<b>%cstring_output_maxsize(parm, maxparm)</b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
This macro is used to handle bounded character output functions where
|
||||
both a <tt>char *</tt> and a maximum length parameter are provided.
|
||||
|
|
@ -902,9 +970,9 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> get_path(1024)
|
||||
>>> get_path(1024)
|
||||
'/home/beazley/Packages/Foo/Bar'
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -918,6 +986,8 @@ into that buffer and returned as a string object.
|
|||
|
||||
<p>
|
||||
<b>%cstring_output_withsize(parm, maxparm)</b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
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,
|
||||
|
|
@ -938,11 +1008,11 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> get_data(1024)
|
||||
>>> get_data(1024)
|
||||
'x627388912'
|
||||
>>> get_data(1024)
|
||||
>>> get_data(1024)
|
||||
'xyzzy'
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -954,6 +1024,8 @@ how much data is actually returned by changing the value of the <tt>maxparm</tt>
|
|||
|
||||
<p>
|
||||
<b>%cstring_output_allocate(parm, release)</b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
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:
|
||||
|
|
@ -983,9 +1055,9 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> foo()
|
||||
>>> foo()
|
||||
'Hello world\n'
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
|
@ -993,6 +1065,8 @@ In the target language:
|
|||
|
||||
<p>
|
||||
<b>%cstring_output_allocate_size(parm, szparm, release)</b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
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:
|
||||
|
|
@ -1024,9 +1098,9 @@ In the target language:
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> foo()
|
||||
>>> foo()
|
||||
'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88'
|
||||
>>>
|
||||
>>>
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -1053,30 +1127,31 @@ void my_get_data(char **result, int *len) {
|
|||
|
||||
<b>Comments:</b>
|
||||
<ul>
|
||||
<Li>Support for the <tt>cstring.i</tt> module depends on the target language. Not all
|
||||
<li>Support for the <tt>cstring.i</tt> module depends on the target language. Not all
|
||||
SWIG modules currently support this library.
|
||||
</li>
|
||||
|
||||
<p>
|
||||
<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>
|
||||
|
||||
<P>
|
||||
<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>
|
||||
|
||||
<p>
|
||||
<li>Rather than manipulating <tt>char *</tt> directly, you might consider using a special string
|
||||
structure or class instead.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<a name="n13"></a><H2>13.4 C++ Library</H2>
|
||||
<H2><a name="Library_nn13"></a>8.4 C++ Library</H2>
|
||||
|
||||
|
||||
The library modules in this section provide access to parts of the standard C++ library.
|
||||
All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete
|
||||
C++ library support including support for the STL.
|
||||
|
||||
<a name="n14"></a><H3>13.4.1 std_string.i</H3>
|
||||
<H3><a name="Library_nn14"></a>8.4.1 std_string.i</H3>
|
||||
|
||||
|
||||
The <tt>std_string.i</tt> library provides typemaps for converting C++ <tt>std::string</tt>
|
||||
|
|
@ -1088,7 +1163,7 @@ objects to and from strings in the target scripting language. For example:
|
|||
%include "std_string.i"
|
||||
|
||||
std::string foo();
|
||||
void bar(const std::string &x);
|
||||
void bar(const std::string &x);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -1102,12 +1177,13 @@ bar("Hello World"); # Pass string as std::string
|
|||
</blockquote>
|
||||
|
||||
This module only supports types <tt>std::string</tt> and
|
||||
<tt>const std::string &</tt>. Pointers and non-const references
|
||||
<tt>const std::string &</tt>. Pointers and non-const references
|
||||
are left unmodified and returned as SWIG pointers.
|
||||
|
||||
<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>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
|
|
@ -1117,14 +1193,14 @@ it with a typedef, make sure you include those declarations in your interface.
|
|||
using namespace std;
|
||||
typedef std::string String;
|
||||
...
|
||||
void foo(string s, const String &t); // std_string typemaps still applied
|
||||
void foo(string s, const String &t); // std_string typemaps still applied
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
<b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms.
|
||||
We're looking into it.
|
||||
|
||||
<a name="n15"></a><H3>13.4.2 std_vector.i</H3>
|
||||
<H3><a name="Library_nn15"></a>8.4.2 std_vector.i</H3>
|
||||
|
||||
|
||||
The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL.
|
||||
|
|
@ -1137,66 +1213,66 @@ instantiate different versions of <tt>vector</tt> for the types that you want to
|
|||
%include "std_vector.i"
|
||||
|
||||
namespace std {
|
||||
%template(vectori) vector<int>;
|
||||
%template(vectord) vector<double>;
|
||||
%template(vectori) vector<int>;
|
||||
%template(vectord) vector<double>;
|
||||
};
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
When a template <tt>vector<X></tt> is instantiated a number of things happen:
|
||||
When a template <tt>vector<X></tt> is instantiated a number of things happen:
|
||||
|
||||
<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>
|
||||
|
||||
<p>
|
||||
<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
|
||||
<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>
|
||||
|
||||
<P>
|
||||
<li>An output typemap is defined for <tt>vector<X></tt>. In this case, the values in the
|
||||
<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>
|
||||
|
||||
<p>
|
||||
<li>For all other variations of the type, the wrappers expect to receive a <tt>vector<X> *</tt>
|
||||
<li>For all other variations of the type, the wrappers expect to receive a <tt>vector<X> *</tt>
|
||||
object in the usual manner.
|
||||
</li>
|
||||
|
||||
<P>
|
||||
<li>An exception handler for <tt>std::out_of_range</tt> is defined.
|
||||
</li>
|
||||
|
||||
<p>
|
||||
<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:
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
/* File : example.h */
|
||||
|
||||
#include <vector>
|
||||
#include <algorithm>
|
||||
#include <functional>
|
||||
#include <numeric>
|
||||
#include <vector>
|
||||
#include <algorithm>
|
||||
#include <functional>
|
||||
#include <numeric>
|
||||
|
||||
double average(std::vector<int> v) {
|
||||
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);
|
||||
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) {
|
||||
void halve_in_place(std::vector<double>& v) {
|
||||
std::transform(v.begin(),v.end(),v.begin(),
|
||||
std::bind2nd(std::divides<double>(),2.0));
|
||||
std::bind2nd(std::divides<double>(),2.0));
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
|
@ -1213,8 +1289,8 @@ To wrap with SWIG, you might write the following:
|
|||
%include "std_vector.i"
|
||||
// Instantiate templates used by example
|
||||
namespace std {
|
||||
%template(IntVector) vector<int>;
|
||||
%template(DoubleVector) vector<double>;
|
||||
%template(IntVector) vector<int>;
|
||||
%template(DoubleVector) vector<double>;
|
||||
}
|
||||
|
||||
// Include the header file with above prototypes
|
||||
|
|
@ -1226,38 +1302,38 @@ Now, to illustrate the behavior in the scripting interpreter, consider this Pyth
|
|||
|
||||
<blockquote>
|
||||
<pre>
|
||||
>>> from example import *
|
||||
>>> iv = IntVector(4) # Create an vector<int>
|
||||
>>> for i in range(0,4):
|
||||
>>> from example import *
|
||||
>>> iv = IntVector(4) # Create an vector<int>
|
||||
>>> for i in range(0,4):
|
||||
... iv[i] = i
|
||||
>>> average(iv) # Call method
|
||||
>>> average(iv) # Call method
|
||||
1.5
|
||||
>>> average([0,1,2,3]) # Call with list
|
||||
>>> average([0,1,2,3]) # Call with list
|
||||
1.5
|
||||
>>> half([1,2,3]) # Half a list
|
||||
>>> half([1,2,3]) # Half a list
|
||||
(0.5,1.0,1.5)
|
||||
>>> halve_in_place([1,2,3]) # Oops
|
||||
>>> halve_in_place([1,2,3]) # Oops
|
||||
Traceback (most recent call last):
|
||||
File "<stdin>", line 1, in ?
|
||||
File "<stdin>", line 1, in ?
|
||||
TypeError: Type error. Expected _p_std__vectorTdouble_t
|
||||
>>> dv = DoubleVector(4)
|
||||
>>> for i in range(0,4):
|
||||
>>> dv = DoubleVector(4)
|
||||
>>> for i in range(0,4):
|
||||
... dv[i] = i
|
||||
>>> halve_in_place(dv) # Ok
|
||||
>>> for i in dv:
|
||||
>>> halve_in_place(dv) # Ok
|
||||
>>> for i in dv:
|
||||
... print i
|
||||
...
|
||||
0.0
|
||||
0.5
|
||||
1.0
|
||||
1.5
|
||||
>>> dv[20] = 4.5
|
||||
>>> dv[20] = 4.5
|
||||
Traceback (most recent call last):
|
||||
File "<stdin>", line 1, in ?
|
||||
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>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -1269,13 +1345,13 @@ make sure you include the appropriate <tt>using</tt> or typedef directives. For
|
|||
%include "std_vector.i"
|
||||
|
||||
namespace std {
|
||||
%template(IntVector) vector<int>;
|
||||
%template(IntVector) vector<int>;
|
||||
}
|
||||
|
||||
using namespace std;
|
||||
typedef std::vector Vector;
|
||||
|
||||
void foo(vector<int> *x, const Vector &x);
|
||||
void foo(vector<int> *x, const Vector &x);
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
|
@ -1284,19 +1360,22 @@ void foo(vector<int> *x, const Vector &x);
|
|||
and template partial specialization. If you are tring 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>
|
||||
|
||||
|
||||
<a name="n16"></a><H2>13.5 Utility Libraries</H2>
|
||||
<H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2>
|
||||
|
||||
|
||||
<a name="n17"></a><H3>13.5.1 exception.i</H3>
|
||||
<H3><a name="Library_nn17"></a>8.5.1 exception.i</H3>
|
||||
|
||||
|
||||
The <tt>exception.i</tt> library provides a language-independent function for raising a run-time
|
||||
|
|
@ -1304,6 +1383,8 @@ exception in the target language.
|
|||
|
||||
<p>
|
||||
<b><tt>SWIG_exception(int code, const char *message)</tt></b>
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
Raises an exception in the target language. <tt>code</tt> is one of the following symbolic
|
||||
constants:
|
||||
|
|
@ -1336,14 +1417,14 @@ For example:
|
|||
try {
|
||||
$action
|
||||
} catch (std::out_of_range& e) {
|
||||
SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
|
||||
SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
|
||||
<p><hr>
|
||||
<hr>
|
||||
<address>SWIG 1.3 - Last Modified : May 29, 2002</address>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue