index.html | searchcode

/trunk/Examples/ruby/value/index.html

#
HTML | 114 lines | 86 code | 28 blank | 0 comment | 0 complexity | 8ecafedc3756985850293e5bb5dff257 MD5 | raw file
  1<html>
  2<head>
  3<title>SWIG:Examples:ruby:value</title>
  4</head>
  5
  6<body bgcolor="#ffffff">
  7
  8
  9<tt>SWIG/Examples/ruby/value/</tt>
 10<hr>
 11
 12<H2>Passing and Returning Structures by Value</H2>
 13
 14<p>
 15Occasionally, a C program will manipulate structures by value such as shown in the
 16following code:
 17
 18<blockquote>
 19<pre>
 20/* File : example.c */
 21
 22typedef struct Vector {
 23   double x, y, z;
 24} Vector;
 25
 26double dot_product(Vector a, Vector b) {
 27  return (a.x*b.x + a.y*b.y + a.z*b.z);
 28}
 29
 30Vector vector_add(Vector a, Vector b) {
 31  Vector r;
 32  r.x = a.x + b.x;
 33  r.y = a.y + b.y;
 34  r.z = a.z + b.z;
 35  return r;
 36}
 37</pre>
 38</blockquote>
 39
 40Since SWIG only knows how to manage pointers to structures (not their internal
 41representation), the following translations are made when wrappers are
 42created:
 43
 44<blockquote>
 45<pre>
 46double wrap_dot_product(Vector *a, Vector *b) {
 47    return dot_product(*a,*b);
 48}
 49
 50Vector *wrap_vector_add(Vector *a, Vector *b) {
 51    Vector *r = (Vector *) malloc(sizeof(Vector));
 52    *r = vector_add(*a,*b);
 53    return r;
 54}
 55</pre>
 56</blockquote>
 57
 58The functions are then called using pointers from the scripting language interface.
 59It should also be noted that any function that returns a structure by value results
 60in an implicit memory allocation. This will be a memory leak unless you take steps
 61to free the result (see below).
 62
 63<h2>The SWIG interface</h2>
 64
 65Click <a href="example.i">here</a> to see a SWIG interface file that
 66wraps these two functions.  In this file, there are a few essential features:
 67
 68<ul>
 69<li>A wrapper for the <tt>free()</tt> function is created so that we
 70can clean up the return result created by <tt>vector_add()</tt>
 71function.
 72
 73<p>
 74<li>The %inline directive is used to create a few helper functions for creating new Vector
 75objects and to print out the value (for debugging purposes).
 76</ul>
 77
 78<h2>A Ruby Script</h2>
 79
 80Click <a href="runme.rb">here</a> to see a script that uses these functions from Ruby.
 81
 82<h2>Notes</h2>
 83
 84<ul>
 85<li>When the '<tt>-c++</tt>' option is used, the resulting wrapper code for the return value
 86changes to the following:
 87
 88<blockquote>
 89<pre>
 90Vector *wrap_vector_add(Vector *a, Vector *b) {
 91    Vector *r = new Vector(vector_add(*a,*b));
 92    return r;
 93}
 94</pre>
 95</blockquote>
 96
 97<p>
 98<li>If you define C structure (or C++ class with '<tt>-c++</tt>' option)
 99in the interface file, the SWIG generated wrappers can automaticallyclean
100up the result of return-by-reference by GC.
101
102<p>
103<li>Passing parameters by value like this really isn't the best C programming style.
104If possible, you might change your application to use pointers.
105
106<p>
107<li>Similar translations are made when C++ references are used.
108
109
110</ul>
111
112<hr>
113</body>
114</html>