/tags/ttn-post-libtool-1-4-3-upgrade/SWIG/Examples/perl5/pointer/index.html

# · HTML · 173 lines · 138 code · 35 blank · 0 comment · 0 complexity · 379f7401de0a47a93d9ba362aab74da6 MD5 · raw file

  1. <html>
  2. <head>
  3. <title>SWIG:Examples:perl5:pointer</title>
  4. </head>
  5. <body bgcolor="#ffffff">
  6. <tt>SWIG/Examples/perl5/pointer/</tt>
  7. <hr>
  8. <H2>Simple Pointer Handling</H2>
  9. <tt>$Header$</tt><br>
  10. <p>
  11. This example illustrates a couple of techniques for handling
  12. simple pointers in SWIG. The prototypical example is a C function
  13. that operates on pointers such as this:
  14. <blockquote>
  15. <pre>
  16. void add(int *x, int *y, int *r) {
  17. *r = *x + *y;
  18. }
  19. </pre>
  20. </blockquote>
  21. By default, SWIG wraps this function exactly as specified and creates
  22. an interface that expects pointer objects for arguments. The only
  23. problem is how does one go about creating these objects from a script?
  24. <h2>Possible Solutions</h2>
  25. <ul>
  26. <li>Write some helper functions to explicitly create objects. For
  27. example:
  28. <blockquote>
  29. <pre>
  30. int *new_int(int ivalue) {
  31. int *i = (int *) malloc(sizeof(ivalue));
  32. *i = ivalue;
  33. return i;
  34. }
  35. int get_int(int *i) {
  36. return *i;
  37. }
  38. void delete_int(int *i) {
  39. free(i);
  40. }
  41. </pre>
  42. </blockquote>
  43. Now, in a script you would do this:
  44. <blockquote>
  45. <pre>
  46. $a = new_int(37);
  47. $b = new_int(42);
  48. $c = new_int(0):
  49. add($a,$b,$c);
  50. $r = get_int($c);
  51. print "Result = $r\n";
  52. delete_int($a);
  53. delete_int($b);
  54. delete_int($c);
  55. </pre>
  56. </blockquote>
  57. <p>
  58. <li>Use the SWIG pointer library. For example, in the interface file
  59. you would do this:
  60. <blockquote>
  61. <pre>
  62. %include "pointer.i"
  63. </pre>
  64. </blockquote?
  65. and in a script you would do this:
  66. <blockquote>
  67. <pre>
  68. $a = ptrcreate("int",37);
  69. $b = ptrcreate("int",42);
  70. $c = ptrcreate("int");
  71. add($a,$b,$c);
  72. $r = ptrvalue($c);
  73. print "Result = $r\n";
  74. ptrfree($a);
  75. ptrfree($b);
  76. ptrfree($c);
  77. </pre>
  78. </blockquote>
  79. The advantage to using the pointer library is that it unifies some of the helper
  80. functions behind a common set of names. For example, the same set of functions work
  81. with int, double, float, and other fundamental types.
  82. <p>
  83. <li>Use the SWIG typemap library. This library allows you to completely
  84. change the way arguments are processed by SWIG. For example:
  85. <blockquote>
  86. <pre>
  87. %include "typemaps.i"
  88. void add(int *INPUT, int *INPUT, int *OUTPUT);
  89. </pre>
  90. </blockquote>
  91. And in a script:
  92. <blockquote>
  93. <pre>
  94. $r = add(37,42);
  95. print "Result = $r\n";
  96. </pre>
  97. </blockquote>
  98. Needless to say, this is substantially easier.
  99. <p>
  100. <li>A final alternative is to use the typemaps library in combination
  101. with the %apply directive. This allows you to change the names of parameters
  102. that behave as input or output parameters. For example:
  103. <blockquote>
  104. <pre>
  105. %include "typemaps.i"
  106. %apply int *INPUT {int *x, int *y};
  107. %apply int *OUTPUT {int *r};
  108. void add(int *x, int *y, int *r);
  109. void sub(int *x, int *y, int *r);
  110. void mul(int *x, int *y, int *r);
  111. ... etc ...
  112. </pre>
  113. </blockquote>
  114. </ul>
  115. <h2>Example</h2>
  116. The following example illustrates the use of these features for pointer
  117. extraction.
  118. <ul>
  119. <li> <a href="example.c">example.c</a> (C Source)
  120. <li> <a href="example.i">example.i</a> (Swig interface)
  121. <li> <a href="example.pl">example.pl</a> (Perl Script)
  122. </ul>
  123. <h2>Notes</h2>
  124. <ul>
  125. <li>Since pointers are used for so many different things (arrays, output values,
  126. etc...) the complexity of pointer handling can be as complicated as you want to
  127. make it.
  128. <p>
  129. <li>More documentation on the typemaps.i and pointer.i library files can be
  130. found in the SWIG user manual. The files also contain documentation.
  131. <p>
  132. <li>The pointer.i library is designed primarily for convenience. If you
  133. are concerned about performance, you probably want to use a different
  134. approach.
  135. </ul>
  136. <hr>
  137. </body>
  138. </html>