diff options
Diffstat (limited to 'Doc/Manual/Library.html')
| -rw-r--r-- | Doc/Manual/Library.html | 361 |
1 files changed, 221 insertions, 140 deletions
diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html index be1ebd2be..bce66503b 100644 --- a/Doc/Manual/Library.html +++ b/Doc/Manual/Library.html @@ -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> @@ -229,8 +249,9 @@ pointers. This is because the pointers are access like objects and they can be (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> |