# Chapter 11Arithmetic

This chapter describes Scheme’s libraries for more specialized numerical operations: fixnum and flonum arithmetic, as well as bitwise operations on exact integers.

## 11.1  Fixnums

Every implementation must define its fixnum range as a closed interval

such that w is a (mathematical) integer w ≥ 24. Every mathematical integer within an implementation’s fixnum range must correspond to an exact integer that is representable within the implementation. A fixnum is an exact integer whose value lies within this fixnum range.

This section describes the (rnrs arithmetic fx (6))library, which defines various operations on fixnums. Fixnum operations perform integer arithmetic on their fixnum arguments, but raise an exception with condition type &implementation-restriction if the result is not a fixnum.

This section uses fx, fx1, fx2, etc., as parameter names for arguments that must be fixnums.

(fixnum? obj)    procedure

Returns #t if obj is an exact integer within the fixnum range, #f otherwise.

(fixnum-width)    procedure
(least-fixnum)    procedure
(greatest-fixnum)    procedure

These procedures return w, - 2w-1 and 2w-1 - 1: the width, minimum and the maximum value of the fixnum range, respectively.

(fx=? fx1 fx2 fx3 ...)    procedure
(fx>? fx1 fx2 fx3 ...)    procedure
(fx<? fx1 fx2 fx3 ...)    procedure
(fx>=? fx1 fx2 fx3 ...)    procedure
(fx<=? fx1 fx2 fx3 ...)    procedure

These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing, #f otherwise.

(fxzero? fx)    procedure
(fxpositive? fx)    procedure
(fxnegative? fx)    procedure
(fxodd? fx)    procedure
(fxeven? fx)    procedure

These numerical predicates test a fixnum for a particular property, returning #t or #f. The five properties tested by these procedures are: whether the number is zero, greater than zero, less than zero, odd, or even.

(fxmax fx1 fx2 ...)    procedure
(fxmin fx1 fx2 ...)    procedure

These procedures return the maximum or minimum of their arguments.

(fx+ fx1 fx2)    procedure
(fx* fx1 fx2)    procedure

These procedures return the sum or product of their arguments, provided that sum or product is a fixnum. An exception with condition type &implementation-restriction is raised if that sum or product is not a fixnum.

Rationale:   These procedures are restricted to two arguments because their generalizations to three or more arguments would require precision proportional to the number of arguments.

(fx- fx1 fx2)    procedure
(fx- fx)    procedure

With two arguments, this procedure returns the difference of its arguments, provided that difference is a fixnum.

With one argument, this procedure returns the additive inverse of its argument, provided that integer is a fixnum.

An exception with condition type &assertion is raised if the mathematically correct result of this procedure is not a fixnum.

(fx- (least-fixnum))
⇒   &assertion exception

(fxdiv-and-mod fx1 fx2)    procedure
(fxdiv fx1 fx2)    procedure
(fxmod fx1 fx2)    procedure
(fxdiv0-and-mod0 fx1 fx2)    procedure
(fxdiv0 fx1 fx2)    procedure
(fxmod0 fx1 fx2)    procedure

Fx2 must be nonzero. These procedures implement number-theoretic integer division and return the results of the corresponding mathematical operations specified in report section on “Integer division”.

(fxdiv fx1 fx2)                 ⇒ fx1 div fx2
(fxmod fx1 fx2)                 ⇒ fx1 mod fx2
(fxdiv-and-mod fx1 fx2)
⇒ fx1 div fx2fx1 mod fx2
; two return values
(fxdiv0 fx1 fx2)                ⇒ fx1 divsb0 fx2
(fxmod0 fx1 fx2)                ⇒ fx1 modsb0 fx2
(fxdiv0-and-mod0 fx1 fx2)
⇒ fx1 fx1 divsb0 fx2fx1 modsb0 fx2
; two return values

(fx+/carry fx1 fx2 fx3)    procedure

Returns the two fixnum results of the following computation:

(let* ((s (+ fx1 fx2 fx3))
(s0 (mod0 s (expt 2 (fixnum-width))))
(s1 (div0 s (expt 2 (fixnum-width)))))
(values s0 s1))

(fx-/carry fx1 fx2 fx3)    procedure

Returns the two fixnum results of the following computation:

