|
| 1 | +/* intprops.h -- properties of integer types |
| 2 | +
|
| 3 | + Copyright (C) 2001-2024 Free Software Foundation, Inc. |
| 4 | +
|
| 5 | + This program is free software: you can redistribute it and/or modify it |
| 6 | + under the terms of the GNU Lesser General Public License as published |
| 7 | + by the Free Software Foundation; either version 2.1 of the License, or |
| 8 | + (at your option) any later version. |
| 9 | +
|
| 10 | + This program is distributed in the hope that it will be useful, |
| 11 | + but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | + GNU Lesser General Public License for more details. |
| 14 | +
|
| 15 | + You should have received a copy of the GNU Lesser General Public License |
| 16 | + along with this program. If not, see <https://www.gnu.org/licenses/>. */ |
| 17 | + |
| 18 | +#ifndef _GL_INTPROPS_H |
| 19 | +#define _GL_INTPROPS_H |
| 20 | + |
| 21 | +#include "intprops-internal.h" |
| 22 | + |
| 23 | +/* The extra casts in the following macros work around compiler bugs, |
| 24 | + e.g., in Cray C 5.0.3.0. */ |
| 25 | + |
| 26 | +/* True if the arithmetic type T is an integer type. bool counts as |
| 27 | + an integer. */ |
| 28 | +#define TYPE_IS_INTEGER(t) ((t) 1.5 == 1) |
| 29 | + |
| 30 | +/* True if the real type T is signed. */ |
| 31 | +#define TYPE_SIGNED(t) _GL_TYPE_SIGNED (t) |
| 32 | + |
| 33 | +/* Return 1 if the real expression E, after promotion, has a |
| 34 | + signed or floating type. Do not evaluate E. */ |
| 35 | +#define EXPR_SIGNED(e) _GL_EXPR_SIGNED (e) |
| 36 | + |
| 37 | + |
| 38 | +/* Minimum and maximum values for integer types and expressions. */ |
| 39 | + |
| 40 | +/* The width in bits of the integer type or expression T. |
| 41 | + Do not evaluate T. T must not be a bit-field expression. |
| 42 | + Padding bits are not supported; this is checked at compile-time below. */ |
| 43 | +#define TYPE_WIDTH(t) _GL_TYPE_WIDTH (t) |
| 44 | + |
| 45 | +/* The maximum and minimum values for the integer type T. */ |
| 46 | +#define TYPE_MINIMUM(t) ((t) ~ TYPE_MAXIMUM (t)) |
| 47 | +#define TYPE_MAXIMUM(t) \ |
| 48 | + ((t) (! TYPE_SIGNED (t) \ |
| 49 | + ? (t) -1 \ |
| 50 | + : ((((t) 1 << (TYPE_WIDTH (t) - 2)) - 1) * 2 + 1))) |
| 51 | + |
| 52 | +/* Bound on length of the string representing an unsigned integer |
| 53 | + value representable in B bits. log10 (2.0) < 146/485. The |
| 54 | + smallest value of B where this bound is not tight is 2621. */ |
| 55 | +#define INT_BITS_STRLEN_BOUND(b) (((b) * 146 + 484) / 485) |
| 56 | + |
| 57 | +/* Bound on length of the string representing an integer type or expression T. |
| 58 | + T must not be a bit-field expression. |
| 59 | +
|
| 60 | + Subtract 1 for the sign bit if T is signed, and then add 1 more for |
| 61 | + a minus sign if needed. |
| 62 | +
|
| 63 | + Because _GL_SIGNED_TYPE_OR_EXPR sometimes returns 1 when its argument is |
| 64 | + unsigned, this macro may overestimate the true bound by one byte when |
| 65 | + applied to unsigned types of size 2, 4, 16, ... bytes. */ |
| 66 | +#define INT_STRLEN_BOUND(t) \ |
| 67 | + (INT_BITS_STRLEN_BOUND (TYPE_WIDTH (t) - _GL_SIGNED_TYPE_OR_EXPR (t)) \ |
| 68 | + + _GL_SIGNED_TYPE_OR_EXPR (t)) |
| 69 | + |
| 70 | +/* Bound on buffer size needed to represent an integer type or expression T, |
| 71 | + including the terminating null. T must not be a bit-field expression. */ |
| 72 | +#define INT_BUFSIZE_BOUND(t) (INT_STRLEN_BOUND (t) + 1) |
| 73 | + |
| 74 | + |
| 75 | +/* Range overflow checks. |
| 76 | +
|
| 77 | + The INT_<op>_RANGE_OVERFLOW macros return 1 if the corresponding C |
| 78 | + operators overflow arithmetically when given the same arguments. |
| 79 | + These macros do not rely on undefined or implementation-defined behavior. |
| 80 | + Although their implementations are simple and straightforward, |
| 81 | + they are harder to use and may be less efficient than the |
| 82 | + INT_<op>_WRAPV, INT_<op>_OK, and INT_<op>_OVERFLOW macros described below. |
| 83 | +
|
| 84 | + Example usage: |
| 85 | +
|
| 86 | + long int i = ...; |
| 87 | + long int j = ...; |
| 88 | + if (INT_MULTIPLY_RANGE_OVERFLOW (i, j, LONG_MIN, LONG_MAX)) |
| 89 | + printf ("multiply would overflow"); |
| 90 | + else |
| 91 | + printf ("product is %ld", i * j); |
| 92 | +
|
| 93 | + Restrictions on *_RANGE_OVERFLOW macros: |
| 94 | +
|
| 95 | + These macros do not check for all possible numerical problems or |
| 96 | + undefined or unspecified behavior: they do not check for division |
| 97 | + by zero, for bad shift counts, or for shifting negative numbers. |
| 98 | +
|
| 99 | + These macros may evaluate their arguments zero or multiple times, |
| 100 | + so the arguments should not have side effects. The arithmetic |
| 101 | + arguments (including the MIN and MAX arguments) must be of the same |
| 102 | + integer type after the usual arithmetic conversions, and the type |
| 103 | + must have minimum value MIN and maximum MAX. Unsigned types should |
| 104 | + use a zero MIN of the proper type. |
| 105 | +
|
| 106 | + Because all arguments are subject to integer promotions, these |
| 107 | + macros typically do not work on types narrower than 'int'. |
| 108 | +
|
| 109 | + These macros are tuned for constant MIN and MAX. For commutative |
| 110 | + operations such as A + B, they are also tuned for constant B. */ |
| 111 | + |
| 112 | +/* Return 1 if A + B would overflow in [MIN,MAX] arithmetic. |
| 113 | + See above for restrictions. */ |
| 114 | +#define INT_ADD_RANGE_OVERFLOW(a, b, min, max) \ |
| 115 | + ((b) < 0 \ |
| 116 | + ? (a) < (min) - (b) \ |
| 117 | + : (max) - (b) < (a)) |
| 118 | + |
| 119 | +/* Return 1 if A - B would overflow in [MIN,MAX] arithmetic. |
| 120 | + See above for restrictions. */ |
| 121 | +#define INT_SUBTRACT_RANGE_OVERFLOW(a, b, min, max) \ |
| 122 | + ((b) < 0 \ |
| 123 | + ? (max) + (b) < (a) \ |
| 124 | + : (a) < (min) + (b)) |
| 125 | + |
| 126 | +/* Return 1 if - A would overflow in [MIN,MAX] arithmetic. |
| 127 | + See above for restrictions. */ |
| 128 | +#define INT_NEGATE_RANGE_OVERFLOW(a, min, max) \ |
| 129 | + _GL_INT_NEGATE_RANGE_OVERFLOW (a, min, max) |
| 130 | + |
| 131 | +/* Return 1 if A * B would overflow in [MIN,MAX] arithmetic. |
| 132 | + See above for restrictions. Avoid && and || as they tickle |
| 133 | + bugs in Sun C 5.11 2010/08/13 and other compilers; see |
| 134 | + <https://lists.gnu.org/r/bug-gnulib/2011-05/msg00401.html>. */ |
| 135 | +#define INT_MULTIPLY_RANGE_OVERFLOW(a, b, min, max) \ |
| 136 | + ((b) < 0 \ |
| 137 | + ? ((a) < 0 \ |
| 138 | + ? (a) < (max) / (b) \ |
| 139 | + : (b) == -1 \ |
| 140 | + ? 0 \ |
| 141 | + : (min) / (b) < (a)) \ |
| 142 | + : (b) == 0 \ |
| 143 | + ? 0 \ |
| 144 | + : ((a) < 0 \ |
| 145 | + ? (a) < (min) / (b) \ |
| 146 | + : (max) / (b) < (a))) |
| 147 | + |
| 148 | +/* Return 1 if A / B would overflow in [MIN,MAX] arithmetic. |
| 149 | + See above for restrictions. Do not check for division by zero. */ |
| 150 | +#define INT_DIVIDE_RANGE_OVERFLOW(a, b, min, max) \ |
| 151 | + ((min) < 0 && (b) == -1 && (a) < - (max)) |
| 152 | + |
| 153 | +/* Return 1 if A % B would overflow in [MIN,MAX] arithmetic. |
| 154 | + See above for restrictions. Do not check for division by zero. |
| 155 | + Mathematically, % should never overflow, but on x86-like hosts |
| 156 | + INT_MIN % -1 traps, and the C standard permits this, so treat this |
| 157 | + as an overflow too. */ |
| 158 | +#define INT_REMAINDER_RANGE_OVERFLOW(a, b, min, max) \ |
| 159 | + INT_DIVIDE_RANGE_OVERFLOW (a, b, min, max) |
| 160 | + |
| 161 | +/* Return 1 if A << B would overflow in [MIN,MAX] arithmetic. |
| 162 | + See above for restrictions. Here, MIN and MAX are for A only, and B need |
| 163 | + not be of the same type as the other arguments. The C standard says that |
| 164 | + behavior is undefined for shifts unless 0 <= B < wordwidth, and that when |
| 165 | + A is negative then A << B has undefined behavior and A >> B has |
| 166 | + implementation-defined behavior, but do not check these other |
| 167 | + restrictions. */ |
| 168 | +#define INT_LEFT_SHIFT_RANGE_OVERFLOW(a, b, min, max) \ |
| 169 | + ((a) < 0 \ |
| 170 | + ? (a) < (min) >> (b) \ |
| 171 | + : (max) >> (b) < (a)) |
| 172 | + |
| 173 | +/* The _GL*_OVERFLOW macros have the same restrictions as the |
| 174 | + *_RANGE_OVERFLOW macros, except that they do not assume that operands |
| 175 | + (e.g., A and B) have the same type as MIN and MAX. Instead, they assume |
| 176 | + that the result (e.g., A + B) has that type. */ |
| 177 | +#if _GL_HAS_BUILTIN_OVERFLOW_P |
| 178 | +# define _GL_ADD_OVERFLOW(a, b, min, max) \ |
| 179 | + __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) |
| 180 | +# define _GL_SUBTRACT_OVERFLOW(a, b, min, max) \ |
| 181 | + __builtin_sub_overflow_p (a, b, (__typeof__ ((a) - (b))) 0) |
| 182 | +# define _GL_MULTIPLY_OVERFLOW(a, b, min, max) \ |
| 183 | + __builtin_mul_overflow_p (a, b, (__typeof__ ((a) * (b))) 0) |
| 184 | +#else |
| 185 | +# define _GL_ADD_OVERFLOW(a, b, min, max) \ |
| 186 | + ((min) < 0 ? INT_ADD_RANGE_OVERFLOW (a, b, min, max) \ |
| 187 | + : (a) < 0 ? (b) <= (a) + (b) \ |
| 188 | + : (b) < 0 ? (a) <= (a) + (b) \ |
| 189 | + : (a) + (b) < (b)) |
| 190 | +# define _GL_SUBTRACT_OVERFLOW(a, b, min, max) \ |
| 191 | + ((min) < 0 ? INT_SUBTRACT_RANGE_OVERFLOW (a, b, min, max) \ |
| 192 | + : (a) < 0 ? 1 \ |
| 193 | + : (b) < 0 ? (a) - (b) <= (a) \ |
| 194 | + : (a) < (b)) |
| 195 | +# define _GL_MULTIPLY_OVERFLOW(a, b, min, max) \ |
| 196 | + (((min) == 0 && (((a) < 0 && 0 < (b)) || ((b) < 0 && 0 < (a)))) \ |
| 197 | + || INT_MULTIPLY_RANGE_OVERFLOW (a, b, min, max)) |
| 198 | +#endif |
| 199 | +#define _GL_DIVIDE_OVERFLOW(a, b, min, max) \ |
| 200 | + ((min) < 0 ? (b) == _GL_INT_NEGATE_CONVERT (min, 1) && (a) < - (max) \ |
| 201 | + : (a) < 0 ? (b) <= (a) + (b) - 1 \ |
| 202 | + : (b) < 0 && (a) + (b) <= (a)) |
| 203 | +#define _GL_REMAINDER_OVERFLOW(a, b, min, max) \ |
| 204 | + ((min) < 0 ? (b) == _GL_INT_NEGATE_CONVERT (min, 1) && (a) < - (max) \ |
| 205 | + : (a) < 0 ? (a) % (b) != ((max) - (b) + 1) % (b) \ |
| 206 | + : (b) < 0 && ! _GL_UNSIGNED_NEG_MULTIPLE (a, b, max)) |
| 207 | + |
| 208 | +/* Return a nonzero value if A is a mathematical multiple of B, where |
| 209 | + A is unsigned, B is negative, and MAX is the maximum value of A's |
| 210 | + type. A's type must be the same as (A % B)'s type. Normally (A % |
| 211 | + -B == 0) suffices, but things get tricky if -B would overflow. */ |
| 212 | +#define _GL_UNSIGNED_NEG_MULTIPLE(a, b, max) \ |
| 213 | + (((b) < -_GL_SIGNED_INT_MAXIMUM (b) \ |
| 214 | + ? (_GL_SIGNED_INT_MAXIMUM (b) == (max) \ |
| 215 | + ? (a) \ |
| 216 | + : (a) % (_GL_INT_CONVERT (a, _GL_SIGNED_INT_MAXIMUM (b)) + 1)) \ |
| 217 | + : (a) % - (b)) \ |
| 218 | + == 0) |
| 219 | + |
| 220 | +/* Check for integer overflow, and report low order bits of answer. |
| 221 | +
|
| 222 | + The INT_<op>_OVERFLOW macros return 1 if the corresponding C operators |
| 223 | + might not yield numerically correct answers due to arithmetic overflow. |
| 224 | + The INT_<op>_WRAPV macros compute the low-order bits of the sum, |
| 225 | + difference, and product of two C integers, and return 1 if these |
| 226 | + low-order bits are not numerically correct. |
| 227 | + These macros work correctly on all known practical hosts, and do not rely |
| 228 | + on undefined behavior due to signed arithmetic overflow. |
| 229 | +
|
| 230 | + Example usage, assuming A and B are long int: |
| 231 | +
|
| 232 | + if (INT_MULTIPLY_OVERFLOW (a, b)) |
| 233 | + printf ("result would overflow\n"); |
| 234 | + else |
| 235 | + printf ("result is %ld (no overflow)\n", a * b); |
| 236 | +
|
| 237 | + Example usage with WRAPV flavor: |
| 238 | +
|
| 239 | + long int result; |
| 240 | + bool overflow = INT_MULTIPLY_WRAPV (a, b, &result); |
| 241 | + printf ("result is %ld (%s)\n", result, |
| 242 | + overflow ? "after overflow" : "no overflow"); |
| 243 | +
|
| 244 | + Restrictions on these macros: |
| 245 | +
|
| 246 | + These macros do not check for all possible numerical problems or |
| 247 | + undefined or unspecified behavior: they do not check for division |
| 248 | + by zero, for bad shift counts, or for shifting negative numbers. |
| 249 | +
|
| 250 | + These macros may evaluate their arguments zero or multiple times, so the |
| 251 | + arguments should not have side effects. |
| 252 | +
|
| 253 | + The WRAPV macros are not constant expressions. They support only |
| 254 | + +, binary -, and *. |
| 255 | +
|
| 256 | + Because the WRAPV macros convert the result, they report overflow |
| 257 | + in different circumstances than the OVERFLOW macros do. For |
| 258 | + example, in the typical case with 16-bit 'short' and 32-bit 'int', |
| 259 | + if A, B and *R are all of type 'short' then INT_ADD_OVERFLOW (A, B) |
| 260 | + returns false because the addition cannot overflow after A and B |
| 261 | + are converted to 'int', whereas INT_ADD_WRAPV (A, B, R) returns |
| 262 | + true or false depending on whether the sum fits into 'short'. |
| 263 | +
|
| 264 | + These macros are tuned for their last input argument being a constant. |
| 265 | +
|
| 266 | + A, B, and *R should be integers; they need not be the same type, |
| 267 | + and they need not be all signed or all unsigned. |
| 268 | + However, none of the integer types should be bit-precise, |
| 269 | + and *R's type should not be char, bool, or an enumeration type. |
| 270 | +
|
| 271 | + Return 1 if the integer expressions A * B, A - B, -A, A * B, A / B, |
| 272 | + A % B, and A << B would overflow, respectively. */ |
| 273 | + |
| 274 | +#define INT_ADD_OVERFLOW(a, b) \ |
| 275 | + _GL_BINARY_OP_OVERFLOW (a, b, _GL_ADD_OVERFLOW) |
| 276 | +#define INT_SUBTRACT_OVERFLOW(a, b) \ |
| 277 | + _GL_BINARY_OP_OVERFLOW (a, b, _GL_SUBTRACT_OVERFLOW) |
| 278 | +#define INT_NEGATE_OVERFLOW(a) _GL_INT_NEGATE_OVERFLOW (a) |
| 279 | +#define INT_MULTIPLY_OVERFLOW(a, b) \ |
| 280 | + _GL_BINARY_OP_OVERFLOW (a, b, _GL_MULTIPLY_OVERFLOW) |
| 281 | +#define INT_DIVIDE_OVERFLOW(a, b) \ |
| 282 | + _GL_BINARY_OP_OVERFLOW (a, b, _GL_DIVIDE_OVERFLOW) |
| 283 | +#define INT_REMAINDER_OVERFLOW(a, b) \ |
| 284 | + _GL_BINARY_OP_OVERFLOW (a, b, _GL_REMAINDER_OVERFLOW) |
| 285 | +#define INT_LEFT_SHIFT_OVERFLOW(a, b) \ |
| 286 | + INT_LEFT_SHIFT_RANGE_OVERFLOW (a, b, \ |
| 287 | + _GL_INT_MINIMUM (a), _GL_INT_MAXIMUM (a)) |
| 288 | + |
| 289 | +/* Return 1 if the expression A <op> B would overflow, |
| 290 | + where OP_RESULT_OVERFLOW (A, B, MIN, MAX) does the actual test, |
| 291 | + assuming MIN and MAX are the minimum and maximum for the result type. |
| 292 | + Arguments should be free of side effects. */ |
| 293 | +#define _GL_BINARY_OP_OVERFLOW(a, b, op_result_overflow) \ |
| 294 | + op_result_overflow (a, b, \ |
| 295 | + _GL_INT_MINIMUM (_GL_INT_CONVERT (a, b)), \ |
| 296 | + _GL_INT_MAXIMUM (_GL_INT_CONVERT (a, b))) |
| 297 | + |
| 298 | +/* Store the low-order bits of A + B, A - B, A * B, respectively, into *R. |
| 299 | + Return 1 if the result overflows. See above for restrictions. */ |
| 300 | +#define INT_ADD_WRAPV(a, b, r) _GL_INT_ADD_WRAPV (a, b, r) |
| 301 | +#define INT_SUBTRACT_WRAPV(a, b, r) _GL_INT_SUBTRACT_WRAPV (a, b, r) |
| 302 | +#define INT_MULTIPLY_WRAPV(a, b, r) _GL_INT_MULTIPLY_WRAPV (a, b, r) |
| 303 | + |
| 304 | +/* The following macros compute A + B, A - B, and A * B, respectively. |
| 305 | + If no overflow occurs, they set *R to the result and return 1; |
| 306 | + otherwise, they return 0 and may modify *R. |
| 307 | +
|
| 308 | + Example usage: |
| 309 | +
|
| 310 | + long int result; |
| 311 | + if (INT_ADD_OK (a, b, &result)) |
| 312 | + printf ("result is %ld\n", result); |
| 313 | + else |
| 314 | + printf ("overflow\n"); |
| 315 | +
|
| 316 | + A, B, and *R should be integers; they need not be the same type, |
| 317 | + and they need not be all signed or all unsigned. |
| 318 | + However, none of the integer types should be bit-precise, |
| 319 | + and *R's type should not be char, bool, or an enumeration type. |
| 320 | +
|
| 321 | + These macros work correctly on all known practical hosts, and do not rely |
| 322 | + on undefined behavior due to signed arithmetic overflow. |
| 323 | +
|
| 324 | + These macros are not constant expressions. |
| 325 | +
|
| 326 | + These macros may evaluate their arguments zero or multiple times, so the |
| 327 | + arguments should not have side effects. |
| 328 | +
|
| 329 | + These macros are tuned for B being a constant. */ |
| 330 | + |
| 331 | +#define INT_ADD_OK(a, b, r) (! INT_ADD_WRAPV (a, b, r)) |
| 332 | +#define INT_SUBTRACT_OK(a, b, r) (! INT_SUBTRACT_WRAPV (a, b, r)) |
| 333 | +#define INT_MULTIPLY_OK(a, b, r) (! INT_MULTIPLY_WRAPV (a, b, r)) |
| 334 | + |
| 335 | +#endif /* _GL_INTPROPS_H */ |
0 commit comments