From 6ab946ed2c06ecea1d7b67335bd70edbb3440a5a Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sun, 14 Mar 2021 21:28:40 -0700 Subject: [PATCH] intprops: improve commentary * lib/intprops.h: Improve comments about promotion etc. --- ChangeLog | 5 +++++ lib/intprops.h | 18 ++++++++++++++---- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/ChangeLog b/ChangeLog index b71c327f9..f89738061 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2021-03-14 Paul Eggert + + intprops: improve commentary + * lib/intprops.h: Improve comments about promotion etc. + 2021-03-14 Bruno Haible time_rz: Put reference documentation into the .h file. diff --git a/lib/intprops.h b/lib/intprops.h index 967e32ea0..9d10028a5 100644 --- a/lib/intprops.h +++ b/lib/intprops.h @@ -133,7 +133,8 @@ 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__WRAPV, INT__OK, and INT__OVERFLOW macros described below. Example usage: @@ -158,6 +159,9 @@ 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. */ @@ -339,9 +343,15 @@ 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. -- 2.27.0