Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>SWIG Library</title> | |
5 | <link rel="stylesheet" type="text/css" href="style.css"> | |
6 | </head> | |
7 | ||
8 | <body bgcolor="#ffffff"> | |
9 | <H1><a name="Library"></a>8 SWIG library</H1> | |
10 | <!-- INDEX --> | |
11 | <div class="sectiontoc"> | |
12 | <ul> | |
13 | <li><a href="#Library_nn2">The %include directive and library search path</a> | |
14 | <li><a href="#Library_nn3">C Arrays and Pointers</a> | |
15 | <ul> | |
16 | <li><a href="#Library_nn4">cpointer.i</a> | |
17 | <li><a href="#Library_nn5">carrays.i</a> | |
18 | <li><a href="#Library_nn6">cmalloc.i</a> | |
19 | <li><a href="#Library_nn7">cdata.i</a> | |
20 | </ul> | |
21 | <li><a href="#Library_nn8">C String Handling</a> | |
22 | <ul> | |
23 | <li><a href="#Library_nn9">Default string handling</a> | |
24 | <li><a href="#Library_nn10">Passing binary data</a> | |
25 | <li><a href="#Library_nn11">Using %newobject to release memory</a> | |
26 | <li><a href="#Library_nn12">cstring.i</a> | |
27 | </ul> | |
28 | <li><a href="#Library_stl_cpp_library">STL/C++ Library</a> | |
29 | <ul> | |
30 | <li><a href="#Library_nn14">std_string.i</a> | |
31 | <li><a href="#Library_nn15">std_vector.i</a> | |
32 | <li><a href="#Library_stl_exceptions">STL exceptions</a> | |
33 | </ul> | |
34 | <li><a href="#Library_nn16">Utility Libraries</a> | |
35 | <ul> | |
36 | <li><a href="#Library_nn17">exception.i</a> | |
37 | </ul> | |
38 | </ul> | |
39 | </div> | |
40 | <!-- INDEX --> | |
41 | ||
42 | ||
43 | ||
44 | <p> | |
45 | To help build extension modules, SWIG is packaged with a library of | |
46 | support files that you can include in your own interfaces. These | |
47 | files often define new SWIG directives or provide utility | |
48 | functions that can be used to access parts of the standard C and C++ libraries. | |
49 | This chapter provides a reference to the current set of supported library files. | |
50 | </p> | |
51 | ||
52 | <p> | |
53 | <b>Compatibility note:</b> Older versions of SWIG included a number of | |
54 | library files for manipulating pointers, arrays, and other structures. Most | |
55 | these files are now deprecated and have been removed from the distribution. | |
56 | Alternative libraries provide similar functionality. Please read this chapter | |
57 | carefully if you used the old libraries. | |
58 | </p> | |
59 | ||
60 | <H2><a name="Library_nn2"></a>8.1 The %include directive and library search path</H2> | |
61 | ||
62 | ||
63 | <p> | |
64 | Library files are included using the <tt>%include</tt> directive. | |
65 | When searching for files, directories are searched in the following order: | |
66 | </p> | |
67 | ||
68 | <ul> | |
69 | <li>The current directory | |
70 | <li>Directories specified with the <tt>-I</tt> command line option | |
71 | <li>.<tt>/swig_lib</tt> | |
72 | <li><tt>/usr/local/lib/swig_lib</tt> (or wherever you installed SWIG) | |
73 | <li>On Windows, SWIG also looks for the library relative to the location of <tt>swig.exe</tt>. | |
74 | </ul> | |
75 | ||
76 | <p> | |
77 | Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., <tt>python</tt>, | |
78 | <tt>tcl</tt>, etc.). If found, SWIG will search the language specific directory first. This allows | |
79 | for language-specific implementations of library files. | |
80 | </p> | |
81 | ||
82 | <p> | |
83 | You can override the location of the SWIG library by setting the | |
84 | <tt>SWIG_LIB</tt> environment variable. | |
85 | </p> | |
86 | ||
87 | <H2><a name="Library_nn3"></a>8.2 C Arrays and Pointers</H2> | |
88 | ||
89 | ||
90 | <p> | |
91 | This section describes library modules for manipulating low-level C arrays and pointers. | |
92 | The primary use of these modules is in supporting C declarations that manipulate bare | |
93 | pointers such as <tt>int *</tt>, <tt>double *</tt>, or <tt>void *</tt>. The modules can be | |
94 | used to allocate memory, manufacture pointers, dereference memory, and wrap | |
95 | pointers as class-like objects. Since these functions provide direct access to | |
96 | memory, their use is potentially unsafe and you should exercise caution. | |
97 | </p> | |
98 | ||
99 | <H3><a name="Library_nn4"></a>8.2.1 cpointer.i</H3> | |
100 | ||
101 | ||
102 | <p> | |
103 | The <tt>cpointer.i</tt> module defines macros that can be used to used | |
104 | to generate wrappers around simple C pointers. The primary use of | |
105 | this module is in generating pointers to primitive datatypes such as | |
106 | <tt>int</tt> and <tt>double</tt>. | |
107 | </p> | |
108 | ||
109 | <p> | |
110 | <b><tt>%pointer_functions(type,name)</tt></b> | |
111 | </p> | |
112 | ||
113 | <div class="indent"> | |
114 | <p>Generates a collection of four functions for manipulating a pointer <tt>type *</tt>:</p> | |
115 | ||
116 | <p> | |
117 | <tt>type *new_name()</tt> | |
118 | </p> | |
119 | ||
120 | <div class="indent"><p> | |
121 | Creates a new object of type <tt>type</tt> and returns a pointer to it. In C, the | |
122 | object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used. | |
123 | </p></div> | |
124 | ||
125 | <p> | |
126 | <tt>type *copy_name(type value)</tt> | |
127 | </p> | |
128 | ||
129 | <div class="indent"><p> | |
130 | Creates a new object of type <tt>type</tt> and returns a pointer to it. | |
131 | An initial value is set by copying it from <tt>value</tt>. In C, the | |
132 | object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used. | |
133 | </p></div> | |
134 | ||
135 | <p> | |
136 | <tt>type *delete_name(type *obj)</tt> | |
137 | </p> | |
138 | ||
139 | <div class="indent"><p> | |
140 | Deletes an object type <tt>type</tt>. | |
141 | </p></div> | |
142 | ||
143 | <p> | |
144 | <tt>void name_assign(type *obj, type value)</tt> | |
145 | </p> | |
146 | ||
147 | <div class="indent"><p> | |
148 | Assigns <tt>*obj = value</tt>. | |
149 | </p></div> | |
150 | ||
151 | <p> | |
152 | <tt>type name_value(type *obj)</tt> | |
153 | </p> | |
154 | ||
155 | <div class="indent"><p> | |
156 | Returns the value of <tt>*obj</tt>. | |
157 | </p></div> | |
158 | ||
159 | <p> | |
160 | When using this macro, <tt>type</tt> may be any type and <tt>name</tt> must be a legal identifier in the target | |
161 | language. <tt>name</tt> should not correspond to any other name used in the interface file. | |
162 | </p> | |
163 | ||
164 | ||
165 | <p> | |
166 | Here is a simple example of using <tt>%pointer_functions()</tt>: | |
167 | </p> | |
168 | ||
169 | <div class="code"> | |
170 | <pre> | |
171 | %module example | |
172 | %include "cpointer.i" | |
173 | ||
174 | /* Create some functions for working with "int *" */ | |
175 | %pointer_functions(int, intp); | |
176 | ||
177 | /* A function that uses an "int *" */ | |
178 | void add(int x, int y, int *result); | |
179 | </pre> | |
180 | </div> | |
181 | ||
182 | <p> | |
183 | Now, in Python: | |
184 | </p> | |
185 | ||
186 | <div class="targetlang"> | |
187 | <pre> | |
188 | >>> import example | |
189 | >>> c = example.new_intp() # Create an "int" for storing result | |
190 | >>> example.add(3,4,c) # Call function | |
191 | >>> example.intp_value(c) # Dereference | |
192 | 7 | |
193 | >>> example.delete_intp(c) # Delete | |
194 | </pre> | |
195 | </div> | |
196 | ||
197 | </div> | |
198 | ||
199 | <p> | |
200 | <b><tt>%pointer_class(type,name)</tt></b> | |
201 | </p> | |
202 | ||
203 | <div class="indent"> | |
204 | ||
205 | <p> | |
206 | Wraps a pointer of <tt>type *</tt> inside a class-based interface. This | |
207 | interface is as follows: | |
208 | </p> | |
209 | ||
210 | <div class="code"> | |
211 | <pre> | |
212 | struct name { | |
213 | name(); // Create pointer object | |
214 | ~name(); // Delete pointer object | |
215 | void assign(type value); // Assign value | |
216 | type value(); // Get value | |
217 | type *cast(); // Cast the pointer to original type | |
218 | static name *frompointer(type *); // Create class wrapper from existing | |
219 | // pointer | |
220 | }; | |
221 | </pre> | |
222 | </div> | |
223 | ||
224 | <p> | |
225 | When using this macro, <tt>type</tt> is restricted to a simple type | |
226 | name like <tt>int</tt>, <tt>float</tt>, or <tt>Foo</tt>. Pointers and | |
227 | other complicated types are not allowed. <tt>name</tt> must be a | |
228 | valid identifier not already in use. When a pointer is wrapped as a class, | |
229 | the "class" may be transparently passed to any function that expects the pointer. | |
230 | </p> | |
231 | ||
232 | <p> | |
233 | If the target language does not support proxy classes, the use of this macro will produce the example | |
234 | same functions as <tt>%pointer_functions()</tt> macro. | |
235 | </p> | |
236 | ||
237 | ||
238 | <p> | |
239 | It should be noted that the class interface does introduce a new object or wrap a pointer inside a special | |
240 | structure. Instead, the raw pointer is used directly. | |
241 | </p> | |
242 | ||
243 | ||
244 | ||
245 | <p> | |
246 | Here is the same example using a class instead: | |
247 | </p> | |
248 | ||
249 | <div class="code"> | |
250 | <pre> | |
251 | %module example | |
252 | %include "cpointer.i" | |
253 | ||
254 | /* Wrap a class interface around an "int *" */ | |
255 | %pointer_class(int, intp); | |
256 | ||
257 | /* A function that uses an "int *" */ | |
258 | void add(int x, int y, int *result); | |
259 | </pre> | |
260 | </div> | |
261 | ||
262 | <p> | |
263 | Now, in Python (using proxy classes) | |
264 | </p> | |
265 | ||
266 | <div class="targetlang"> | |
267 | <pre> | |
268 | >>> import example | |
269 | >>> c = example.intp() # Create an "int" for storing result | |
270 | >>> example.add(3,4,c) # Call function | |
271 | >>> c.value() # Dereference | |
272 | 7 | |
273 | </pre> | |
274 | </div> | |
275 | ||
276 | <p> | |
277 | Of the two macros, <tt>%pointer_class</tt> is probably the most convenient when working with simple | |
278 | pointers. This is because the pointers are access like objects and they can be easily garbage collected | |
279 | (destruction of the pointer object destroys the underlying object). | |
280 | </p> | |
281 | ||
282 | </div> | |
283 | ||
284 | <p> | |
285 | <b><tt>%pointer_cast(type1, type2, name)</tt></b> | |
286 | </p> | |
287 | ||
288 | <div class="indent"> | |
289 | ||
290 | <p> | |
291 | Creates a casting function that converts <tt>type1</tt> to <tt>type2</tt>. The name of the function is <tt>name</tt>. | |
292 | For example: | |
293 | </p> | |
294 | ||
295 | <div class="code"> | |
296 | <pre> | |
297 | %pointer_cast(int *, unsigned int *, int_to_uint); | |
298 | </pre> | |
299 | </div> | |
300 | ||
301 | <p> | |
302 | In this example, the function <tt>int_to_uint()</tt> would be used to cast types in the target language. | |
303 | </p> | |
304 | ||
305 | </div> | |
306 | ||
307 | <p> | |
308 | <b>Note:</b> None of these macros can be used to safely work with strings (<tt>char *</tt> or <tt>char **</tt>). | |
309 | </p> | |
310 | ||
311 | <P> | |
312 | <b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation. | |
313 | </p> | |
314 | ||
315 | <H3><a name="Library_nn5"></a>8.2.2 carrays.i</H3> | |
316 | ||
317 | ||
318 | <p> | |
319 | This module defines macros that assist in wrapping ordinary C pointers as arrays. | |
320 | The module does not provide any safety or an extra layer of wrapping--it merely | |
321 | provides functionality for creating, destroying, and modifying the contents of | |
322 | raw C array data. | |
323 | </p> | |
324 | ||
325 | <p> | |
326 | <b><tt>%array_functions(type,name)</tt></b> | |
327 | </p> | |
328 | ||
329 | <div class="indent"> | |
330 | <p>Creates four functions.</p> | |
331 | ||
332 | <p> | |
333 | <tt>type *new_name(int nelements)</tt> | |
334 | </p> | |
335 | ||
336 | <div class="indent"><p> | |
337 | Creates a new array of objects of type <tt>type</tt>. In C, the array is allocated using | |
338 | <tt>calloc()</tt>. In C++, <tt>new []</tt> is used. | |
339 | </p></div> | |
340 | ||
341 | <p> | |
342 | <tt>type *delete_name(type *ary)</tt> | |
343 | </p> | |
344 | ||
345 | <div class="indent"><p> | |
346 | Deletes an array. In C, <tt>free()</tt> is used. In C++, <tt>delete []</tt> is used. | |
347 | </p></div> | |
348 | ||
349 | <p> | |
350 | <tt>type name_getitem(type *ary, int index)</tt> | |
351 | </p> | |
352 | ||
353 | <div class="indent"><p> | |
354 | Returns the value <tt>ary[index]</tt>. | |
355 | </p></div> | |
356 | ||
357 | <p> | |
358 | <tt>void name_setitem(type *ary, int index, type value)</tt> | |
359 | </p> | |
360 | ||
361 | <div class="indent"><p> | |
362 | Assigns <tt>ary[index] = value</tt>. | |
363 | </p></div> | |
364 | ||
365 | <p> | |
366 | When using this macro, <tt>type</tt> may be any type and <tt>name</tt> | |
367 | must be a legal identifier in the target language. <tt>name</tt> | |
368 | should not correspond to any other name used in the interface file. | |
369 | </p> | |
370 | ||
371 | <p> | |
372 | Here is an example of <tt>%array_functions()</tt>. Suppose you had a | |
373 | function like this: | |
374 | </p> | |
375 | ||
376 | <div class="code"> | |
377 | <pre> | |
378 | void print_array(double x[10]) { | |
379 | int i; | |
380 | for (i = 0; i < 10; i++) { | |
381 | printf("[%d] = %g\n", i, x[i]); | |
382 | } | |
383 | } | |
384 | </pre> | |
385 | </div> | |
386 | ||
387 | <p> | |
388 | To wrap it, you might write this: | |
389 | </p> | |
390 | ||
391 | <div class="code"> | |
392 | <pre> | |
393 | %module example | |
394 | ||
395 | %include "carrays.i" | |
396 | %array_functions(double, doubleArray); | |
397 | ||
398 | void print_array(double x[10]); | |
399 | </pre> | |
400 | </div> | |
401 | ||
402 | <p> | |
403 | Now, in a scripting language, you might write this: | |
404 | </p> | |
405 | ||
406 | <div class="code"> | |
407 | <pre> | |
408 | a = new_doubleArray(10) # Create an array | |
409 | for i in range(0,10): | |
410 | doubleArray_setitem(a,i,2*i) # Set a value | |
411 | print_array(a) # Pass to C | |
412 | delete_doubleArray(a) # Destroy array | |
413 | </pre> | |
414 | </div> | |
415 | ||
416 | </div> | |
417 | ||
418 | <b><tt>%array_class(type,name)</tt></b> | |
419 | <div class="indent"> | |
420 | ||
421 | <p> | |
422 | Wraps a pointer of <tt>type *</tt> inside a class-based interface. This | |
423 | interface is as follows: | |
424 | </p> | |
425 | ||
426 | <div class="code"> | |
427 | <pre> | |
428 | struct name { | |
429 | name(int nelements); // Create an array | |
430 | ~name(); // Delete array | |
431 | type getitem(int index); // Return item | |
432 | void setitem(int index, type value); // Set item | |
433 | type *cast(); // Cast to original type | |
434 | static name *frompointer(type *); // Create class wrapper from | |
435 | // existing pointer | |
436 | }; | |
437 | </pre> | |
438 | </div> | |
439 | ||
440 | <p> | |
441 | When using this macro, <tt>type</tt> is restricted to a simple type | |
442 | name like <tt>int</tt> or <tt>float</tt>. Pointers and | |
443 | other complicated types are not allowed. <tt>name</tt> must be a | |
444 | valid identifier not already in use. When a pointer is wrapped as a class, | |
445 | it can be transparently passed to any function that expects the pointer. | |
446 | </p> | |
447 | ||
448 | ||
449 | <p> | |
450 | When combined with proxy classes, the <tt>%array_class()</tt> macro can be especially useful. | |
451 | For example: | |
452 | </p> | |
453 | ||
454 | <div class="code"> | |
455 | <pre> | |
456 | %module example | |
457 | %include "carrays.i" | |
458 | %array_class(double, doubleArray); | |
459 | ||
460 | void print_array(double x[10]); | |
461 | </pre> | |
462 | </div> | |
463 | ||
464 | <p> | |
465 | Allows you to do this: | |
466 | </p> | |
467 | ||
468 | <div class="code"> | |
469 | <pre> | |
470 | import example | |
471 | c = example.doubleArray(10) # Create double[10] | |
472 | for i in range(0,10): | |
473 | c[i] = 2*i # Assign values | |
474 | example.print_array(c) # Pass to C | |
475 | </pre> | |
476 | </div> | |
477 | ||
478 | </div> | |
479 | ||
480 | <p> | |
481 | <b>Note:</b> These macros do not encapsulate C arrays inside a special data structure | |
482 | or proxy. There is no bounds checking or safety of any kind. If you want this, | |
483 | you should consider using a special array object rather than a bare pointer. | |
484 | </p> | |
485 | ||
486 | <p> | |
487 | <b>Note:</b> <tt>%array_functions()</tt> and <tt>%array_class()</tt> should not be | |
488 | used with types of <tt>char</tt> or <tt>char *</tt>. | |
489 | </p> | |
490 | ||
491 | <H3><a name="Library_nn6"></a>8.2.3 cmalloc.i</H3> | |
492 | ||
493 | ||
494 | <p> | |
495 | This module defines macros for wrapping the low-level C memory allocation functions | |
496 | <tt>malloc()</tt>, <tt>calloc()</tt>, <tt>realloc()</tt>, and <tt>free()</tt>. | |
497 | </p> | |
498 | ||
499 | <p> | |
500 | <b><tt>%malloc(type [,name=type])</tt></b> | |
501 | </p> | |
502 | ||
503 | <div class="indent"> | |
504 | ||
505 | <p> | |
506 | Creates a wrapper around <tt>malloc()</tt> with the following prototype: | |
507 | </p> | |
508 | ||
509 | <div class="code"><pre> | |
510 | <em>type</em> *malloc_<em>name</em>(int nbytes = sizeof(<em>type</em>)); | |
511 | </pre> | |
512 | </div> | |
513 | ||
514 | <p> | |
515 | If <tt>type</tt> is <tt>void</tt>, then the size parameter <tt>nbytes</tt> is required. | |
516 | The <tt>name</tt> parameter only needs to be specified when wrapping a type that | |
517 | is not a valid identifier (e.g., "<tt>int *</tt>", "<tt>double **</tt>", etc.). | |
518 | </p> | |
519 | ||
520 | </div> | |
521 | ||
522 | <p> | |
523 | <b><tt>%calloc(type [,name=type])</tt></b> | |
524 | </p> | |
525 | ||
526 | <div class="indent"> | |
527 | ||
528 | <p> | |
529 | Creates a wrapper around <tt>calloc()</tt> with the following prototype: | |
530 | </p> | |
531 | ||
532 | <div class="code"><pre> | |
533 | <em>type</em> *calloc_<em>name</em>(int nobj =1, int sz = sizeof(<em>type</em>)); | |
534 | </pre> | |
535 | </div> | |
536 | ||
537 | <p> | |
538 | If <tt>type</tt> is <tt>void</tt>, then the size parameter <tt>sz</tt> is required. | |
539 | </p> | |
540 | ||
541 | </div> | |
542 | ||
543 | <p> | |
544 | <b><tt>%realloc(type [,name=type])</tt></b> | |
545 | </p> | |
546 | ||
547 | <div class="indent"> | |
548 | ||
549 | <p> | |
550 | Creates a wrapper around <tt>realloc()</tt> with the following prototype: | |
551 | </p> | |
552 | ||
553 | <div class="code"><pre> | |
554 | <em>type</em> *realloc_<em>name</em>(<em>type</em> *ptr, int nitems); | |
555 | </pre> | |
556 | </div> | |
557 | ||
558 | <p> | |
559 | Note: unlike the C <tt>realloc()</tt>, the wrapper generated by this macro implicitly includes the | |
560 | size of the corresponding type. For example, <tt>realloc_int(p, 100)</tt> reallocates <tt>p</tt> so that | |
561 | it holds 100 integers. | |
562 | </p> | |
563 | ||
564 | </div> | |
565 | ||
566 | <p> | |
567 | <b><tt>%free(type [,name=type])</tt></b> | |
568 | </p> | |
569 | ||
570 | <div class="indent"> | |
571 | ||
572 | <p> | |
573 | Creates a wrapper around <tt>free()</tt> with the following prototype: | |
574 | </p> | |
575 | ||
576 | <div class="code"><pre> | |
577 | void free_<em>name</em>(<em>type</em> *ptr); | |
578 | </pre> | |
579 | </div> | |
580 | </div> | |
581 | ||
582 | <p> | |
583 | <b><tt>%sizeof(type [,name=type])</tt></b> | |
584 | </p> | |
585 | ||
586 | <div class="indent"> | |
587 | ||
588 | <p> | |
589 | Creates the constant: | |
590 | </p> | |
591 | ||
592 | <div class="code"><pre> | |
593 | %constant int sizeof_<em>name</em> = sizeof(<em>type</em>); | |
594 | </pre> | |
595 | </div> | |
596 | </div> | |
597 | ||
598 | <p> | |
599 | <b><tt>%allocators(type [,name=type])</tt></b> | |
600 | </p> | |
601 | ||
602 | <div class="indent"><p> | |
603 | Generates wrappers for all five of the above operations. | |
604 | </p></div> | |
605 | ||
606 | <p> | |
607 | Here is a simple example that illustrates the use of these macros: | |
608 | </p> | |
609 | ||
610 | <div class="code"> | |
611 | <pre> | |
612 | // SWIG interface | |
613 | %module example | |
614 | %include "cmalloc.i" | |
615 | ||
616 | %malloc(int); | |
617 | %free(int); | |
618 | ||
619 | %malloc(int *, intp); | |
620 | %free(int *, intp); | |
621 | ||
622 | %allocators(double); | |
623 | </pre> | |
624 | </div> | |
625 | ||
626 | <p> | |
627 | Now, in a script: | |
628 | </p> | |
629 | ||
630 | <div class="targetlang"> | |
631 | <pre> | |
632 | >>> from example import * | |
633 | >>> a = malloc_int() | |
634 | >>> a | |
635 | '_000efa70_p_int' | |
636 | >>> free_int(a) | |
637 | >>> b = malloc_intp() | |
638 | >>> b | |
639 | '_000efb20_p_p_int' | |
640 | >>> free_intp(b) | |
641 | >>> c = calloc_double(50) | |
642 | >>> c | |
643 | '_000fab98_p_double' | |
644 | >>> c = realloc_double(100000) | |
645 | >>> free_double(c) | |
646 | >>> print sizeof_double | |
647 | 8 | |
648 | >>> | |
649 | </pre> | |
650 | </div> | |
651 | ||
652 | <H3><a name="Library_nn7"></a>8.2.4 cdata.i</H3> | |
653 | ||
654 | ||
655 | <p> | |
656 | The <tt>cdata.i</tt> module defines functions for converting raw C data to and from strings | |
657 | in the target language. The primary applications of this module would be packing/unpacking of | |
658 | binary data structures---for instance, if you needed to extract data from a buffer. | |
659 | The target language must support strings with embedded binary data | |
660 | in order for this to work. | |
661 | </p> | |
662 | ||
663 | <p> | |
664 | <b><tt>char *cdata(void *ptr, int nbytes)</tt></b> | |
665 | </p> | |
666 | ||
667 | <div class="indent"><p> | |
668 | Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any | |
669 | pointer. | |
670 | </p></div> | |
671 | ||
672 | <p> | |
673 | <b><tt>void memmove(void *ptr, char *s)</tt></b> | |
674 | </p> | |
675 | ||
676 | <div class="indent"><p> | |
677 | Copies all of the string data in <tt>s</tt> into the memory pointed to by | |
678 | <tt>ptr</tt>. The string may contain embedded NULL bytes. The length of | |
679 | the string is implicitly determined in the underlying wrapper code. | |
680 | </p></div> | |
681 | ||
682 | <p> | |
683 | One use of these functions is packing and unpacking data from memory. | |
684 | Here is a short example: | |
685 | </p> | |
686 | ||
687 | <div class="code"> | |
688 | <pre> | |
689 | // SWIG interface | |
690 | %module example | |
691 | %include "carrays.i" | |
692 | %include "cdata.i" | |
693 | ||
694 | %array_class(int, intArray); | |
695 | </pre> | |
696 | </div> | |
697 | ||
698 | <p> | |
699 | Python example: | |
700 | </p> | |
701 | ||
702 | <div class="targetlang"> | |
703 | <pre> | |
704 | >>> a = intArray(10) | |
705 | >>> for i in range(0,10): | |
706 | ... a[i] = i | |
707 | >>> b = cdata(a,40) | |
708 | >>> b | |
709 | '\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00\x04 | |
710 | \x00\x00\x00\x05\x00\x00\x00\x06\x00\x00\x00\x07\x00\x00\x00\x08\x00\x00\x00\t' | |
711 | >>> c = intArray(10) | |
712 | >>> memmove(c,b) | |
713 | >>> print c[4] | |
714 | 4 | |
715 | >>> | |
716 | </pre> | |
717 | </div> | |
718 | ||
719 | <p> | |
720 | Since the size of data is not always known, the following macro is also defined: | |
721 | </p> | |
722 | ||
723 | <p> | |
724 | <b><tt>%cdata(type [,name=type])</tt></b> | |
725 | </p> | |
726 | ||
727 | <div class="indent"> | |
728 | ||
729 | <p> | |
730 | Generates the following function for extracting C data for a given type. | |
731 | </p> | |
732 | ||
733 | <div class="code"> | |
734 | <pre> | |
735 | char *cdata_<em>name</em>(type* ptr, int nitems) | |
736 | </pre> | |
737 | </div> | |
738 | ||
739 | <p> | |
740 | <tt>nitems</tt> is the number of items of the given type to extract. | |
741 | </p> | |
742 | ||
743 | </div> | |
744 | ||
745 | <p> | |
746 | <b>Note:</b> These functions provide direct access to memory and can be used to overwrite data. | |
747 | Clearly they are unsafe. | |
748 | </p> | |
749 | ||
750 | <H2><a name="Library_nn8"></a>8.3 C String Handling</H2> | |
751 | ||
752 | ||
753 | <p> | |
754 | A common problem when working with C programs is dealing with | |
755 | functions that manipulate raw character data using <tt>char *</tt>. | |
756 | In part, problems arise because there are different interpretations of | |
757 | <tt>char *</tt>---it could be a NULL-terminated string or it could | |
758 | point to binary data. Moreover, functions that manipulate raw strings | |
759 | may mutate data, perform implicit memory allocations, or utilize | |
760 | fixed-sized buffers. | |
761 | </p> | |
762 | ||
763 | <p> | |
764 | The problems (and perils) of using <tt>char *</tt> are | |
765 | well-known. However, SWIG is not in the business of enforcing | |
766 | morality. The modules in this section provide basic functionality | |
767 | for manipulating raw C strings. | |
768 | </p> | |
769 | ||
770 | <H3><a name="Library_nn9"></a>8.3.1 Default string handling</H3> | |
771 | ||
772 | ||
773 | <p> | |
774 | Suppose you have a C function with this prototype: | |
775 | </p> | |
776 | ||
777 | <div class="code"> | |
778 | <pre> | |
779 | char *foo(char *s); | |
780 | </pre> | |
781 | </div> | |
782 | ||
783 | <p> | |
784 | The default wrapping behavior for this function is to set <tt>s</tt> | |
785 | to a raw <tt>char *</tt> that refers to the internal string data in the | |
786 | target language. In other words, if you were using a language like Tcl, | |
787 | and you wrote this, | |
788 | </p> | |
789 | ||
790 | <div class="code"> | |
791 | <pre> | |
792 | % foo Hello | |
793 | </pre> | |
794 | </div> | |
795 | ||
796 | <p> | |
797 | then <tt>s</tt> would point to the representation of "Hello" inside | |
798 | the Tcl interpreter. When returning a <tt>char *</tt>, SWIG assumes | |
799 | that it is a NULL-terminated string and makes a copy of it. This | |
800 | gives the target language its own copy of the result. | |
801 | </p> | |
802 | ||
803 | <p> | |
804 | There are obvious problems with the default behavior. First, since | |
805 | a <tt>char *</tt> argument points to data inside the target language, it is | |
806 | <b>NOT</b> safe for a function to modify this data (doing so may corrupt the | |
807 | interpreter and lead to a crash). Furthermore, the default behavior does | |
808 | not work well with binary data. Instead, strings are assumed to be NULL-terminated. | |
809 | </p> | |
810 | ||
811 | <H3><a name="Library_nn10"></a>8.3.2 Passing binary data</H3> | |
812 | ||
813 | ||
814 | <p> | |
815 | If you have a function that expects binary data, | |
816 | </p> | |
817 | ||
818 | <div class="code"> | |
819 | <pre> | |
820 | int parity(char *str, int len, int initial); | |
821 | </pre> | |
822 | </div> | |
823 | ||
824 | <p> | |
825 | you can wrap the parameters <tt>(char *str, int len)</tt> as a single | |
826 | argument using a typemap. Just do this: | |
827 | </p> | |
828 | ||
829 | <div class="code"> | |
830 | <pre> | |
831 | %apply (char *STRING, int LENGTH) { (char *str, int len) }; | |
832 | ... | |
833 | int parity(char *str, int len, int initial); | |
834 | </pre> | |
835 | </div> | |
836 | ||
837 | <p> | |
838 | Now, in the target language, you can use binary string data like this: | |
839 | </p> | |
840 | ||
841 | <div class="code"> | |
842 | <pre> | |
843 | >>> s = "H\x00\x15eg\x09\x20" | |
844 | >>> parity(s,0) | |
845 | </pre> | |
846 | </div> | |
847 | ||
848 | <p> | |
849 | In the wrapper function, the passed string will be expanded to a pointer and length parameter. | |
850 | </p> | |
851 | ||
852 | <H3><a name="Library_nn11"></a>8.3.3 Using %newobject to release memory</H3> | |
853 | ||
854 | ||
855 | <p> | |
856 | If you have a function that allocates memory like this, | |
857 | </p> | |
858 | ||
859 | <div class="code"> | |
860 | <pre> | |
861 | char *foo() { | |
862 | char *result = (char *) malloc(...); | |
863 | ... | |
864 | return result; | |
865 | } | |
866 | </pre> | |
867 | </div> | |
868 | ||
869 | <p> | |
870 | then the SWIG generated wrappers will have a memory leak--the returned data will be copied | |
871 | into a string object and the old contents ignored. | |
872 | </p> | |
873 | ||
874 | <p> | |
875 | To fix the memory leak, use the <tt>%newobject</tt> directive. | |
876 | </p> | |
877 | ||
878 | <div class="code"> | |
879 | <pre> | |
880 | %newobject foo; | |
881 | ... | |
882 | char *foo(); | |
883 | </pre> | |
884 | </div> | |
885 | ||
886 | <p> | |
887 | This will release the result. | |
888 | </p> | |
889 | ||
890 | <H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3> | |
891 | ||
892 | ||
893 | <p> | |
894 | The <tt>cstring.i</tt> library file provides a collection of macros | |
895 | for dealing with functions that either mutate string arguments or | |
896 | which try to output string data through their arguments. An | |
897 | example of such a function might be this rather questionable | |
898 | implementation: | |
899 | </p> | |
900 | ||
901 | <div class="code"> | |
902 | <pre> | |
903 | void get_path(char *s) { | |
904 | // Potential buffer overflow---uh, oh. | |
905 | sprintf(s,"%s/%s", base_directory, sub_directory); | |
906 | } | |
907 | ... | |
908 | // Somewhere else in the C program | |
909 | { | |
910 | char path[1024]; | |
911 | ... | |
912 | get_path(path); | |
913 | ... | |
914 | } | |
915 | </pre> | |
916 | </div> | |
917 | ||
918 | <p> | |
919 | (Off topic rant: If your program really has functions like this, you | |
920 | would be well-advised to replace them with safer alternatives | |
921 | involving bounds checking). | |
922 | </p> | |
923 | ||
924 | <p> | |
925 | The macros defined in this module all expand to various combinations of | |
926 | typemaps. Therefore, the same pattern matching rules and ideas apply. | |
927 | </p> | |
928 | ||
929 | <p> | |
930 | <b>%cstring_bounded_output(parm, maxsize)</b> | |
931 | </p> | |
932 | ||
933 | <div class="indent"> | |
934 | ||
935 | <p> | |
936 | Turns parameter <tt><em>parm</em></tt> into an output value. The | |
937 | output string is assumed to be NULL-terminated and smaller than | |
938 | <tt><em>maxsize</em></tt> characters. Here is an example: | |
939 | </p> | |
940 | ||
941 | <div class="code"> | |
942 | <pre> | |
943 | %cstring_bounded_output(char *path, 1024); | |
944 | ... | |
945 | void get_path(char *path); | |
946 | </pre> | |
947 | </div> | |
948 | ||
949 | <p> | |
950 | In the target language: | |
951 | </p> | |
952 | ||
953 | <div class="targetlang"> | |
954 | <pre> | |
955 | >>> get_path() | |
956 | /home/beazley/packages/Foo/Bar | |
957 | >>> | |
958 | </pre> | |
959 | </div> | |
960 | ||
961 | <p> | |
962 | Internally, the wrapper function allocates a small buffer (on the stack) of the | |
963 | requested size and passes it as the pointer value. Data stored in the buffer is then | |
964 | returned as a function return value. | |
965 | If the function already returns a value, then the return value and the output string | |
966 | are returned together (multiple return values). <b>If more than <tt><em>maxsize</em></tt> | |
967 | bytes are written, your program will crash with a buffer overflow!</b> | |
968 | </p> | |
969 | ||
970 | </div> | |
971 | ||
972 | <p> | |
973 | <b>%cstring_chunk_output(parm, chunksize)</b> | |
974 | </p> | |
975 | ||
976 | <div class="indent"> | |
977 | ||
978 | <p> | |
979 | Turns parameter <tt><em>parm</em></tt> into an output value. The | |
980 | output string is always <tt><em>chunksize</em></tt> and may contain | |
981 | binary data. Here is an example: | |
982 | </p> | |
983 | ||
984 | <div class="code"> | |
985 | <pre> | |
986 | %cstring_chunk_output(char *packet, PACKETSIZE); | |
987 | ... | |
988 | void get_packet(char *packet); | |
989 | </pre> | |
990 | </div> | |
991 | ||
992 | <p> | |
993 | In the target language: | |
994 | </p> | |
995 | ||
996 | <div class="targetlang"> | |
997 | <pre> | |
998 | >>> get_packet() | |
999 | '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88' | |
1000 | >>> | |
1001 | </pre> | |
1002 | </div> | |
1003 | ||
1004 | <p> | |
1005 | This macro is essentially identical to <tt>%cstring_bounded_output</tt>. The | |
1006 | only difference is that the result is always <tt><em>chunksize</em></tt> characters. | |
1007 | Furthermore, the result can contain binary data. | |
1008 | <b>If more than <tt><em>maxsize</em></tt> | |
1009 | bytes are written, your program will crash with a buffer overflow!</b> | |
1010 | </p> | |
1011 | ||
1012 | </div> | |
1013 | ||
1014 | <p> | |
1015 | <b>%cstring_bounded_mutable(parm, maxsize)</b> | |
1016 | </p> | |
1017 | ||
1018 | <div class="indent"> | |
1019 | ||
1020 | <p> | |
1021 | Turns parameter <tt><em>parm</em></tt> into a mutable string argument. | |
1022 | The input string is assumed to be NULL-terminated and smaller than | |
1023 | <tt><em>maxsize</em></tt> characters. The output string is also assumed | |
1024 | to be NULL-terminated and less than <tt><em>maxsize</em></tt> characters. | |
1025 | </p> | |
1026 | ||
1027 | <div class="code"> | |
1028 | <pre> | |
1029 | %cstring_bounded_mutable(char *ustr, 1024); | |
1030 | ... | |
1031 | void make_upper(char *ustr); | |
1032 | </pre> | |
1033 | </div> | |
1034 | ||
1035 | <p> | |
1036 | In the target language: | |
1037 | </p> | |
1038 | ||
1039 | <div class="targetlang"> | |
1040 | <pre> | |
1041 | >>> make_upper("hello world") | |
1042 | 'HELLO WORLD' | |
1043 | >>> | |
1044 | </pre> | |
1045 | </div> | |
1046 | ||
1047 | <p> | |
1048 | Internally, this macro is almost exactly the same as | |
1049 | <tt>%cstring_bounded_output</tt>. The only difference is that the | |
1050 | parameter accepts an input value that is used to initialize the | |
1051 | internal buffer. It is important to emphasize that this function | |
1052 | does not mutate the string value passed---instead it makes a copy of the | |
1053 | input value, mutates it, and returns it as a result. | |
1054 | <b>If more than <tt><em>maxsize</em></tt> bytes are | |
1055 | written, your program will crash with a buffer overflow!</b> | |
1056 | </p> | |
1057 | ||
1058 | </div> | |
1059 | ||
1060 | <p> | |
1061 | <b>%cstring_mutable(parm [, expansion])</b> | |
1062 | </p> | |
1063 | ||
1064 | <div class="indent"> | |
1065 | ||
1066 | <p> | |
1067 | Turns parameter <tt><em>parm</em></tt> into a mutable string argument. | |
1068 | The input string is assumed to be NULL-terminated. An optional | |
1069 | parameter <tt><em>expansion</em></tt> specifies the number of | |
1070 | extra characters by which the string might grow when it is modified. | |
1071 | The output string is assumed to be NULL-terminated and less than | |
1072 | the size of the input string plus any expansion characters. | |
1073 | </p> | |
1074 | ||
1075 | <div class="code"> | |
1076 | <pre> | |
1077 | %cstring_mutable(char *ustr); | |
1078 | ... | |
1079 | void make_upper(char *ustr); | |
1080 | ||
1081 | %cstring_mutable(char *hstr, HEADER_SIZE); | |
1082 | ... | |
1083 | void attach_header(char *hstr); | |
1084 | </pre> | |
1085 | </div> | |
1086 | ||
1087 | <p> | |
1088 | In the target language: | |
1089 | </p> | |
1090 | ||
1091 | <div class="targetlang"> | |
1092 | <pre> | |
1093 | >>> make_upper("hello world") | |
1094 | 'HELLO WORLD' | |
1095 | >>> attach_header("Hello world") | |
1096 | 'header: Hello world' | |
1097 | >>> | |
1098 | </pre> | |
1099 | </div> | |
1100 | ||
1101 | <p> | |
1102 | This macro differs from <tt>%cstring_bounded_mutable()</tt> in that a | |
1103 | buffer is dynamically allocated (on the heap using | |
1104 | <tt>malloc/new</tt>). This buffer is always large enough to store a | |
1105 | copy of the input value plus any expansion bytes that might have been | |
1106 | requested. | |
1107 | It is important to emphasize that this function | |
1108 | does not directly mutate the string value passed---instead it makes a copy of the | |
1109 | input value, mutates it, and returns it as a result. | |
1110 | <b>If the function expands the result by more than <tt><em>expansion</em></tt> extra | |
1111 | bytes, then the program will crash with a buffer overflow!</b> | |
1112 | </p> | |
1113 | ||
1114 | </div> | |
1115 | ||
1116 | ||
1117 | <p> | |
1118 | <b>%cstring_output_maxsize(parm, maxparm)</b> | |
1119 | </p> | |
1120 | ||
1121 | <div class="indent"> | |
1122 | ||
1123 | <p> | |
1124 | This macro is used to handle bounded character output functions where | |
1125 | both a <tt>char *</tt> and a maximum length parameter are provided. | |
1126 | As input, a user simply supplies the maximum length. | |
1127 | The return value is assumed to be a NULL-terminated string. | |
1128 | </p> | |
1129 | ||
1130 | <div class="code"> | |
1131 | <pre> | |
1132 | %cstring_output_maxsize(char *path, int maxpath); | |
1133 | ... | |
1134 | void get_path(char *path, int maxpath); | |
1135 | </pre> | |
1136 | </div> | |
1137 | ||
1138 | <p> | |
1139 | In the target language: | |
1140 | </p> | |
1141 | ||
1142 | <div class="targetlang"> | |
1143 | <pre> | |
1144 | >>> get_path(1024) | |
1145 | '/home/beazley/Packages/Foo/Bar' | |
1146 | >>> | |
1147 | </pre> | |
1148 | </div> | |
1149 | ||
1150 | <p> | |
1151 | This macro provides a safer alternative for functions that need to | |
1152 | write string data into a buffer. User supplied buffer size is | |
1153 | used to dynamically allocate memory on heap. Results are placed | |
1154 | into that buffer and returned as a string object. | |
1155 | </p> | |
1156 | ||
1157 | </div> | |
1158 | ||
1159 | ||
1160 | ||
1161 | <p> | |
1162 | <b>%cstring_output_withsize(parm, maxparm)</b> | |
1163 | </p> | |
1164 | ||
1165 | <div class="indent"> | |
1166 | ||
1167 | <p> | |
1168 | This macro is used to handle bounded character output functions where | |
1169 | both a <tt>char *</tt> and a pointer <tt>int *</tt> are passed. Initially, | |
1170 | the <tt>int *</tt> parameter points to a value containing the maximum size. | |
1171 | On return, this value is assumed to contain the actual number of bytes. | |
1172 | As input, a user simply supplies the maximum length. The output value is a | |
1173 | string that may contain binary data. | |
1174 | </p> | |
1175 | ||
1176 | <div class="code"> | |
1177 | <pre> | |
1178 | %cstring_output_withsize(char *data, int *maxdata); | |
1179 | ... | |
1180 | void get_data(char *data, int *maxdata); | |
1181 | </pre> | |
1182 | </div> | |
1183 | ||
1184 | <p> | |
1185 | In the target language: | |
1186 | </p> | |
1187 | ||
1188 | <div class="targetlang"> | |
1189 | <pre> | |
1190 | >>> get_data(1024) | |
1191 | 'x627388912' | |
1192 | >>> get_data(1024) | |
1193 | 'xyzzy' | |
1194 | >>> | |
1195 | </pre> | |
1196 | </div> | |
1197 | ||
1198 | <p> | |
1199 | This macro is a somewhat more powerful version of <tt>%cstring_output_chunk()</tt>. Memory | |
1200 | is dynamically allocated and can be arbitrary large. Furthermore, a function can control | |
1201 | how much data is actually returned by changing the value of the <tt>maxparm</tt> argument. | |
1202 | </p> | |
1203 | ||
1204 | </div> | |
1205 | ||
1206 | ||
1207 | <p> | |
1208 | <b>%cstring_output_allocate(parm, release)</b> | |
1209 | </p> | |
1210 | ||
1211 | <div class="indent"> | |
1212 | ||
1213 | <p> | |
1214 | This macro is used to return strings that are allocated within the program and | |
1215 | returned in a parameter of type <tt>char **</tt>. For example: | |
1216 | </p> | |
1217 | ||
1218 | <div class="code"> | |
1219 | <pre> | |
1220 | void foo(char **s) { | |
1221 | *s = (char *) malloc(64); | |
1222 | sprintf(*s, "Hello world\n"); | |
1223 | } | |
1224 | </pre> | |
1225 | </div> | |
1226 | ||
1227 | <p> | |
1228 | The returned string is assumed to be NULL-terminated. <tt><em>release</em></tt> | |
1229 | specifies how the allocated memory is to be released (if applicable). Here is an | |
1230 | example: | |
1231 | </p> | |
1232 | ||
1233 | <div class="code"> | |
1234 | <pre> | |
1235 | %cstring_output_allocate(char **s, free(*$1)); | |
1236 | ... | |
1237 | void foo(char **s); | |
1238 | </pre> | |
1239 | </div> | |
1240 | ||
1241 | <p> | |
1242 | In the target language: | |
1243 | </p> | |
1244 | ||
1245 | <div class="targetlang"> | |
1246 | <pre> | |
1247 | >>> foo() | |
1248 | 'Hello world\n' | |
1249 | >>> | |
1250 | </pre> | |
1251 | </div> | |
1252 | </div> | |
1253 | ||
1254 | ||
1255 | <p> | |
1256 | <b>%cstring_output_allocate_size(parm, szparm, release)</b> | |
1257 | </p> | |
1258 | ||
1259 | <div class="indent"> | |
1260 | ||
1261 | <p> | |
1262 | This macro is used to return strings that are allocated within the program and | |
1263 | returned in two parameters of type <tt>char **</tt> and <tt>int *</tt>. For example: | |
1264 | </p> | |
1265 | ||
1266 | <div class="code"> | |
1267 | <pre> | |
1268 | void foo(char **s, int *sz) { | |
1269 | *s = (char *) malloc(64); | |
1270 | *sz = 64; | |
1271 | // Write some binary data | |
1272 | ... | |
1273 | } | |
1274 | </pre> | |
1275 | </div> | |
1276 | ||
1277 | <p> | |
1278 | The returned string may contain binary data. <tt><em>release</em></tt> | |
1279 | specifies how the allocated memory is to be released (if applicable). Here is an | |
1280 | example: | |
1281 | </p> | |
1282 | ||
1283 | <div class="code"> | |
1284 | <pre> | |
1285 | %cstring_output_allocate_size(char **s, int *slen, free(*$1)); | |
1286 | ... | |
1287 | void foo(char **s, int *slen); | |
1288 | </pre> | |
1289 | </div> | |
1290 | ||
1291 | <p> | |
1292 | In the target language: | |
1293 | </p> | |
1294 | ||
1295 | <div class="targetlang"> | |
1296 | <pre> | |
1297 | >>> foo() | |
1298 | '\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88' | |
1299 | >>> | |
1300 | </pre> | |
1301 | </div> | |
1302 | ||
1303 | <p> | |
1304 | This is the safest and most reliable way to return binary string data in | |
1305 | SWIG. If you have functions that conform to another prototype, you might | |
1306 | consider wrapping them with a helper function. For example, if you had this: | |
1307 | </p> | |
1308 | ||
1309 | <div class="code"> | |
1310 | <pre> | |
1311 | char *get_data(int *len); | |
1312 | </pre> | |
1313 | </div> | |
1314 | ||
1315 | <p> | |
1316 | You could wrap it with a function like this: | |
1317 | </p> | |
1318 | ||
1319 | <div class="code"> | |
1320 | <pre> | |
1321 | void my_get_data(char **result, int *len) { | |
1322 | *result = get_data(len); | |
1323 | } | |
1324 | </pre> | |
1325 | </div> | |
1326 | </div> | |
1327 | ||
1328 | <p> | |
1329 | <b>Comments:</b> | |
1330 | </p> | |
1331 | ||
1332 | <ul> | |
1333 | <li>Support for the <tt>cstring.i</tt> module depends on the target language. Not all | |
1334 | SWIG modules currently support this library. | |
1335 | </li> | |
1336 | ||
1337 | <li>Reliable handling of raw C strings is a delicate topic. There are many ways | |
1338 | to accomplish this in SWIG. This library provides support for a few common techniques. | |
1339 | </li> | |
1340 | ||
1341 | <li>If used in C++, this library uses <tt>new</tt> and <tt>delete []</tt> for memory | |
1342 | allocation. If using ANSI C, the library uses <tt>malloc()</tt> and <tt>free()</tt>. | |
1343 | </li> | |
1344 | ||
1345 | <li>Rather than manipulating <tt>char *</tt> directly, you might consider using a special string | |
1346 | structure or class instead. | |
1347 | </li> | |
1348 | </ul> | |
1349 | ||
1350 | <H2><a name="Library_stl_cpp_library"></a>8.4 STL/C++ Library</H2> | |
1351 | ||
1352 | ||
1353 | <p> | |
1354 | The library modules in this section provide access to parts of the standard C++ library including the STL. | |
1355 | SWIG support for the STL is an ongoing effort. Support is quite comprehensive for some language modules | |
1356 | but some of the lesser used modules do not have quite as much library code written. | |
1357 | </p> | |
1358 | ||
1359 | <p> | |
1360 | The following table shows which C++ classes are supported and the equivalent SWIG interface library file for the C++ library. | |
1361 | </p> | |
1362 | ||
1363 | <table BORDER summary="SWIG C++ library files"> | |
1364 | <tr VALIGN=TOP> | |
1365 | <td><b>C++ class</b></td> | |
1366 | <td><b>C++ Library file</b></td> | |
1367 | <td><b>SWIG Interface library file</b></td> | |
1368 | </tr> | |
1369 | ||
1370 | <tr> <td>std::deque</td> <td>deque</td> <td>std_deque.i</td> </tr> | |
1371 | <tr> <td>std::list</td> <td>list</td> <td>std_list.i</td> </tr> | |
1372 | <tr> <td>std::map</td> <td>map</td> <td>std_map.i</td> </tr> | |
1373 | <tr> <td>std::pair</td> <td>utility</td> <td>std_pair.i</td> </tr> | |
1374 | <tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr> | |
1375 | <tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr> | |
1376 | <tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr> | |
1377 | ||
1378 | </table> | |
1379 | ||
1380 | <p> | |
1381 | The list is by no means complete; some language modules support a subset of the above and some support additional STL classes. | |
1382 | Please look for the library files in the appropriate language library directory. | |
1383 | </p> | |
1384 | ||
1385 | ||
1386 | <H3><a name="Library_nn14"></a>8.4.1 std_string.i</H3> | |
1387 | ||
1388 | ||
1389 | <p> | |
1390 | The <tt>std_string.i</tt> library provides typemaps for converting C++ <tt>std::string</tt> | |
1391 | objects to and from strings in the target scripting language. For example: | |
1392 | </p> | |
1393 | ||
1394 | <div class="code"> | |
1395 | <pre> | |
1396 | %module example | |
1397 | %include "std_string.i" | |
1398 | ||
1399 | std::string foo(); | |
1400 | void bar(const std::string &x); | |
1401 | </pre> | |
1402 | </div> | |
1403 | ||
1404 | <p> | |
1405 | In the target language: | |
1406 | </p> | |
1407 | ||
1408 | <div class="targetlang"> | |
1409 | <pre> | |
1410 | x = foo(); # Returns a string object | |
1411 | bar("Hello World"); # Pass string as std::string | |
1412 | </pre> | |
1413 | </div> | |
1414 | ||
1415 | <p> | |
1416 | This module only supports types <tt>std::string</tt> and | |
1417 | <tt>const std::string &</tt>. Pointers and non-const references | |
1418 | are left unmodified and returned as SWIG pointers. | |
1419 | </p> | |
1420 | ||
1421 | <p> | |
1422 | This library file is fully aware of C++ namespaces. If you export <tt>std::string</tt> or rename | |
1423 | it with a typedef, make sure you include those declarations in your interface. For example: | |
1424 | </p> | |
1425 | ||
1426 | <div class="code"> | |
1427 | <pre> | |
1428 | %module example | |
1429 | %include "std_string.i" | |
1430 | ||
1431 | using namespace std; | |
1432 | typedef std::string String; | |
1433 | ... | |
1434 | void foo(string s, const String &t); // std_string typemaps still applied | |
1435 | </pre> | |
1436 | </div> | |
1437 | ||
1438 | <p> | |
1439 | <b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms. | |
1440 | We're looking into it. | |
1441 | </p> | |
1442 | ||
1443 | <H3><a name="Library_nn15"></a>8.4.2 std_vector.i</H3> | |
1444 | ||
1445 | ||
1446 | <p> | |
1447 | The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL. | |
1448 | Using this library involves the use of the <tt>%template</tt> directive. All you need to do is to | |
1449 | instantiate different versions of <tt>vector</tt> for the types that you want to use. For example: | |
1450 | </p> | |
1451 | ||
1452 | <div class="code"> | |
1453 | <pre> | |
1454 | %module example | |
1455 | %include "std_vector.i" | |
1456 | ||
1457 | namespace std { | |
1458 | %template(vectori) vector<int>; | |
1459 | %template(vectord) vector<double>; | |
1460 | }; | |
1461 | </pre> | |
1462 | </div> | |
1463 | ||
1464 | <p> | |
1465 | When a template <tt>vector<X></tt> is instantiated a number of things happen: | |
1466 | </p> | |
1467 | ||
1468 | <ul> | |
1469 | <li>A class that exposes the C++ API is created in the target language . | |
1470 | This can be used to create objects, invoke methods, etc. This class is | |
1471 | currently a subset of the real STL vector class. | |
1472 | </li> | |
1473 | ||
1474 | <li>Input typemaps are defined for <tt>vector<X></tt>, <tt>const vector<X> &</tt>, and | |
1475 | <tt>const vector<X> *</tt>. For each of these, a pointer <tt>vector<X> *</tt> may be passed or | |
1476 | a native list object in the target language. | |
1477 | </li> | |
1478 | ||
1479 | <li>An output typemap is defined for <tt>vector<X></tt>. In this case, the values in the | |
1480 | vector are expanded into a list object in the target language. | |
1481 | </li> | |
1482 | ||
1483 | <li>For all other variations of the type, the wrappers expect to receive a <tt>vector<X> *</tt> | |
1484 | object in the usual manner. | |
1485 | </li> | |
1486 | ||
1487 | <li>An exception handler for <tt>std::out_of_range</tt> is defined. | |
1488 | </li> | |
1489 | ||
1490 | <li>Optionally, special methods for indexing, item retrieval, slicing, and element assignment | |
1491 | may be defined. This depends on the target language. | |
1492 | </li> | |
1493 | </ul> | |
1494 | ||
1495 | <p> | |
1496 | To illustrate the use of this library, consider the following functions: | |
1497 | </p> | |
1498 | ||
1499 | <div class="code"> | |
1500 | <pre> | |
1501 | /* File : example.h */ | |
1502 | ||
1503 | #include <vector> | |
1504 | #include <algorithm> | |
1505 | #include <functional> | |
1506 | #include <numeric> | |
1507 | ||
1508 | double average(std::vector<int> v) { | |
1509 | return std::accumulate(v.begin(),v.end(),0.0)/v.size(); | |
1510 | } | |
1511 | ||
1512 | std::vector<double> half(const std::vector<double>& v) { | |
1513 | std::vector<double> w(v); | |
1514 | for (unsigned int i=0; i<w.size(); i++) | |
1515 | w[i] /= 2.0; | |
1516 | return w; | |
1517 | } | |
1518 | ||
1519 | void halve_in_place(std::vector<double>& v) { | |
1520 | std::transform(v.begin(),v.end(),v.begin(), | |
1521 | std::bind2nd(std::divides<double>(),2.0)); | |
1522 | } | |
1523 | </pre> | |
1524 | </div> | |
1525 | ||
1526 | <p> | |
1527 | To wrap with SWIG, you might write the following: | |
1528 | </p> | |
1529 | ||
1530 | <div class="code"> | |
1531 | <pre> | |
1532 | %module example | |
1533 | %{ | |
1534 | #include "example.h" | |
1535 | %} | |
1536 | ||
1537 | %include "std_vector.i" | |
1538 | // Instantiate templates used by example | |
1539 | namespace std { | |
1540 | %template(IntVector) vector<int>; | |
1541 | %template(DoubleVector) vector<double>; | |
1542 | } | |
1543 | ||
1544 | // Include the header file with above prototypes | |
1545 | %include "example.h" | |
1546 | </pre> | |
1547 | </div> | |
1548 | ||
1549 | <p> | |
1550 | Now, to illustrate the behavior in the scripting interpreter, consider this Python example: | |
1551 | </p> | |
1552 | ||
1553 | <div class="targetlang"> | |
1554 | <pre> | |
1555 | >>> from example import * | |
1556 | >>> iv = IntVector(4) # Create an vector<int> | |
1557 | >>> for i in range(0,4): | |
1558 | ... iv[i] = i | |
1559 | >>> average(iv) # Call method | |
1560 | 1.5 | |
1561 | >>> average([0,1,2,3]) # Call with list | |
1562 | 1.5 | |
1563 | >>> half([1,2,3]) # Half a list | |
1564 | (0.5,1.0,1.5) | |
1565 | >>> halve_in_place([1,2,3]) # Oops | |
1566 | Traceback (most recent call last): | |
1567 | File "<stdin>", line 1, in ? | |
1568 | TypeError: Type error. Expected _p_std__vectorTdouble_t | |
1569 | >>> dv = DoubleVector(4) | |
1570 | >>> for i in range(0,4): | |
1571 | ... dv[i] = i | |
1572 | >>> halve_in_place(dv) # Ok | |
1573 | >>> for i in dv: | |
1574 | ... print i | |
1575 | ... | |
1576 | 0.0 | |
1577 | 0.5 | |
1578 | 1.0 | |
1579 | 1.5 | |
1580 | >>> dv[20] = 4.5 | |
1581 | Traceback (most recent call last): | |
1582 | File "<stdin>", line 1, in ? | |
1583 | File "example.py", line 81, in __setitem__ | |
1584 | def __setitem__(*args): return apply(examplec.DoubleVector___setitem__,args) | |
1585 | IndexError: vector index out of range | |
1586 | >>> | |
1587 | </pre> | |
1588 | </div> | |
1589 | ||
1590 | <p> | |
1591 | This library module is fully aware of C++ namespaces. If you use vectors with other names, | |
1592 | make sure you include the appropriate <tt>using</tt> or typedef directives. For example: | |
1593 | </p> | |
1594 | ||
1595 | <div class="code"> | |
1596 | <pre> | |
1597 | %include "std_vector.i" | |
1598 | ||
1599 | namespace std { | |
1600 | %template(IntVector) vector<int>; | |
1601 | } | |
1602 | ||
1603 | using namespace std; | |
1604 | typedef std::vector Vector; | |
1605 | ||
1606 | void foo(vector<int> *x, const Vector &x); | |
1607 | </pre> | |
1608 | </div> | |
1609 | ||
1610 | <p> | |
1611 | <b>Note:</b> This module makes use of several advanced SWIG features including templatized typemaps | |
1612 | and template partial specialization. If you are tring to wrap other C++ code with templates, you | |
1613 | might look at the code contained in <tt>std_vector.i</tt>. Alternatively, you can show them the code | |
1614 | if you want to make their head explode. | |
1615 | </p> | |
1616 | ||
1617 | <p> | |
1618 | <b>Note:</b> This module is defined for all SWIG target languages. However argument conversion | |
1619 | details and the public API exposed to the interpreter vary. | |
1620 | </p> | |
1621 | ||
1622 | <p> | |
1623 | <b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio. | |
1624 | </p> | |
1625 | ||
1626 | ||
1627 | <H3><a name="Library_stl_exceptions"></a>8.4.3 STL exceptions</H3> | |
1628 | ||
1629 | ||
1630 | <p> | |
1631 | Many of the STL wrapper functions add parameter checking and will throw a language dependent error/exception | |
1632 | should the values not be valid. The classic example is array bounds checking. | |
1633 | The library wrappers are written to throw a C++ exception in the case of error. | |
1634 | The C++ exception in turn gets converted into an appropriate error/exception for the target language. | |
1635 | By and large this handling should not need customising, however, customisation can easily be achieved by supplying appropriate "throws" typemaps. | |
1636 | For example: | |
1637 | </p> | |
1638 | ||
1639 | <div class="code"> | |
1640 | <pre> | |
1641 | %module example | |
1642 | %include "std_vector.i" | |
1643 | %typemap(throws) std::out_of_range { | |
1644 | // custom exception handler | |
1645 | } | |
1646 | %template(VectInt) std::vector<int>; | |
1647 | </pre> | |
1648 | </div> | |
1649 | ||
1650 | <p> | |
1651 | The custom exception handler might, for example, log the exception then convert it into a specific error/exception for the target language. | |
1652 | </p> | |
1653 | ||
1654 | <p> | |
1655 | When using the STL it is advisable to add in an exception handler to catch all STL exceptions. | |
1656 | The <tt>%exception</tt> directive can be used by placing the following code before any other methods or libraries to be wrapped: | |
1657 | </p> | |
1658 | ||
1659 | <div class="code"> | |
1660 | <pre> | |
1661 | %include "exception.i" | |
1662 | ||
1663 | %exception { | |
1664 | try { | |
1665 | $action | |
1666 | } catch (const std::exception& e) { | |
1667 | SWIG_exception(SWIG_RuntimeError, e.what()); | |
1668 | } | |
1669 | } | |
1670 | </pre> | |
1671 | </div> | |
1672 | ||
1673 | <p> | |
1674 | Any thrown STL exceptions will then be gracefully handled instead of causing a crash. | |
1675 | </p> | |
1676 | ||
1677 | ||
1678 | <H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2> | |
1679 | ||
1680 | ||
1681 | <H3><a name="Library_nn17"></a>8.5.1 exception.i</H3> | |
1682 | ||
1683 | ||
1684 | <p> | |
1685 | The <tt>exception.i</tt> library provides a language-independent function for raising a run-time | |
1686 | exception in the target language. This library is largely used by the SWIG library writers. | |
1687 | If possible, use the error handling scheme available to your target language as there is greater | |
1688 | flexibility in what errors/exceptions can be thrown. | |
1689 | </p> | |
1690 | ||
1691 | <p> | |
1692 | <b><tt>SWIG_exception(int code, const char *message)</tt></b> | |
1693 | </p> | |
1694 | ||
1695 | <div class="indent"> | |
1696 | ||
1697 | <p> | |
1698 | Raises an exception in the target language. <tt>code</tt> is one of the following symbolic | |
1699 | constants: | |
1700 | </p> | |
1701 | ||
1702 | <div class="code"> | |
1703 | <pre> | |
1704 | SWIG_MemoryError | |
1705 | SWIG_IOError | |
1706 | SWIG_RuntimeError | |
1707 | SWIG_IndexError | |
1708 | SWIG_TypeError | |
1709 | SWIG_DivisionByZero | |
1710 | SWIG_OverflowError | |
1711 | SWIG_SyntaxError | |
1712 | SWIG_ValueError | |
1713 | SWIG_SystemError | |
1714 | </pre> | |
1715 | </div> | |
1716 | ||
1717 | <p> | |
1718 | <tt>message</tt> is a string indicating more information about the problem. | |
1719 | </p> | |
1720 | ||
1721 | </div> | |
1722 | ||
1723 | <p> | |
1724 | The primary use of this module is in writing language-independent exception handlers. | |
1725 | For example: | |
1726 | </p> | |
1727 | ||
1728 | <div class="code"> | |
1729 | <pre> | |
1730 | %include "exception.i" | |
1731 | %exception std::vector::getitem { | |
1732 | try { | |
1733 | $action | |
1734 | } catch (std::out_of_range& e) { | |
1735 | SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what())); | |
1736 | } | |
1737 | } | |
1738 | </pre> | |
1739 | </div> | |
1740 | ||
1741 | ||
1742 | </body> | |
1743 | </html> |