(let* ((d (- fx1 fx2 fx3))
(d0 (mod0 d (expt 2 (fixnum-width))))
(d1 (div0 d (expt 2 (fixnum-width)))))
(values d0 d1))

(fx*/carry fx1 fx2 fx3)    procedure

Returns the two fixnum results of the following computation:

(let* ((s (+ (* fx1 fx2fx3))
(s0 (mod0 s (expt 2 (fixnum-width))))
(s1 (div0 s (expt 2 (fixnum-width)))))
(values s0 s1))

(fxnot fx)    procedure

Returns the unique fixnum that is congruent mod 2w to the one’s-complement of fx.

(fxand fx1 ...)    procedure
(fxior fx1 ...)    procedure
(fxxor fx1 ...)    procedure

These procedures return the fixnum that is the bit-wise “and”, “inclusive or”, or “exclusive or” of the two’s complement representations of their arguments. If they are passed only one argument, they return that argument. If they are passed no arguments, they return the fixnum (either - 1 or 0) that acts as identity for the operation.

(fxif fx1 fx2 fx3)    procedure

Returns the fixnum result of the following computation:

(fxior (fxand fx1 fx2)
(fxand (fxnot fx1fx3))

(fxbit-count fx)    procedure

If fx is non-negative, this procedure returns the number of 1 bits in the two’s complement representation of fx. Otherwise it returns the result of the following computation:

(fxnot (fxbit-count (fxnot ei)))

(fxlength fx)    procedure

Returns the fixnum result of the following computation:

(do ((result 0 (+ result 1))
(bits (if (fxnegative? fx)
(fxnot fx)
fx)
(fxarithmetic-shift-right bits 1)))
((fxzero? bits)
result))

(fxfirst-bit-set fx)    procedure

Returns the index of the least significant 1 bit in the two’s complement representation of fx. If fx is 0, then - 1 is returned.

(fxfirst-bit-set 0)                ⇒  -1
(fxfirst-bit-set 1)                ⇒  0
(fxfirst-bit-set -4)               ⇒  2

(fxbit-set? fx fx2)    procedure

Fx2 must be non-negative and less than (fixnum-width). The fxbit-set? procedure returns the fixnum result of the following computation:

(not
(fxzero?
(fxand fx1
(fxarithmetic-shift-left 1 fx2))))

(fxcopy-bit fx1 fx2 fx3)    procedure

Fx2 must be non-negative and less than (fixnum-width). Fx3 must be 0 or 1. The fxcopy-bit procedure returns the result of the following computation:

(fxarithmetic-shift-left fx3 fx2)
fx1))

(fxbit-field fx1 fx2 fx3)    procedure

Fx2 and fx3 must be non-negative and less than (fixnum-width). Moreover, fx2 must be less than or equal to fx3. The fxbit-field procedure returns the fixnum result of the following computation:

(fxarithmetic-shift-left -1 fx3))))
fx2))

(fxcopy-bit-field fx1 fx2 fx3 fx4)    procedure

Fx2 and fx3 must be non-negative and less than (fixnum-width). Moreover, fx2 must be less than or equal to fx3. The fxcopy-bit-field procedure returns the fixnum result of the following computation:

(let* ((to    fx1)
(start fx2)
(end   fx3)
(from  fx4)
(fxarithmetic-shift-left -1 end)))
(fxarithmetic-shift-left from start)
to))

(fxarithmetic-shift fx1 fx2)    procedure

The absolute value of fx2 must be less than (fixnum-width). If

(* fx1 (expt 2 fx2))

is a fixnum, then that fixnum is returned. Otherwise an exception with condition type &implementation-restriction is raised.

(fxarithmetic-shift-left fx1 fx2)    procedure
(fxarithmetic-shift-right fx1 fx2)    procedure

Fx2 must be non-negative. fxarithmetic-shift-left behaves the same as fxarithmetic-shift, and (fxarithmetic-shift-right fx1 fx2) behaves the same as (fxarithmetic-shift fx1 (fixnum- fx2)).

(fxrotate-bit-field fx1 fx2 fx3 fx4)    procedure

Fx2, fx3, and fx4 must be non-negative and less than (fixnum-width). Fx4 must be less than the difference between fx3 and fx3. The fxrotate-bit-field procedure returns the result of the following computation:

