diff options
| author | Dave Beazley <dave-swig@dabeaz.com> | 2003-11-25 21:18:30 +0000 |
|---|---|---|
| committer | Dave Beazley <dave-swig@dabeaz.com> | 2003-11-25 21:18:30 +0000 |
| commit | 47f612c99a450e59caf8d54c264c4a28f86bff5f (patch) | |
| tree | db0fbaed5bb1a6b1212c15bd28bb318abb78b8ec /Doc/Manual/Contract.html | |
| parent | 60c74da9c697347ed1c038cc8c6d3e647f6cb342 (diff) | |
| download | swig-47f612c99a450e59caf8d54c264c4a28f86bff5f.tar.gz | |
Doc update
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@5411 626c5289-ae23-0410-ae9c-e8d60b6d4f22
Diffstat (limited to 'Doc/Manual/Contract.html')
| -rw-r--r-- | Doc/Manual/Contract.html | 93 |
1 files changed, 88 insertions, 5 deletions
diff --git a/Doc/Manual/Contract.html b/Doc/Manual/Contract.html index 2711788cd..2650d103b 100644 --- a/Doc/Manual/Contract.html +++ b/Doc/Manual/Contract.html @@ -5,10 +5,18 @@ </head> <body bgcolor="#ffffff"> -<H1>Contracts</H1> +<a name="n1"></a><H1>10 Contracts</H1> <!-- INDEX --> +<ul> +<li><a href="#n2">The %contract directive</a> +<li><a href="#n3">%contract and classes</a> +<li><a href="#n4">Constant aggregation and %aggregate_check</a> +<li><a href="#n5">Notes</a> +</ul> <!-- INDEX --> + + A common problem that arises when wrapping C libraries is that of maintaining reliability and checking for errors. The fact of the matter is that many C programs are notorious for not providing error checks. Not only that, @@ -24,7 +32,8 @@ check the output values of a function and more. When one of the rules is violated by a script, a runtime exception is generated rather than having the program continue to execute. -<H2>The %contract directive</H2> +<a name="n2"></a><H2>10.1 The %contract directive</H2> + Contracts are added to a declaration using the %contract directive. Here is a simple example: @@ -73,7 +82,8 @@ RuntimeError: Contract violation: require: (arg1>=0) </pre> </blockquote> -<h2>%contract and classes</h2> +<a name="n3"></a><H2>10.2 %contract and classes</H2> + The <tt>%contract</tt> directive can also be applied to class methods and constructors. For example: @@ -143,10 +153,83 @@ In other words conditions specified for the base class and conditions specified for the derived class all must hold. In the above example, this means that both the arguments to <tt>Spam::bar</tt> must be positive. -<h2>Constant aggregation and %aggregate_check</h2> +<a name="n4"></a><H2>10.3 Constant aggregation and %aggregate_check</H2> + +Consider an interface file that contains the following code: + +<blockquote> +<pre> +#define UP 1 +#define DOWN 2 +#define RIGHT 3 +#define LEFT 4 + +void move(SomeObject *, int direction, int distance); +</pre> +</blockquote> + +One thing you might want to do is impose a constraint on the direction parameter to +make sure it's one of a few accepted values. To do that, SWIG provides an easy to +use macro %aggregate_check() that works like this: + +<blockquote> +<pre> +%aggregate_check(int, check_direction, UP, DOWN, LEFT, RIGHT); +</pre> +</blockquote> + +This merely defines a utility function of the form + +<blockquote> +<pre> +int check_direction(int x); +</pre> +</blockquote> + +That checks the argument x to see if it is one of the values listed. This utility +function can be used in contracts. For example: + +<blockquote> +<pre> +%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT); + +%contract move(SomeObject *, int direction, in) { +require: + check_direction(direction); +} + +#define UP 1 +#define DOWN 2 +#define RIGHT 3 +#define LEFT 4 + +void move(SomeObject *, int direction, int distance); +</pre> +</blockquote> + +Alternatively, it can be used in typemaps and other directives. For example: +<blockquote> +<pre> +%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT); + +%typemap(check) int direction { + if (!check_direction($1)) SWIG_exception(SWIG_ValueError, "Bad direction"); +} + +#define UP 1 +#define DOWN 2 +#define RIGHT 3 +#define LEFT 4 + +void move(SomeObject *, int direction, int distance); +</pre> +</blockquote> + +Regrettably, there is no automatic way to perform similar checks with enums values. Maybe in a future +release. +<a name="n5"></a><H2>10.4 Notes</H2> -<h2>Notes</h2> Contract support was implemented by Songyan (Tiger) Feng and first appeared in SWIG-1.3.20. |