Lib/constraints.i

   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
  18 This library provides support for applying constraints to function
  19 arguments.  Using a constraint, you can restrict arguments to be
  20 positive numbers, non-NULL pointers, and so on.   The following
  21 constraints 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
  33 To use the constraints, you need to "apply" them to specific
  34 function arguments in your code.  This is done using the %apply
  35 directive.   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
  44 Any function argument of the type you specify with the %apply directive
  45 will be checked with the appropriate constraint.   Multiple types may
  46 be specified as follows :
  47
  48   %apply Pointer NONNULL { void *, Vector *, List *, double *};
  49
  50 In this case, all of the types listed would be checked for non-NULL
  51 pointers.
  52
  53 The common datatypes of int, short, long, unsigned int, unsigned long,
  54 unsigned short, unsigned char, signed char, float, and double can be
  55 checked without using the %apply directive by simply using the
  56 constraint name as the parameter name. For example :
  57
  58   double sqrt(double NONNEGATIVE);
  59   double log(double POSITIVE);
  60
  61 If 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