← Back to branch summary

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

« back to all changes in this revision

Viewing changes to Examples/perl5/reference/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/perl5/reference/index.html
 
1
<html>
 
2
<head>
 
3
<title>SWIG:Examples:perl5:reference</title>
 
4
</head>
 
5
 
 
6
<body bgcolor="#ffffff">
 
7
 
 
8
 
 
9
<tt>SWIG/Examples/perl5/reference/</tt>
 
10
<hr>
 
11
 
 
12
<H2>C++ Reference Handling</H2>
 
13
 
 
14
<tt>$Header: /cvs/projects/SWIG/Examples/perl5/reference/index.html,v 1.1 2000/09/01 20:48:27 beazley Exp $</tt><br>
 
15
 
 
16
<p>
 
17
This example tests SWIG's handling of C++ references.  Since C++
 
18
references are closely related to pointers (as both refer to a
 
19
location in memory), SWIG simply collapses all references into
 
20
pointers when creating wrappers.
 
21
 
 
22
<h2>Some examples</h2>
 
23
 
 
24
References are most commonly used as function parameter.  For example,
 
25
you might have an operator like this:
 
26
 
 
27
<blockquote>
 
28
<pre>
 
29
Vector operator+(const Vector &a, const Vector &b) {
 
30
   Vector result;
 
31
   result.x = a.x + b.x;
 
32
   result.y = a.y + b.y;
 
33
   result.z = a.z + b.z;
 
34
   return result;
 
35
}
 
36
</pre>
 
37
</blockquote>
 
38
 
 
39
or a function:
 
40
 
 
41
<blockquote>
 
42
<pre>
 
43
Vector addv(const Vector &a, const Vector &b) {
 
44
   Vector result;
 
45
   result.x = a.x + b.x;
 
46
   result.y = a.y + b.y;
 
47
   result.z = a.z + b.z;
 
48
   return result;
 
49
}
 
50
</pre>
 
51
</blockquote>
 
52
 
 
53
In these cases, SWIG transforms everything into a pointer and creates a wrapper
 
54
that looks like this:
 
55
 
 
56
<blockquote>
 
57
<pre>
 
58
Vector wrap_addv(Vector *a, Vector *b) {
 
59
    return addv(*a,*b);
 
60
}
 
61
</pre>
 
62
</blockquote>
 
63
 
 
64
Occasionally, a reference is used as a return value of a function
 
65
when the return result is to be used as an lvalue in an expression.
 
66
The prototypical example is an operator like this:
 
67
 
 
68
<blockquote>
 
69
<pre>
 
70
Vector &operator[](int index);
 
71
</pre>
 
72
</blockquote>
 
73
 
 
74
or a method:
 
75
 
 
76
<blockquote>
 
77
<pre>
 
78
Vector &get(int index);
 
79
</pre>
 
80
</blockquote>
 
81
 
 
82
For functions returning references, a wrapper like this is created:
 
83
 
 
84
<blockquote>
 
85
<pre>
 
86
Vector *wrap_Object_get(Object *self, int index) {
 
87
    Vector &result = self->get(index);
 
88
    return &result;
 
89
}
 
90
</pre>
 
91
</blockquote>
 
92
 
 
93
The following <a href="example.h">header file</a> contains some class
 
94
definitions with some operators and use of references.
 
95
 
 
96
<h2>SWIG Interface</h2>
 
97
 
 
98
SWIG does NOT support overloaded operators so it can not directly build
 
99
an interface to the classes in the above file.   However, a number of workarounds
 
100
can be made.  For example, an overloaded operator can be stuck behind a function
 
101
call such as the <tt>addv()</tt> function above.  Array access can be handled
 
102
with a pair of set/get functions like this:
 
103
 
 
104
<blockquote>
 
105
<pre>
 
106
class VectorArray {
 
107
public:
 
108
 ...
 
109
   %addmethods {
 
110
    Vector &get(int index) {
 
111
      return (*self)[index];
 
112
    }
 
113
    void set(int index, Vector &a) {
 
114
      (*self)[index] = a;
 
115
    }
 
116
   }
 
117
   ...
 
118
}
 
119
</pre>
 
120
</blockquote>
 
121
 
 
122
Click <a href="example.i">here</a> to see a SWIG interface file with these additions.
 
123
 
 
124
<h2>Sample Perl script</h2>
 
125
 
 
126
Click <a href="example.pl">here</a> to see a script that manipulates some C++ references.
 
127
 
 
128
<h2>Notes:</h2>
 
129
 
 
130
<ul>
 
131
<li>C++ references primarily provide notational convenience for C++
 
132
source code.  However, it doesn't much matter to Perl.
 
133
 
 
134
<p>
 
135
<li>When a program returns a reference, a pointer is returned.
 
136
Unlike return by value, memory is not allocated to hold the
 
137
return result.
 
138
 
 
139
<p>
 
140
<li>SWIG has particular trouble handling various combinations of references
 
141
and pointers.  This is side effect of an old parsing scheme and
 
142
type representation that will be replaced in future versions.
 
143
 
 
144
</ul>
 
145
 
 
146
<hr>
 
147
</body>
 
148
</html>