← Back to branch summary

~ubuntu-branches/ubuntu/maverick/swig1.3/maverick

« back to all changes in this revision

Viewing changes to Examples/ruby/value/index.html

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Landschoff
  • Date: 2002-03-29 01:56:07 UTC
  • Revision ID: james.westby@ubuntu.com-20020329015607-c0wt03xu8oy9ioj7
Tags: upstream-1.3.11
Import upstream version 1.3.11

Show diffs side-by-side

added added

removed removed

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