1/* -----------------------------------------------------------------------------
2 * See the LICENSE file for information on copyright, usage and redistribution
3 * of SWIG, and the README file for authors - http://www.swig.org/release.html.
4 *
5 * constraints.i
6 *
7 * SWIG constraints library.
8 *
9 * SWIG library file containing typemaps for implementing various kinds of
10 * constraints.  Depends upon the SWIG exception library for generating
11 * errors in a language-independent manner.
12 * ----------------------------------------------------------------------------- */
13
14#ifdef AUTODOC
15%text %{
16%include <constraints.i>
17
18This library provides support for applying constraints to function
19arguments.  Using a constraint, you can restrict arguments to be
20positive numbers, non-NULL pointers, and so on.   The following
21constraints are available :
22
23      Number  POSITIVE        - Positive number (not zero)
24      Number  NEGATIVE        - Negative number (not zero)
25      Number  NONZERO         - Nonzero number
26      Number  NONNEGATIVE     - Positive number (including zero)
27      Number  NONPOSITIVE     - Negative number (including zero)
28      Pointer NONNULL         - Non-NULL pointer
29      Pointer ALIGN8          - 8-byte aligned pointer
30      Pointer ALIGN4          - 4-byte aligned pointer
31      Pointer ALIGN2          - 2-byte aligned pointer
32
33To use the constraints, you need to "apply" them to specific
34function arguments in your code.  This is done using the %apply
35directive.   For example :
36
37  %apply Number NONNEGATIVE { double nonneg };
38  double sqrt(double nonneg);         // Name of argument must match
39
40  %apply Pointer NONNULL { void *ptr };
41  void *malloc(int POSITIVE);       // May return a NULL pointer
42  void free(void *ptr);             // May not accept a NULL pointer
43
44Any function argument of the type you specify with the %apply directive
45will be checked with the appropriate constraint.   Multiple types may
46be specified as follows :
47
48  %apply Pointer NONNULL { void *, Vector *, List *, double *};
49
50In this case, all of the types listed would be checked for non-NULL
51pointers.
52
53The common datatypes of int, short, long, unsigned int, unsigned long,
54unsigned short, unsigned char, signed char, float, and double can be
55checked without using the %apply directive by simply using the
56constraint name as the parameter name. For example :
57
58  double sqrt(double NONNEGATIVE);
59  double log(double POSITIVE);
60
61If you have used typedef to change type-names, you can also do this :
62
63  %apply double { Real };       // Make everything defined for doubles
64                                // work for Reals.
65  Real sqrt(Real NONNEGATIVE);
66  Real log(Real POSITIVE);
67
68%}
69#endif
70
71%include <exception.i>
72
73#ifdef SWIGCSHARP
74// Required attribute for C# exception handling
75#define SWIGCSHARPCANTHROW , canthrow=1
76#else
77#define SWIGCSHARPCANTHROW
78#endif
79
80
81// Positive numbers
82
83%typemap(check SWIGCSHARPCANTHROW)
84                int               POSITIVE,
85                short             POSITIVE,
86                long              POSITIVE,
87                unsigned int      POSITIVE,
88                unsigned short    POSITIVE,
89                unsigned long     POSITIVE,
90                signed char       POSITIVE,
91                unsigned char     POSITIVE,
92                float             POSITIVE,
93                double            POSITIVE,
94                Number            POSITIVE
95{
96  if ($1 <= 0) {
97    SWIG_exception(SWIG_ValueError,"Expected a positive value.");
98  }
99}
100
101// Negative numbers
102
103%typemap(check SWIGCSHARPCANTHROW)
104                int               NEGATIVE,
105                short             NEGATIVE,
106                long              NEGATIVE,
107                unsigned int      NEGATIVE,
108                unsigned short    NEGATIVE,
109                unsigned long     NEGATIVE,
110                signed char       NEGATIVE,
111                unsigned char     NEGATIVE,
112                float             NEGATIVE,
113                double            NEGATIVE,
114                Number            NEGATIVE
115{
116  if ($1 >= 0) {
117    SWIG_exception(SWIG_ValueError,"Expected a negative value.");
118  }
119}
120
121// Nonzero numbers
122
123%typemap(check SWIGCSHARPCANTHROW)
124                int               NONZERO,
125                short             NONZERO,
126                long              NONZERO,
127                unsigned int      NONZERO,
128                unsigned short    NONZERO,
129                unsigned long     NONZERO,
130                signed char       NONZERO,
131                unsigned char     NONZERO,
132                float             NONZERO,
133                double            NONZERO,
134                Number            NONZERO
135{
136  if ($1 == 0) {
137    SWIG_exception(SWIG_ValueError,"Expected a nonzero value.");
138  }
139}
140
141// Nonnegative numbers
142
143%typemap(check SWIGCSHARPCANTHROW)
144                int               NONNEGATIVE,
145                short             NONNEGATIVE,
146                long              NONNEGATIVE,
147                unsigned int      NONNEGATIVE,
148                unsigned short    NONNEGATIVE,
149                unsigned long     NONNEGATIVE,
150                signed char       NONNEGATIVE,
151                unsigned char     NONNEGATIVE,
152                float             NONNEGATIVE,
153                double            NONNEGATIVE,
154                Number            NONNEGATIVE
155{
156  if ($1 < 0) {
157    SWIG_exception(SWIG_ValueError,"Expected a non-negative value.");
158  }
159}
160
161// Nonpositive numbers
162
163%typemap(check SWIGCSHARPCANTHROW)
164                int               NONPOSITIVE,
165                short             NONPOSITIVE,
166                long              NONPOSITIVE,
167                unsigned int      NONPOSITIVE,
168                unsigned short    NONPOSITIVE,
169                unsigned long     NONPOSITIVE,
170                signed char       NONPOSITIVE,
171                unsigned char     NONPOSITIVE,
172                float             NONPOSITIVE,
173                double            NONPOSITIVE,
174                Number            NONPOSITIVE
175{
176  if ($1 > 0) {
177    SWIG_exception(SWIG_ValueError,"Expected a non-positive value.");
178  }
179}
180
181// Non-NULL pointer
182
183%typemap(check SWIGCSHARPCANTHROW)
184                void *            NONNULL,
185                Pointer           NONNULL
186{
187  if (!$1) {
188    SWIG_exception(SWIG_ValueError,"Received a NULL pointer.");
189  }
190}
191
192// Aligned pointers
193
194%typemap(check SWIGCSHARPCANTHROW)
195                void *            ALIGN8,
196                Pointer           ALIGN8
197{
198   unsigned long long tmp;
199   tmp = (unsigned long long) $1;
200   if (tmp & 7) {
201     SWIG_exception(SWIG_ValueError,"Pointer must be 8-byte aligned.");
202   }
203}
204
205%typemap(check SWIGCSHARPCANTHROW)
206                void *            ALIGN4,
207                Pointer           ALIGN4
208{
209   unsigned long long tmp;
210   tmp = (unsigned long long) $1;
211   if (tmp & 3) {
212     SWIG_exception(SWIG_ValueError,"Pointer must be 4-byte aligned.");
213   }
214}
215
216%typemap(check SWIGCSHARPCANTHROW)
217                void *            ALIGN2,
218                Pointer           ALIGN2
219{
220   unsigned long long tmp;
221   tmp = (unsigned long long) $1;
222   if (tmp & 1) {
223     SWIG_exception(SWIG_ValueError,"Pointer must be 2-byte aligned.");
224   }
225}
226
227
228