[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / swig / Arguments.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Argument Handling</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>

<body bgcolor="#ffffff">
<H1><a name="Arguments"></a>9 Argument Handling</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Arguments_nn2">The typemaps.i library</a>
<ul>
<li><a href="#Arguments_nn3">Introduction</a>
<li><a href="#Arguments_nn4">Input parameters</a>
<li><a href="#Arguments_nn5">Output parameters</a>
<li><a href="#Arguments_nn6">Input/Output parameters</a>
<li><a href="#Arguments_nn7">Using different names</a>
</ul>
<li><a href="#Arguments_nn8">Applying constraints to input values</a>
<ul>
<li><a href="#Arguments_nn9">Simple constraint example</a>
<li><a href="#Arguments_nn10">Constraint methods</a>
<li><a href="#Arguments_nn11">Applying constraints to new datatypes</a>
</ul>
</ul>
</div>
<!-- INDEX -->


<b>Disclaimer: This chapter is under construction.</b>

<p>
In Chapter 3, SWIG's treatment of basic datatypes and pointers was
described.  In particular, primitive types such as <tt>int</tt> and
<tt>double</tt> are mapped to corresponding types in the target
language.  For everything else, pointers are used to refer to
structures, classes, arrays, and other user-defined datatypes.
However, in certain applications it is desirable to change SWIG's
handling of a specific datatype. For example, you might want to
return multiple values through the arguments of a function.  This chapter
describes some of the techniques for doing this.
</p>

<H2><a name="Arguments_nn2"></a>9.1 The typemaps.i library</H2>


<p>
This section describes the <tt>typemaps.i</tt> library file--commonly used to
change certain properties of argument conversion.
</p>

<H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3>


<p>
Suppose you had a C function like this:
</p>

<div class="code"><pre>
void add(double a, double b, double *result) {
	*result = a + b;
}
</pre></div>

<p>
From reading the source code, it is clear that the function is storing
a value in the <tt>double *result</tt> parameter.   However, since SWIG
does not examine function bodies, it has no way to know that this is
the underlying behavior.
</p>

<p>
One way to deal with this is to use the 
<tt>typemaps.i</tt> library file and write interface code like this:
</p>

<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"

%apply double *OUTPUT { double *result };
%inlne %{
extern void add(double a, double b, double *result);
%}
</pre></div>

<p>
The <tt>%apply</tt> directive tells SWIG that you are going to apply
a special type handling rule to a type. The "<tt>double *OUTPUT</tt>" specification is the
name of a rule that defines how to return an output value from an argument of type
<tt>double *</tt>. This rule gets applied to all of the datatypes
listed in curly braces-- in this case "<tt>double *result</tt>".</p>

<p>
When the resulting module is created, you can now use the function
like this (shown for Python):
</p>

<div class="targetlang"><pre>
&gt;&gt;&gt; a = add(3,4)
&gt;&gt;&gt; print a
7
&gt;&gt;&gt;
</pre></div>

<p>
In this case, you can see how the output value normally returned in
the third argument has magically been transformed into a function
return value.  Clearly this makes the function much easier to use
since it is no longer necessary to manufacture a special <tt>double
*</tt> object and pass it to the function somehow.
</p>

<p>
Once a typemap has been applied to a type, it stays in effect for all future occurrences
of the type and name.  For example, you could write the following:
</p>

<div class="code"><pre>
%module example
%include "typemaps.i"

%apply double *OUTPUT { double *result };

%inline %{
extern void add(double a, double b, double *result);
extern void sub(double a, double b, double *result);
extern void mul(double a, double b, double *result);
extern void div(double a, double b, double *result);
%}
...
</pre></div>

<p>
In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the functions that follow.
</p>

<p>
Typemap transformations can even be extended to multiple return values.
For example, consider this code:
</p>

<div class="code">
<pre>
%include "typemaps.i"
%apply int *OUTPUT { int *width, int *height };

// Returns a pair (width,height)
void getwinsize(int winid, int *width, int *height);
</pre>
</div>

<p>
In this case, the function returns multiple values, allowing it to be used like this:
</p>

<div class="targetlang"><pre>
&gt;&gt;&gt; w,h = genwinsize(wid)
&gt;&gt;&gt; print w
400
&gt;&gt;&gt; print h
300
&gt;&gt;&gt;
</pre>
</div>

<p>
It should also be noted that although the <tt>%apply</tt> directive is
used to associate typemap rules to datatypes, you can also use the
rule names directly in arguments.  For example, you could write this:
</p>

<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"

%{
extern void add(double a, double b, double *OUTPUT);
%}
extern void add(double a, double b, double *OUTPUT);
</pre></div>

<p>
Typemaps stay in effect until they are explicitly deleted or redefined to something
else.   To clear a typemap, the <tt>%clear</tt> directive should be used.  For example:
</p>

<div class="code">
<pre>
%clear double *result;      // Remove all typemaps for double *result
</pre>
</div>

<H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3>


<p>
The following typemaps instruct SWIG that a pointer really only holds a single
input value:
</p>

<div class="code"><pre>
int *INPUT		
short *INPUT
long *INPUT
unsigned int *INPUT
unsigned short *INPUT
unsigned long *INPUT
double *INPUT
float *INPUT
</pre></div>

<p>
When used, it allows values to be passed instead of pointers.  For example, consider this
function:
</p>

<div class="code"><pre>
double add(double *a, double *b) {
	return *a+*b;
}
</pre></div>

<p>
Now, consider this SWIG interface:
</p>

<div class="code"><pre>
%module example
%include "typemaps.i"
...
%{
extern double add(double *, double *);
%}
extern double add(double *INPUT, double *INPUT);

</pre></div>

<p>
When the function is used in the scripting language interpreter, it will work like this:
</p>

<div class="targetlang"><pre>
result = add(3,4)
</pre></div>

<H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3>


<p>
The following typemap rules tell SWIG that pointer is the output value of a
function. When used, you do not need to supply the argument when
calling the function. Instead, one or more output values are returned. 
</p>

<div class="code"><pre>
int *OUTPUT
short *OUTPUT
long *OUTPUT
unsigned int *OUTPUT
unsigned short *OUTPUT
unsigned long *OUTPUT
double *OUTPUT
float *OUTPUT

</pre></div>
<p>
These methods can be used as shown in an earlier example. For example, if you have this C function :</p>

<div class="code"><pre>
void add(double a, double b, double *c) {
	*c = a+b;
}
</pre></div>

<p>
A SWIG interface file might look like this :</p>

<div class="code"><pre>
%module example
%include "typemaps.i"
...
%inline %{
extern void add(double a, double b, double *OUTPUT);
%}

</pre></div>

<p>
In this case, only a single output value is returned, but this is not
a restriction.  An arbitrary number of output values can be returned by applying
the output rules to more than one argument (as shown previously).
</p>

<p>
If the function also returns a value, it is returned along with the argument. For example,
if you had this:
</p>

<div class="code"><pre>
extern int foo(double a, double b, double *OUTPUT);
</pre></div>

<p>
The function will return two values like this:
</p>

<div class="targetlang">
<pre>
iresult, dresult = foo(3.5, 2)
</pre>
</div>

<H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3>


<p>
When a pointer serves as both an input and output value you can use
the following typemaps :</p>

<div class="code"><pre>
int *INOUT
short *INOUT
long *INOUT
unsigned int *INOUT
unsigned short *INOUT
unsigned long *INOUT
double *INOUT
float *INOUT

</pre></div>

<p>
A C function that uses this might be something like this:</p>

<div class="code"><pre>
void negate(double *x) {
	*x = -(*x);
}

</pre></div>

<p>
To make x function as both and input and output value, declare the
function like this in an interface file :</p>

<div class="code"><pre>
%module example
%include typemaps.i
...
%{
extern void negate(double *);
%}
extern void negate(double *INOUT);

</pre></div>

<p>
Now within a script, you can simply call the function normally :</p>

<div class="targetlang"><pre>
a = negate(3);         # a = -3 after calling this
</pre></div>

<p>
One subtle point of the <tt>INOUT</tt> rule is that many scripting languages
enforce mutability constraints on primitive objects (meaning that simple objects
like integers and strings aren't supposed to change).   Because of this, you can't
just modify the object's value in place as the underlying C function does in this example.
Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
rather than directly overwriting the value of the original input object.
</p>

<p>
<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
SWIG.  Backwards compatibility is preserved, but deprecated.
</p>

<H3><a name="Arguments_nn7"></a>9.1.5 Using different names</H3>


<p>
As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>INPUT</tt>, <tt>OUTPUT</tt>, and
<tt>INOUT</tt> typemaps to different argument names.  For example:
</p>

<div class="code"><pre>
// Make double *result an output value
%apply double *OUTPUT { double *result };

// Make Int32 *in an input value
%apply int *INPUT { Int32 *in };

// Make long *x inout
%apply long *INOUT {long *x};

</pre></div>

<p>
To clear a rule, the <tt>%clear</tt> directive is used:
</p>

<div class="code"><pre>
%clear double *result;
%clear Int32 *in, long *x;
</pre></div>

<p>
Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the
file or a matching <tt>%clear</tt> declaration.
</p>

<H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2>


<p>
In addition to changing the handling of various input values, it is
also possible to use typemaps to apply constraints. For example, maybe you want to
insure that a value is positive, or that a pointer is non-NULL. This
can be accomplished including the <tt>constraints.i</tt> library file.
</p>

<H3><a name="Arguments_nn9"></a>9.2.1 Simple constraint example</H3>


<p>
The constraints library is best illustrated by the following interface
file :</p>

<div class="code"><pre>
// Interface file with constraints
%module example
%include "constraints.i"

double exp(double x);
double log(double POSITIVE);         // Allow only positive values
double sqrt(double NONNEGATIVE);     // Non-negative values only
double inv(double NONZERO);          // Non-zero values
void   free(void *NONNULL);          // Non-NULL pointers only

</pre></div>

<p>
The behavior of this file is exactly as you would expect. If any of
the arguments violate the constraint condition, a scripting language
exception will be raised. As a result, it is possible to catch bad
values, prevent mysterious program crashes and so on.</p>

<H3><a name="Arguments_nn10"></a>9.2.2 Constraint methods</H3>


<p>
The following constraints are currently available</p>

<div class="code"><pre>
POSITIVE                     Any number &gt; 0 (not zero)
NEGATIVE                     Any number &lt; 0 (not zero)
NONNEGATIVE                  Any number &gt;= 0
NONPOSITIVE                  Any number &lt;= 0
NONZERO                      Nonzero number
NONNULL                      Non-NULL pointer (pointers only).

</pre></div>

<H3><a name="Arguments_nn11"></a>9.2.3 Applying constraints to new datatypes</H3>


<p>
The constraints library only supports the primitive C datatypes, but it
is easy to apply it to new datatypes using <tt>%apply</tt>. For
example :</p>

<div class="code"><pre>
// Apply a constraint to a Real variable
%apply Number POSITIVE { Real in };

// Apply a constraint to a pointer type
%apply Pointer NONNULL { Vector * };

</pre></div>

<p>
The special types of "Number" and "Pointer" can be applied to any
numeric and pointer variable type respectively. To later remove a
constraint, the <tt>%clear</tt> directive can be used :</p>

<div class="code"><pre>
%clear Real in;
%clear Vector *;
</pre></div>

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