(let* ((n     fx1)
(start fx2)
(end   fx3)
(count fx4)
(width (fx- end start)))
(if (fxpositive? width)
(let* ((count (fxmod count width))
(field0
(fxbit-field n start end))
(field1
(fxarithmetic-shift-left
field0 count))
(field2
(fxarithmetic-shift-right
field0 (fx- width count)))
(field (fxior field1 field2)))
(fxcopy-bit-field n start end field))
n))

(fxreverse-bit-field fx1 fx2 fx3)    procedure

Fx2 and fx3 must be non-negative and less than (fixnum-width). Moreover, fx2 must be less than or equal to fx3. The fxreverse-bit-field procedure returns the fixnum obtained from fx1 by reversing the bit field specified by fx2 and fx3.

(fxreverse-bit-field #b1010010 1 4)
⇒  88 ; #b1011000
(fxreverse-bit-field #b1010010 91 -4)
⇒  82 ; #b1010010

## 11.2  Flonums

This section describes the (rnrs arithmetic flonum (6))library.

This section uses fl, fl1, fl2, etc., as parameter names for arguments that must be flonums, and ifl as a name for arguments that must be integer-valued flonums, i.e., flonums for which the integer-valued? predicate returns true.

(flonum? obj)    procedure

Returns #t if obj is a flonum, #f otherwise.

(real->flonum x)    procedure

Returns the best flonum representation of x.

The value returned is a flonum that is numerically closest to the argument.

Rationale:   Not all reals are inexact, and some inexact reals may not be flonums.

Note:   If flonums are represented in binary floating point, then implementations are strongly encouraged to break ties by preferring the floating point representation whose least significant bit is zero.

(fl=? fl1 fl2 fl3 ...)    procedure
(fl<? fl1 fl2 fl3 ...)    procedure
(fl<=? fl1 fl2 fl3 ...)    procedure
(fl>? fl1 fl2 fl3 ...)    procedure
(fl>=? fl1 fl2 fl3 ...)    procedure

These procedures return #t if their arguments are (respectively): equal, monotonically increasing, monotonically decreasing, monotonically nondecreasing, or monotonically nonincreasing, #f otherwise. These predicates are required to be transitive.

(fl= +inf.0 +inf.0)                   ⇒  #t
(fl= -inf.0 +inf.0)                   ⇒  #f
(fl= -inf.0 -inf.0)                   ⇒  #t
(fl= 0.0 -0.0)                        ⇒  #t
(fl< 0.0 -0.0)                        ⇒  #f
(fl= +nan.0 fl)                       ⇒  #f
(fl< +nan.0 fl)                       ⇒  #f

(flinteger? fl)    procedure
(flzero? fl)    procedure
(flpositive? fl)    procedure
(flnegative? fl)    procedure
(flodd? ifl)    procedure
(fleven? ifl)    procedure
(flfinite? fl)    procedure
(flinfinite? fl)    procedure
(flnan? fl)    procedure

These numerical predicates test a flonum for a particular property, returning #t or #f. The flinteger? procedure tests whether the number is an integer, flzero? tests whether it is fl=? to zero, flpositive? tests whether it is greater than zero, flnegative? tests whether it is less than zero, flodd? tests whether it is odd, fleven? tests whether it is even, flfinite? tests whether it is not an infinity and not a NaN, flinfinite? tests whether it is an infinity, and flnan? tests whether it is a NaN.

(flnegative? -0.0)           ⇒ #f
(flfinite? +inf.0)           ⇒ #f
(flfinite? 5.0)              ⇒ #t
(flinfinite? 5.0)            ⇒ #f
(flinfinite? +inf.0)         ⇒ #t

Note:   (flnegative? -0.0) must return #f, else it would lose the correspondence with (fl< -0.0 0.0), which is #f according to the IEEE standards.

(flmax fl1 fl2 ...)    procedure
(flmin fl1 fl2 ...)    procedure

These procedures return the maximum or minimum of their arguments. They always return a NaN when one or more of the arguments is a NaN.

(fl+ fl1 ...)    procedure
(fl* fl1 ...)    procedure

These procedures return the flonum sum or product of their flonum arguments. In general, they should return the flonum that best approximates the mathematical sum or product. (For implementations that represent flonums as IEEE binary floating point numbers, the meaning of “best” is defined by the IEEE standards.)

(fl+ +inf.0 -inf.0)              ⇒  +nan.0
(fl+ +nan.0 fl)                  ⇒  +nan.0
(fl* +nan.0 fl)                  ⇒  +nan.0

(fl- fl1 fl2 ...)    procedure
(fl- fl)    procedure
(fl/ fl1 fl2 ...)    procedure
(fl/ fl)    procedure

With two or more arguments, these procedures return the flonum difference or quotient of their flonum arguments, associating to the left. With one argument, however, they return the additive or multiplicative flonum inverse of their argument. In general, they should return the flonum that best approximates the mathematical difference or quotient. (For implementations that represent flonums as IEEE binary floating point numbers, the meaning of “best” is reasonably well-defined by the IEEE standards.)

(fl- +inf.0 +inf.0)              ⇒  +nan.0

For undefined quotients, fl/ behaves as specified by the IEEE standards:

(fl/ 1.0 0.0)          ⇒ +inf.0
(fl/ -1.0 0.0)         ⇒ -inf.0
(fl/ 0.0 0.0)          ⇒ +nan.0

(flabs fl)    procedure

Returns the absolute value of fl.

(fldiv-and-mod fl1 fl2)    procedure
(fldiv fl1 fl2)    procedure
(flmod fl1 fl2)    procedure
(fldiv0-and-mod0 fl1 fl2)    procedure
(fldiv0 fl1 fl2)    procedure
(flmod0 fl1 fl2)    procedure

These procedures implement number-theoretic integer division and return the results of the corresponding mathematical operations specified in report section on “Integer division”. For zero divisors, these procedures may return a NaN or some meaningless flonum.

(fldiv fl1 fl2)                 ⇒ fl1 div fl2
(flmod fl1 fl2)                 ⇒ fl1 mod fl2
(fldiv-and-mod fl1 fl2)
⇒ fl1 div fl2fl1 mod fl2
; two return values
(fldiv0 fl1 fl2)                ⇒ fl1 div0 fl2
(flmod0 fl1 fl2)                ⇒ fl1 mod0 fl2
(fldiv0-and-mod0 fl1 fl2)
⇒ fl1 div0 fl2fl1 mod0 fl2
; two return values

(flnumerator fl)    procedure
(fldenominator fl)    procedure

These procedures return the numerator or denominator of fl as a flonum; the result is computed as if fl was represented as a fraction in lowest terms. The denominator is always positive. The denominator of 0.0 is defined to be 1.0.

(flnumerator +inf.0)                   ⇒  +inf.0
(flnumerator -inf.0)                   ⇒  -inf.0
(fldenominator +inf.0)                 ⇒  1.0
(fldenominator -inf.0)                 ⇒  1.0
(flnumerator 0.75)                     ⇒  3.0 ; probably
(fldenominator 0.75)                   ⇒  4.0 ; probably

The following behavior is strongly recommended but not required:

(flnumerator -0.0)                     ⇒ -0.0

(flfloor fl)    procedure
(flceiling fl)    procedure
(fltruncate fl)    procedure
(flround fl)    procedure

These procedures return integral flonums for flonum arguments that are not infinities or NaNs. For such arguments, flfloor returns the largest integral flonum not larger than fl. The flceiling procedure returns the smallest integral flonum not smaller than fl. The fltruncate procedure returns the integral flonum closest to fl whose absolute value is not larger than the absolute value of fl. The flround procedure returns the closest integral flonum to fl, rounding to even when fl is halfway between two integers.

Rationale:   The flround procedure rounds to even for consistency with the default rounding mode specified by the IEEE floating point standard.

Although infinities and NaNs are not integers, these procedures return an infinity when given an infinity as an argument, and a NaN when given a NaN:

(flfloor +inf.0)                               ⇒  +inf.0
(flceiling -inf.0)                             ⇒  -inf.0
(fltruncate +nan.0)                            ⇒  +nan.0

(flexp fl)    procedure
(fllog fl)    procedure
(fllog fl1 fl2)    procedure
(flsin fl)    procedure
(flcos fl)    procedure
(fltan fl)    procedure
(flasin fl)    procedure
(flacos fl)    procedure
(flatan fl)    procedure
(flatan fl1 fl2)    procedure

These procedures compute the usual transcendental functions. The flexp procedure computes the base-e exponential of fl. The fllog procedure with a single argument computes the natural logarithm of fl (not the base ten logarithm); (fllog fl1 fl2) computes the base-fl2 logarithm of fl1. The flasin, flacos, and flatan procedures compute arcsine, arccosine, and arctangent, respectively. (flatan fl1 fl2) computes the arc tangent of fl1/fl2.

See report section on “Transcendental functions” for the underlying mathematical operations. In the event that these operations do not yield a real result for the given arguments, the result may be a NaN, or may be some meaningless flonum.

Implementations that use IEEE binary floating point arithmetic are encouraged to follow the relevant standards for these procedures.

(flexp +inf.0)                        ⇒ +inf.0
(flexp -inf.0)                        ⇒ 0.0
(fllog +inf.0)                        ⇒ +inf.0
(fllog 0.0)                           ⇒ -inf.0
(fllog -0.0)                          ⇒ unspecified
; if -0.0 is distinguished
(fllog -inf.0)                        ⇒ +nan.0
(flatan -inf.0)
⇒ -1.5707963267948965
; approximately
(flatan +inf.0)
⇒ 1.5707963267948965
; approximately

(flsqrt fl)    procedure

Returns the principal square root of fl. For - 0.0, flsqrt should return - 0.0; for other negative arguments, the result may be a NaN or some meaningless flonum.

Rationale:   The behavior of flsqrt on - 0.0 is consistent with the IEEE floating point standard.

(flsqrt +inf.0)                       ⇒  +inf.0
(flsqrt -0.0)                         ⇒  -0.0

(flexpt fl1 fl2)    procedure

Returns fl1 raised to the power fl2. fl1 should be non-negative; if fl1 is negative, then the result may be a NaN, or may be some meaningless flonum. If fl1 is zero, then the result is zero. For positive mathitfl1,

&no-infinities    condition type
(make-no-infinities-violation obj)    procedure
(no-infinities-violation? obj)    procedure
&no-nans    condition type
(make-no-nans-violation obj)    procedure
(no-nans-violation? obj)    procedure

These condition types could be defined by the following code:

(define-condition-type &no-infinities
&implementation-restriction
make-no-infinities-violation no-infinities-violation?)

(define-condition-type &no-nans
&implementation-restriction
make-no-nans-violation no-nans-violation?)

These types describe that a program has executed an arithmetic operations that is specified to return an infinity or a NaN, respectively, on a Scheme implementation that is not able to represent the infinity or NaN. (See report section on “Representability of infinities and NaNs”.)

(fixnum->flonum fx)    procedure

Returns a flonum that is numerically closest to fx.

Note:   The result of this procedure may not be numerically equal to fx, because the fixnum precision may be greater than the flonum precision.

## 11.3  Exact bitwise arithmetic

This section describes the (rnrs arithmetic bitwise (6))library. The exact bitwise arithmetic provides generic operations on exact integers. This section uses ei, ei1, ei2, etc., as parameter names that must be exact integers.

Some procedures allow extracting bit fields, i.e., numbers representing subsequences of the binary representation of an exact integer. Bit fields are always positive, and always defined using a finite number of bits, contrary to 2’s complement representation which implicitly uses an infinite extension of 0 bits or 1 bits to the left.

(bitwise-not ei)    procedure

Returns the exact integer whose two’s complement representation is the one’s complement of the two’s complement representation of ei.

(bitwise-and ei1 ...)    procedure
(bitwise-ior ei1 ...)    procedure
(bitwise-xor ei1 ...)    procedure

These procedures return the exact integer that is the bit-wise “and”, “inclusive or”, or “exclusive or” of the two’s complement representations of their arguments. If they are passed only one argument, they return that argument. If they are passed no arguments, they return the integer (either - 1 or 0) that acts as identity for the operation.

(bitwise-if ei1 ei2 ei3)    procedure

Returns the exact integer that is the result of the following computation:

(bitwise-ior (bitwise-and ei1 ei2)
(bitwise-and (bitwise-not ei1ei3))

(bitwise-bit-count ei)    procedure

If ei is non-negative, this procedure returns the number of 1 bits in the two’s complement representation of ei. Otherwise it returns the result of the following computation:

(bitwise-not (bitwise-bit-count (bitwise-not ei)))

(bitwise-length ei)    procedure

Returns the exact integer that is the result of the following computation:

(do ((result 0 (+ result 1))
(bits (if (negative? ei)
(bitwise-not ei)
ei)
(bitwise-arithmetic-shift bits -1)))
((zero? bits)
result))

(bitwise-first-bit-set ei)    procedure

Returns the index of the least significant 1 bit in the two’s complement representation of ei. If ei is 0, then - 1 is returned.

(bitwise-first-bit-set 0)                ⇒  -1
(bitwise-first-bit-set 1)                ⇒  0
(bitwise-first-bit-set -4)               ⇒  2

(bitwise-bit-set? ei1 ei2)    procedure

Ei2 must be non-negative. Returns the result of the following computation:

(not (zero?
(bitwise-and
(bitwise-arithmetic-shift-left 1 ei2)
ei1)))

(bitwise-copy-bit ei1 ei2 ei3)    procedure

Ei2 must be non-negative, and ei3 must be either 0 or 1. The bitwise-copy-bit procedure returns the result of the following computation:

(bitwise-arithmetic-shift-left ei3 ei2)
ei1))

(bitwise-bit-field ei1 ei2 ei3)    procedure

Ei2 and ei3 must be non-negative, and ei2 must be less than or equal to ei3. This procedure returns the result of the following computation:

(bitwise-not
(bitwise-arithmetic-shift-left -1 ei3))))
(bitwise-arithmetic-shift-right
ei2))

