PageRenderTime 140ms CodeModel.GetById 26ms RepoModel.GetById 0ms app.codeStats 0ms

/tags/rel-1-3-27/SWIG/Doc/Manual/Arguments.html

#
HTML | 498 lines | 387 code | 109 blank | 2 comment | 0 complexity | 84750f1c7a58b50ac42419d1c0624990 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2. <html>
  3. <head>
  4. <title>Argument Handling</title>
  5. <link rel="stylesheet" type="text/css" href="style.css">
  6. </head>
  7. <body bgcolor="#ffffff">
  8. <H1><a name="Arguments"></a>9 Argument Handling</H1>
  9. <!-- INDEX -->
  10. <div class="sectiontoc">
  11. <ul>
  12. <li><a href="#Arguments_nn2">The typemaps.i library</a>
  13. <ul>
  14. <li><a href="#Arguments_nn3">Introduction</a>
  15. <li><a href="#Arguments_nn4">Input parameters</a>
  16. <li><a href="#Arguments_nn5">Output parameters</a>
  17. <li><a href="#Arguments_nn6">Input/Output parameters</a>
  18. <li><a href="#Arguments_nn7">Using different names</a>
  19. </ul>
  20. <li><a href="#Arguments_nn8">Applying constraints to input values</a>
  21. <ul>
  22. <li><a href="#Arguments_nn9">Simple constraint example</a>
  23. <li><a href="#Arguments_nn10">Constraint methods</a>
  24. <li><a href="#Arguments_nn11">Applying constraints to new datatypes</a>
  25. </ul>
  26. </ul>
  27. </div>
  28. <!-- INDEX -->
  29. <b>Disclaimer: This chapter is under construction.</b>
  30. <p>
  31. In Chapter 3, SWIG's treatment of basic datatypes and pointers was
  32. described. In particular, primitive types such as <tt>int</tt> and
  33. <tt>double</tt> are mapped to corresponding types in the target
  34. language. For everything else, pointers are used to refer to
  35. structures, classes, arrays, and other user-defined datatypes.
  36. However, in certain applications it is desirable to change SWIG's
  37. handling of a specific datatype. For example, you might want to
  38. return multiple values through the arguments of a function. This chapter
  39. describes some of the techniques for doing this.
  40. </p>
  41. <H2><a name="Arguments_nn2"></a>9.1 The typemaps.i library</H2>
  42. <p>
  43. This section describes the <tt>typemaps.i</tt> library file--commonly used to
  44. change certain properties of argument conversion.
  45. </p>
  46. <H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3>
  47. <p>
  48. Suppose you had a C function like this:
  49. </p>
  50. <div class="code"><pre>
  51. void add(double a, double b, double *result) {
  52. *result = a + b;
  53. }
  54. </pre></div>
  55. <p>
  56. From reading the source code, it is clear that the function is storing
  57. a value in the <tt>double *result</tt> parameter. However, since SWIG
  58. does not examine function bodies, it has no way to know that this is
  59. the underlying behavior.
  60. </p>
  61. <p>
  62. One way to deal with this is to use the
  63. <tt>typemaps.i</tt> library file and write interface code like this:
  64. </p>
  65. <div class="code"><pre>
  66. // Simple example using typemaps
  67. %module example
  68. %include "typemaps.i"
  69. %apply double *OUTPUT { double *result };
  70. %inlne %{
  71. extern void add(double a, double b, double *result);
  72. %}
  73. </pre></div>
  74. <p>
  75. The <tt>%apply</tt> directive tells SWIG that you are going to apply
  76. a special type handling rule to a type. The "<tt>double *OUTPUT</tt>" specification is the
  77. name of a rule that defines how to return an output value from an argument of type
  78. <tt>double *</tt>. This rule gets applied to all of the datatypes
  79. listed in curly braces-- in this case "<tt>double *result</tt>".</p>
  80. <p>
  81. When the resulting module is created, you can now use the function
  82. like this (shown for Python):
  83. </p>
  84. <div class="targetlang"><pre>
  85. &gt;&gt;&gt; a = add(3,4)
  86. &gt;&gt;&gt; print a
  87. 7
  88. &gt;&gt;&gt;
  89. </pre></div>
  90. <p>
  91. In this case, you can see how the output value normally returned in
  92. the third argument has magically been transformed into a function
  93. return value. Clearly this makes the function much easier to use
  94. since it is no longer necessary to manufacture a special <tt>double
  95. *</tt> object and pass it to the function somehow.
  96. </p>
  97. <p>
  98. Once a typemap has been applied to a type, it stays in effect for all future occurrences
  99. of the type and name. For example, you could write the following:
  100. </p>
  101. <div class="code"><pre>
  102. %module example
  103. %include "typemaps.i"
  104. %apply double *OUTPUT { double *result };
  105. %inline %{
  106. extern void add(double a, double b, double *result);
  107. extern void sub(double a, double b, double *result);
  108. extern void mul(double a, double b, double *result);
  109. extern void div(double a, double b, double *result);
  110. %}
  111. ...
  112. </pre></div>
  113. <p>
  114. In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the functions that follow.
  115. </p>
  116. <p>
  117. Typemap transformations can even be extended to multiple return values.
  118. For example, consider this code:
  119. </p>
  120. <div class="code">
  121. <pre>
  122. %include "typemaps.i"
  123. %apply int *OUTPUT { int *width, int *height };
  124. // Returns a pair (width,height)
  125. void getwinsize(int winid, int *width, int *height);
  126. </pre>
  127. </div>
  128. <p>
  129. In this case, the function returns multiple values, allowing it to be used like this:
  130. </p>
  131. <div class="targetlang"><pre>
  132. &gt;&gt;&gt; w,h = genwinsize(wid)
  133. &gt;&gt;&gt; print w
  134. 400
  135. &gt;&gt;&gt; print h
  136. 300
  137. &gt;&gt;&gt;
  138. </pre>
  139. </div>
  140. <p>
  141. It should also be noted that although the <tt>%apply</tt> directive is
  142. used to associate typemap rules to datatypes, you can also use the
  143. rule names directly in arguments. For example, you could write this:
  144. </p>
  145. <div class="code"><pre>
  146. // Simple example using typemaps
  147. %module example
  148. %include "typemaps.i"
  149. %{
  150. extern void add(double a, double b, double *OUTPUT);
  151. %}
  152. extern void add(double a, double b, double *OUTPUT);
  153. </pre></div>
  154. <p>
  155. Typemaps stay in effect until they are explicitly deleted or redefined to something
  156. else. To clear a typemap, the <tt>%clear</tt> directive should be used. For example:
  157. </p>
  158. <div class="code">
  159. <pre>
  160. %clear double *result; // Remove all typemaps for double *result
  161. </pre>
  162. </div>
  163. <H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3>
  164. <p>
  165. The following typemaps instruct SWIG that a pointer really only holds a single
  166. input value:
  167. </p>
  168. <div class="code"><pre>
  169. int *INPUT
  170. short *INPUT
  171. long *INPUT
  172. unsigned int *INPUT
  173. unsigned short *INPUT
  174. unsigned long *INPUT
  175. double *INPUT
  176. float *INPUT
  177. </pre></div>
  178. <p>
  179. When used, it allows values to be passed instead of pointers. For example, consider this
  180. function:
  181. </p>
  182. <div class="code"><pre>
  183. double add(double *a, double *b) {
  184. return *a+*b;
  185. }
  186. </pre></div>
  187. <p>
  188. Now, consider this SWIG interface:
  189. </p>
  190. <div class="code"><pre>
  191. %module example
  192. %include "typemaps.i"
  193. ...
  194. %{
  195. extern double add(double *, double *);
  196. %}
  197. extern double add(double *INPUT, double *INPUT);
  198. </pre></div>
  199. <p>
  200. When the function is used in the scripting language interpreter, it will work like this:
  201. </p>
  202. <div class="targetlang"><pre>
  203. result = add(3,4)
  204. </pre></div>
  205. <H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3>
  206. <p>
  207. The following typemap rules tell SWIG that pointer is the output value of a
  208. function. When used, you do not need to supply the argument when
  209. calling the function. Instead, one or more output values are returned.
  210. </p>
  211. <div class="code"><pre>
  212. int *OUTPUT
  213. short *OUTPUT
  214. long *OUTPUT
  215. unsigned int *OUTPUT
  216. unsigned short *OUTPUT
  217. unsigned long *OUTPUT
  218. double *OUTPUT
  219. float *OUTPUT
  220. </pre></div>
  221. <p>
  222. These methods can be used as shown in an earlier example. For example, if you have this C function :</p>
  223. <div class="code"><pre>
  224. void add(double a, double b, double *c) {
  225. *c = a+b;
  226. }
  227. </pre></div>
  228. <p>
  229. A SWIG interface file might look like this :</p>
  230. <div class="code"><pre>
  231. %module example
  232. %include "typemaps.i"
  233. ...
  234. %inline %{
  235. extern void add(double a, double b, double *OUTPUT);
  236. %}
  237. </pre></div>
  238. <p>
  239. In this case, only a single output value is returned, but this is not
  240. a restriction. An arbitrary number of output values can be returned by applying
  241. the output rules to more than one argument (as shown previously).
  242. </p>
  243. <p>
  244. If the function also returns a value, it is returned along with the argument. For example,
  245. if you had this:
  246. </p>
  247. <div class="code"><pre>
  248. extern int foo(double a, double b, double *OUTPUT);
  249. </pre></div>
  250. <p>
  251. The function will return two values like this:
  252. </p>
  253. <div class="targetlang">
  254. <pre>
  255. iresult, dresult = foo(3.5, 2)
  256. </pre>
  257. </div>
  258. <H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3>
  259. <p>
  260. When a pointer serves as both an input and output value you can use
  261. the following typemaps :</p>
  262. <div class="code"><pre>
  263. int *INOUT
  264. short *INOUT
  265. long *INOUT
  266. unsigned int *INOUT
  267. unsigned short *INOUT
  268. unsigned long *INOUT
  269. double *INOUT
  270. float *INOUT
  271. </pre></div>
  272. <p>
  273. A C function that uses this might be something like this:</p>
  274. <div class="code"><pre>
  275. void negate(double *x) {
  276. *x = -(*x);
  277. }
  278. </pre></div>
  279. <p>
  280. To make x function as both and input and output value, declare the
  281. function like this in an interface file :</p>
  282. <div class="code"><pre>
  283. %module example
  284. %include typemaps.i
  285. ...
  286. %{
  287. extern void negate(double *);
  288. %}
  289. extern void negate(double *INOUT);
  290. </pre></div>
  291. <p>
  292. Now within a script, you can simply call the function normally :</p>
  293. <div class="targetlang"><pre>
  294. a = negate(3); # a = -3 after calling this
  295. </pre></div>
  296. <p>
  297. One subtle point of the <tt>INOUT</tt> rule is that many scripting languages
  298. enforce mutability constraints on primitive objects (meaning that simple objects
  299. like integers and strings aren't supposed to change). Because of this, you can't
  300. just modify the object's value in place as the underlying C function does in this example.
  301. Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
  302. rather than directly overwriting the value of the original input object.
  303. </p>
  304. <p>
  305. <b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
  306. SWIG. Backwards compatibility is preserved, but deprecated.
  307. </p>
  308. <H3><a name="Arguments_nn7"></a>9.1.5 Using different names</H3>
  309. <p>
  310. As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>INPUT</tt>, <tt>OUTPUT</tt>, and
  311. <tt>INOUT</tt> typemaps to different argument names. For example:
  312. </p>
  313. <div class="code"><pre>
  314. // Make double *result an output value
  315. %apply double *OUTPUT { double *result };
  316. // Make Int32 *in an input value
  317. %apply int *INPUT { Int32 *in };
  318. // Make long *x inout
  319. %apply long *INOUT {long *x};
  320. </pre></div>
  321. <p>
  322. To clear a rule, the <tt>%clear</tt> directive is used:
  323. </p>
  324. <div class="code"><pre>
  325. %clear double *result;
  326. %clear Int32 *in, long *x;
  327. </pre></div>
  328. <p>
  329. Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the
  330. file or a matching <tt>%clear</tt> declaration.
  331. </p>
  332. <H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2>
  333. <p>
  334. In addition to changing the handling of various input values, it is
  335. also possible to use typemaps to apply constraints. For example, maybe you want to
  336. insure that a value is positive, or that a pointer is non-NULL. This
  337. can be accomplished including the <tt>constraints.i</tt> library file.
  338. </p>
  339. <H3><a name="Arguments_nn9"></a>9.2.1 Simple constraint example</H3>
  340. <p>
  341. The constraints library is best illustrated by the following interface
  342. file :</p>
  343. <div class="code"><pre>
  344. // Interface file with constraints
  345. %module example
  346. %include "constraints.i"
  347. double exp(double x);
  348. double log(double POSITIVE); // Allow only positive values
  349. double sqrt(double NONNEGATIVE); // Non-negative values only
  350. double inv(double NONZERO); // Non-zero values
  351. void free(void *NONNULL); // Non-NULL pointers only
  352. </pre></div>
  353. <p>
  354. The behavior of this file is exactly as you would expect. If any of
  355. the arguments violate the constraint condition, a scripting language
  356. exception will be raised. As a result, it is possible to catch bad
  357. values, prevent mysterious program crashes and so on.</p>
  358. <H3><a name="Arguments_nn10"></a>9.2.2 Constraint methods</H3>
  359. <p>
  360. The following constraints are currently available</p>
  361. <div class="code"><pre>
  362. POSITIVE Any number &gt; 0 (not zero)
  363. NEGATIVE Any number &lt; 0 (not zero)
  364. NONNEGATIVE Any number &gt;= 0
  365. NONPOSITIVE Any number &lt;= 0
  366. NONZERO Nonzero number
  367. NONNULL Non-NULL pointer (pointers only).
  368. </pre></div>
  369. <H3><a name="Arguments_nn11"></a>9.2.3 Applying constraints to new datatypes</H3>
  370. <p>
  371. The constraints library only supports the primitive C datatypes, but it
  372. is easy to apply it to new datatypes using <tt>%apply</tt>. For
  373. example :</p>
  374. <div class="code"><pre>
  375. // Apply a constraint to a Real variable
  376. %apply Number POSITIVE { Real in };
  377. // Apply a constraint to a pointer type
  378. %apply Pointer NONNULL { Vector * };
  379. </pre></div>
  380. <p>
  381. The special types of "Number" and "Pointer" can be applied to any
  382. numeric and pointer variable type respectively. To later remove a
  383. constraint, the <tt>%clear</tt> directive can be used :</p>
  384. <div class="code"><pre>
  385. %clear Real in;
  386. %clear Vector *;
  387. </pre></div>
  388. </body>
  389. </html>