Integer Properties
==================

The intprops module consists of an include file <intprops.h> that defines several macros useful for testing properties of integer types.

Integer overflow is a common source of problems in programs written in C and other languages.  In some cases, such as signed integer arithmetic in C programs, the resulting behavior is undefined, and practical platforms do not always behave as if integers wrap around reliably.  In other cases, such as unsigned integer arithmetic in C, the resulting behavior is well-defined, but programs may still misbehave badly after overflow occurs.

Many techniques have been proposed to attack these problems.  These include precondition testing, GCC's -ftrapv option, GCC's no-undefined-overflow branch, the As-if Infinitely Ranged (AIR) model implemented in Clang, saturation semantics where overflow reliably yields an extreme value, the RICH static transformer to an overflow-checking variant, and special testing methods.  For more information about these techniques, see: Dannenberg R, Dormann W, Keaton D et al., As-if Infinitely Ranged integer model -- 2nd ed. (http://www.sei.cmu.edu/library/abstracts/reports/10tn008.cfm), Software Engineering Institute Technical Note CMU/SEI-2010-TN-008, April 2010.

Gnulib supports the precondition testing technique, as this is easy to support portably.  There are two families of precondition tests: the first, for integer ranges, has a simple and straightforward implementation, while the second, for integer types, is easier to use.

Integer Type Determination
--------------------------

TYPE_IS_INTEGER (T) expands to a constant expression that is 1 if the arithmetic type T is an integer type. _Bool counts as an integer type.

TYPE_SIGNED (T) expands to a constant expression that is 1 if the arithmetic type T is a signed integer type or a floating type.  If T is an integer type, TYPE_SIGNED (T) expands to an integer constant expression.

Example usage:

     #include <intprops.h>
     #include <time.h>
     enum
     {
       time_t_is_signed_integer =
         TYPE_IS_INTEGER (time_t) && TYPE_SIGNED (time_t)
     };

Integer Bounds
--------------

INT_BUFSIZE_BOUND (T) expands to an integer constant expression that is a bound on the size of the string representing an integer type or expression T in decimal notation, including the terminating null character and any leading - character.  For example, if INT_STRLEN_BOUND (int) is 12, any value of type int can be represented in 12 bytes or less, including the terminating null.  The bound is not necessarily tight.

Example usage:

     #include <intprops.h>
     #include <stdio.h>
     int
     int_strlen (int i)
     {
       char buf[INT_BUFSIZE_BOUND (int)];
       return sprintf (buf, "%d", i);
     }

INT_STRLEN_BOUND (T) expands to an integer constant expression that is a bound on the length of the string representing an integer type or expression T in decimal notation, including any leading - character.  This is one less than INT_BUFSIZE_BOUND (T).

TYPE_MINIMUM (T) and TYPE_MAXIMUM (T) expand to integer constant expressions equal to the minimum and maximum values of the integer type T.  These expressions are of the type T (or more precisely, the type T after integer promotions).

Example usage:

     #include <stdint.h>
     #include <sys/types.h>
     #include <intprops.h>
     int
     in_off_t_range (intmax_t a)
     {
       return TYPE_MINIMUM (off_t) <= a && a <= TYPE_MAXIMUM (off_t);
     }

Integer Range Overflow
----------------------

These macros yield 1 if the corresponding C operators might not yield numerically correct answers due to arithmetic overflow.  They do not rely on undefined or implementation-defined behavior.  They expand to integer constant expressions if their arguments are.  Their implementations are simple and straightforward, but they are typically harder to use than the integer type overflow macros.  See Integer Type Overflow.

Although the implementation of these macros is similar to that suggested in Seacord R, The CERT C Secure Coding Standard (2009, revised 2011), in its two sections ``INT30-C. Ensure that unsigned integer operations do not wrap (https://www.securecoding.cert.org/confluence/display/seccode/INT30-C.+Ensure+that+unsigned+integer+operations+do+not+wrap)'' and ``INT32-C. Ensure that operations on signed integers do not result in overflow (https://www.securecoding.cert.org/confluence/display/seccode/INT32-C.+Ensure+that+operations+on+signed+integers+do+not+result+in+overflow)'', Gnulib's implementation was derived independently of CERT's suggestions.

Example usage:

     #include <intprops.h>
     void
     print_product (long int a, long int b)
     {
       if (INT_MULTIPLY_RANGE_OVERFLOW (a, b, LONG_MIN, LONG_MAX))
         printf ("multiply would overflow");
       else
         printf ("product is %ld", a * b);
     }

These macros have the following restrictions:

  * Their arguments must be integer expressions.

  * They may evaluate their arguments zero or multiple times, so the arguments should not have side effects.

  * The arithmetic arguments (including the MIN and MAX arguments) must be of the same integer type after the usual arithmetic conversions, and the type must have minimum value MIN and maximum MAX.  Unsigned values should use a zero MIN of the proper type, for example, (unsigned int) 0.

These macros are tuned for constant MIN and MAX.  For commutative operations such as A + B, they are also tuned for constant B.

INT_ADD_RANGE_OVERFLOW (A, B, MIN, MAX)
     Yield 1 if A + B would overflow in [MIN,MAX] integer arithmetic.  See above for restrictions.

INT_SUBTRACT_RANGE_OVERFLOW (A, B, MIN, MAX)
     Yield 1 if A - B would overflow in [MIN,MAX] integer arithmetic.  See above for restrictions.

INT_NEGATE_RANGE_OVERFLOW (A, MIN, MAX)
     Yield 1 if -A would overflow in [MIN,MAX] integer arithmetic.  See above for restrictions.

INT_MULTIPLY_RANGE_OVERFLOW (A, B, MIN, MAX)
     Yield 1 if A * B would overflow in [MIN,MAX] integer arithmetic.  See above for restrictions.

INT_DIVIDE_RANGE_OVERFLOW (A, B, MIN, MAX)
     Yield 1 if A / B would overflow in [MIN,MAX] integer arithmetic.  See above for restrictions. Division overflow can happen on two's complement hosts when dividing the most negative integer by -1.  This macro does not check for division by zero.

INT_REMAINDER_RANGE_OVERFLOW (A, B, MIN, MAX)
     Yield 1 if A % B would overflow in [MIN,MAX] integer arithmetic.  See above for restrictions. Remainder overflow can happen on two's complement hosts when dividing the most negative integer by -1; although the mathematical result is always 0, in practice some implementations trap, so this counts as an overflow.  This macro does not check for division by zero.

INT_LEFT_SHIFT_RANGE_OVERFLOW (A, B, MIN, MAX)
     Yield 1 if A << B would overflow in [MIN,MAX] integer arithmetic.  See above for restrictions. Here, MIN and MAX are for A only, and B need not be of the same type as the other arguments.  The C standard says that behavior is undefined for shifts unless 0≤B<W where W is A's word width, and that when A is negative then A << B has undefined behavior and A >> B has implementation-defined behavior, but this macro does not check these other restrictions.

Integer Type Overflow
---------------------

These macros yield 1 if the corresponding C operators might not yield numerically correct answers due to arithmetic overflow of an integer type.  They work correctly on all known practical hosts, and do not rely on undefined behavior due to signed arithmetic overflow.  They expand to integer constant expressions if their arguments are.  They are easier to use than the integer range overflow macros (see Integer Range Overflow).

Example usage:

     #include <intprops.h>
     void
     print_product (long int a, long int b)
     {
       if (INT_MULTIPLY_OVERFLOW (a, b))
         printf ("multiply would overflow");
       else
         printf ("product is %ld", a * b);
     }

These macros have the following restrictions:

  * Their arguments must be integer expressions.

  * They may evaluate their arguments zero or multiple times, so the arguments should not have side effects.

These macros are tuned for their last argument being a constant.

INT_ADD_OVERFLOW (A, B)
     Yield 1 if A + B would overflow.  See above for restrictions.

INT_SUBTRACT_OVERFLOW (A, B)
     Yield 1 if A - B would overflow.  See above for restrictions.

INT_NEGATE_OVERFLOW (A)
     Yields 1 if -A would overflow.  See above for restrictions.

INT_MULTIPLY_OVERFLOW (A, B)
     Yield 1 if A * B would overflow.  See above for restrictions.

INT_DIVIDE_OVERFLOW (A, B)
     Yields 1 if A / B would overflow.  See above for restrictions.  Division overflow can happen on two's complement hosts when dividing the most negative integer by -1.  This macro does not check for division by zero.

INT_REMAINDER_OVERFLOW (A, B)
     Yield 1 if A % B would overflow.  See above for restrictions.  Remainder overflow can happen on two's complement hosts when dividing the most negative integer by -1; although the mathematical result is always 0, in practice some implementations trap, so this counts as an overflow.  This macro does not check for division by zero.

INT_LEFT_SHIFT_OVERFLOW (A, B)
     Yield 1 if A << B would overflow.  See above for restrictions.  The C standard says that behavior is undefined for shifts unless 0≤B<W where W is A's word width, and that when A is negative then A << B has undefined behavior and A >> B has implementation-defined behavior, but this macro does not check these other restrictions.