]> Savannah Git Hosting - gnulib.git/commitdiff
intprops: improve commentary
authorPaul Eggert <eggert@cs.ucla.edu>
Mon, 15 Mar 2021 04:28:40 +0000 (21:28 -0700)
committerPaul Eggert <eggert@cs.ucla.edu>
Mon, 15 Mar 2021 04:29:18 +0000 (21:29 -0700)
* lib/intprops.h: Improve comments about promotion etc.

ChangeLog
lib/intprops.h

index b71c327f9bd725b2a9f6803f98ac06a74765fb8c..f89738061bdf41844988fe02251ca431f0f60cd2 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2021-03-14  Paul Eggert  <eggert@cs.ucla.edu>
+
+       intprops: improve commentary
+       * lib/intprops.h: Improve comments about promotion etc.
+
 2021-03-14  Bruno Haible  <bruno@clisp.org>
 
        time_rz: Put reference documentation into the .h file.
index 967e32ea0cbedd56fec3697c5fb40d9594cbfb9c..9d10028a5966c1c6fba2eb1a0907ac75a80dbc78 100644 (file)
    operators might not yield numerically correct answers due to
    arithmetic overflow.  They do not rely on undefined or
    implementation-defined behavior.  Their implementations are simple
-   and straightforward, but they are a bit harder to use than the
+   and straightforward, but they are harder to use and may be less
+   efficient than the INT_<op>_WRAPV, INT_<op>_OK, and
    INT_<op>_OVERFLOW macros described below.
 
    Example usage:
    must have minimum value MIN and maximum MAX.  Unsigned types should
    use a zero MIN of the proper type.
 
+   Because all arguments are subject to integer promotions, these
+   macros typically do not work on types narrower than 'int'.
+
    These macros are tuned for constant MIN and MAX.  For commutative
    operations such as A + B, they are also tuned for constant B.  */
 
    arguments should not have side effects.
 
    The WRAPV macros are not constant expressions.  They support only
-   +, binary -, and *.  Because the WRAPV macros convert the result,
-   they report overflow in different circumstances than the OVERFLOW
-   macros do.
+   +, binary -, and *.
+
+   Because the WRAPV macros convert the result, they report overflow
+   in different circumstances than the OVERFLOW macros do.  For
+   example, in the typical case with 16-bit 'short' and 32-bit 'int',
+   if A, B and R are all of type 'short' then INT_ADD_OVERFLOW (A, B)
+   returns false because the addition cannot overflow after A and B
+   are converted to 'int', whereas INT_ADD_WRAPV (A, B, &R) returns
+   true or false depending on whether the sum fits into 'short'.
 
    These macros are tuned for their last input argument being a constant.