(bitwise-copy-bit-field ei1 ei2 ei3 ei4)    procedure

Ei2 and ei3 must be non-negative, and ei2 must be less than or equal to ei3. The bitwise-copy-bit-field procedure returns the result of the following computation:

(let* ((to    ei1)
(start ei2)
(end   ei3)
(from  ei4)
(bitwise-arithmetic-shift-left -1 start))
(bitwise-not
(bitwise-arithmetic-shift-left -1 end)))
(bitwise-arithmetic-shift-left from
start)
to))

(bitwise-arithmetic-shift ei1 ei2)    procedure

Returns the result of the following computation:

(floor (* ei1 (expt 2 ei2)))

Examples:

(bitwise-arithmetic-shift -6 -1)
⇒ -3
(bitwise-arithmetic-shift -5 -1)
⇒ -3
(bitwise-arithmetic-shift -4 -1)
⇒ -2
(bitwise-arithmetic-shift -3 -1)
⇒ -2
(bitwise-arithmetic-shift -2 -1)
⇒ -1
(bitwise-arithmetic-shift -1 -1)
⇒ -1

(bitwise-arithmetic-shift-left ei1 ei2)    procedure
(bitwise-arithmetic-shift-right ei1 ei2)    procedure

Ei2 must be non-negative. The bitwise-arithmetic-shift-left procedure returns the same result as bitwise-arithmetic-shift, and (bitwise-arithmetic-shift-right ei1 ei2) returns the same result as (bitwise-arithmetic-shift ei1 (- ei2)).

(bitwise-rotate-bit-field ei1 ei2 ei3 ei4)    procedure

Ei2, ei3, ei4 must be non-negative, ei2 must be less than or equal to ei3, and ei4 must be non-negative. The procedure returns the result of the following computation:

(let* ((n     ei1)
(start ei2)
(end   ei3)
(count ei4)
(width (- end start)))
(if (positive? width)
(let* ((count (mod count width))
(field0
(bitwise-bit-field n start end))
(field1 (bitwise-arithmetic-shift-left
field0 count))
(field2 (bitwise-arithmetic-shift-right
field0
(- width count)))
(field (bitwise-ior field1 field2)))
(bitwise-copy-bit-field n start end field))
n))

(bitwise-reverse-bit-field ei1 ei2 ei3)    procedure

Ei2 and ei3 must be non-negative, and ei2 must be less than or equal to ei3. The bitwise-reverse-bit-field procedure returns the result obtained from ei1 by reversing the bit field specified by ei2 and ei3.

(bitwise-reverse-bit-field #b1010010 1 4)
⇒  88 ; #b1011000
(bitwise-reverse-bit-field #1010010 91 -4)
⇒   &assertion exception