# Chapter 8. Numeric Operations

This chapter describes Chez Scheme extensions to the standard set of operations on numbers. See Chapter 6 of The Scheme Programming Language, Third Edition or the Revised5 Report on Scheme for a description of standard operations on numbers.

Chez Scheme supports the full set of Scheme numeric datatypes, including exact and inexact integer, rational, real, and complex numbers. A variety of representations are used to support these datatypes:

Fixnums
represent exact integers in the fixnum range (see most-negative-fixnum and most-positive-fixnum). The length of a string, vector, or fxvector is constrained to be a fixnum.

Bignums
represent arbitrary-precision exact integers outside of the fixnum range.

Ratnums
represent arbitrary-precision exact rational numbers. Each ratnum contains an exact integer (fixnum or bignum) numerator and an exact integer denominator. Ratios are always reduced to lowest terms and never have a denominator of one or a numerator of zero.

Flonums
represent inexact real numbers. Flonums are IEEE 64-bit floating-point numbers. (Since flonums cannot represent irrational numbers, all inexact real numbers are actually rational, although they may approximate irrational quantities.)

Exact complexnums
represent exact complex numbers. Each exact complexnum contains an exact rational (fixnum, bignum, or ratnum) real part and an exact rational imaginary part.

Inexact complexnums
represent inexact complex numbers. Each inexact complexnum contains a flonum real part and a flonum imaginary part.

Most numbers can be represented in only one way; however, real numbers are sometimes represented as inexact complex numbers with imaginary component equal to zero.

Chez Scheme extends the syntax of numbers with arbitrary radixes from two through 36, nondecimal floating-point and scientific notation, and printed representations for IEEE infinities and NANs. (NAN stands for "not-a-number.")

Arbitrary radixes are specified with the prefix #nr, where n ranges from 2 through 36. Digits beyond 9 are specified with the letters (in either upper or lower case) a through z. For example, #2r101 is 510, and #36rZ is 3510.

For higher radixes, an ambiguity arises between the interpretation of certain letters, e.g., e, as digits or exponent specifiers; in such cases, the letter is assumed to be a digit. For example, the e in #x3.2e5 is interpreted as a digit, not as an exponent marker, whereas in 3.2e5 it is treated as an exponent marker.

IEEE infinities are printed as +inf.0 and -inf.0, while IEEE NANs are printed as +nan.0 or -nan.0. (+nan.0 is used on output for all NANs.)

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

The first section of this chapter describes type-specific numeric type predicates. Sections 8.2 through 8.4 describe fast, type-specific numeric operations on fixnums, flonums, and inexact complex numbers (flonums and/or inexact complexnums). The fixnum-specific versions should be used only when the programmer is certain that the operands and results (where appropriate) will be fixnums, i.e., integers in the range (most-negative-fixnum) to (most-positive-fixnum), inclusive. The flonum-specific versions should be used only when the inputs and outputs (where appropriate) are certain to be flonums. The mixed flonum/complexnum versions should be used only when the inputs are certain to be either flonums or inexact complexnums. Section 8.5 describes operations, both arbitrary precision and fixnum-specific, that allow exact integers to be treated as sets or sequences of bits. Random number generation is covered Section 8.6, and miscellaneous numeric operations are covered in the Section 8.7.

### Section 8.1. Numeric Type Predicates

procedure: (fixnum? obj)
returns: #t if obj is a fixnum, otherwise #f

(fixnum? 0)  #t
(fixnum? (most-positive-fixnum))  #t
(fixnum? (most-negative-fixnum))  #t
(fixnum? (* (most-positive-fixnum) 2))  #f
(fixnum? 3/4)  #f
(fixnum? 'a)  #f

procedure: (bignum? obj)
returns: #t if obj is a bignum, otherwise #f

(bignum? 0)  #f
(bignum? (most-positive-fixnum))  #f
(bignum? (most-negative-fixnum))  #f
(bignum? (* (most-positive-fixnum) 2))  #t
(bignum? 3/4)  #f
(bignum? 'a)  #f

procedure: (ratnum? obj)
returns: #t if obj is a ratnum, otherwise #f

(ratnum? 0)  #f
(ratnum? (* (most-positive-fixnum) 2))  #f
(ratnum? 3/4)  #t
(ratnum? -10/2)  #f
(ratnum? -11/2)  #t
(ratnum? 'a)  #f

procedure: (flonum? obj)
returns: #t if obj is a flonum, otherwise #f

(flonum? 0)  #f
(flonum? 3/4)  #f
(flonum? #i3/4)  #t
(flonum? .02)  #t
(flonum? 1e10)  #t
(flonum? 3.0+0.0i)  #f

procedure: (cflonum? obj)
returns: #t if obj is an inexact complexnum or flonum, otherwise #f

(cflonum? 0)  #f
(cflonum? 0.0)  #t
(cflonum? 3+4i)  #f
(cflonum? 3.0+4i)  #t
(cflonum? +i)  #f
(cflonum? +1.0i)  #t

### Section 8.2. Fixnum Operations

At optimization levels 0, 1, and 2 the fixnum-specific procedures check their inputs and outputs (where appropriate), while at optimization level 3 the compiler generates, in most cases, code that does not perform these checks. Fixnum-specific procedure names begin with the prefix "fx" to set them apart from their generic counterparts. The remainder of this section describes the fixnum-specific procedures.

procedure: (most-positive-fixnum)
returns: the most positive fixnum supported by the system

The value returned by most-positive-fixnum determines the most positive value that is valid as input to or output from fixnum-only procedures.

procedure: (most-negative-fixnum)
returns: the most negative fixnum supported by the system

The value returned by most-negative-fixnum determines the most negative value that is valid as input to or output from fixnum-only procedures.

procedure: (fx= fixnum1 fixnum2 ...)
procedure: (fx< fixnum1 fixnum2 ...)
procedure: (fx> fixnum1 fixnum2 ...)
procedure: (fx<= fixnum1 fixnum2 ...)
procedure: (fx>= fixnum1 fixnum2 ...)
returns: #t if the relation holds, #f otherwise

The predicate fx= returns #t if its arguments are equal. The predicate fx< returns #t if its arguments are monotonically increasing, i.e., each argument is greater than the preceding ones, while fx> returns #t if its arguments are monotonically decreasing. The predicate fx<= returns #t if its arguments are monotonically nondecreasing, i.e., each argument is not less than the preceding ones, while fx>= returns #t if its arguments are monotonically nonincreasing. When passed only one argument, each of these predicates returns #t.

(fx= 0)  #t
(fx= 0 0)  #t
(fx< (most-negative-fixnum) 0 (most-positive-fixnum))  #t
(let ([x 3]) (fx<= 0 x 9))  #t
(fx<= 0 3 3)  #t
(fx>= 0 0 (most-negative-fixnum))  #t

procedure: (fxzero? fixnum)
returns: #t if fixnum is zero, #f otherwise

fxzero? is equivalent to (lambda (x) (fx= x 0)).

(fxzero? 0)  #t
(fxzero? 1)  #f

procedure: (fxpositive? fixnum)
returns: #t if fixnum is greater than zero, #f otherwise

fxpositive? is equivalent to (lambda (x) (fx> x 0)).

(fxpositive? 128)  #t
(fxpositive? 0)  #f
(fxpositive? -1)  #f

procedure: (fxnegative? fixnum)
returns: #t if fixnum is less than zero, #f otherwise

fxnegative? is equivalent to (lambda (x) (fx< x 0)).

(fxnegative? -65)  #t
(fxnegative? 0)  #f
(fxnegative? 1)  #f

procedure: (fxnonpositive? fixnum)
returns: #t if fixnum is not greater than zero, #f otherwise

fxnonpositive? is equivalent to (lambda (x) (fx<= x 0)).

(fxnonpositive? 128)  #f
(fxnonpositive? 0)  #t
(fxnonpositive? -1)  #t

procedure: (fxnonnegative? fixnum)
returns: #t if fixnum is not less than zero, #f otherwise

fxnonnegative? is equivalent to (lambda (x) (fx>= x 0)).

(fxnonnegative? -65)  #f
(fxnonnegative? 0)  #t
(fxnonnegative? 1)  #t

procedure: (fxeven? fixnum)
returns: #t if fixnum is even, #f otherwise

(fxeven? 0)  #t
(fxeven? 1)  #f
(fxeven? -1)  #f
(fxeven? -10)  #t

procedure: (fxodd? fixnum)
returns: #t if fixnum is odd, #f otherwise

(fxodd? 0)  #f
(fxodd? 1)  #t
(fxodd? -1)  #t
(fxodd? -10)  #f

procedure: (fx+ fixnum ...)
returns: the sum of the arguments fixnum ...

When called with no arguments, fx+ returns 0.

(fx+)  0
(fx+ 1 2)  3
(fx+ 3 4 5)  12
(apply fx+ '(1 2 3 4 5))  15

procedure: (fx- fixnum1 fixnum2 ...)
returns: a fixnum

When called with one argument, fx- returns the negative of fixnum1. Thus, (fx- fixnum1) is an idiom for (fx- 0 fixnum1).

When called with two or more arguments, fx- returns the result of subtracting the sum of the numbers fixnum2 ... from fixnum1.

(fx- 3)  -3
(fx- 4 3)  1
(fx- 4 3 2 1)  -2

procedure: (fx* fixnum ...)
returns: the product of the arguments fixnum ...

When called with no arguments, fx* returns 1.

(fx*)  1
(fx* 1 2)  2
(fx* 3 -4 5)  -60
(apply fx* '(1 -2 3 -4 5))  120

procedure: (fx/ fixnum1 fixnum2 ...)
returns: see explanation

When called with one argument, fx/ returns the reciprocal of fixnum1. That is, (fx/ fixnum1) is an idiom for (fx/ 1 fixnum1).

When called with two or more arguments, fx/ returns the result of dividing fixnum1 by the product of the remaining arguments fixnum2 ....

(fx/ 1)  1
(fx/ -17)  0
(fx/ 8 -2)  -4
(fx/ -9 2)  -4
(fx/ 60 5 3 2)  2

procedure: (fx1+ fixnum)
procedure: (fx1- fixnum)
returns: fixnum plus 1 or fixnum minus 1

(define fxplus
(lambda (x y)
(if (fxzero? x)
y
(fxplus (fx1- x) (fx1+ y)))))

(fxplus 7 8)  15

fx1+ and fx1- can be defined as follows:

(define fx1+ (lambda (x) (fx+ x 1)))
(define fx1- (lambda (x) (fx- x 1)))

procedure: (fxquotient fixnum1 fixnum2)
returns: see explanation

fxquotient is identical to fx/. See the description of fx/ above.

procedure: (fxremainder fixnum1 fixnum2)
returns: the fixnum remainder of fixnum1 divided by fixnum2

The result of fxremainder has the same sign as fixnum1.

(fxremainder 16 4)  0
(fxremainder 5 2)  1
(fxremainder -45 7)  -3
(fxremainder 10 -3)  1
(fxremainder -17 -9)  -8

procedure: (fxmodulo fixnum1 fixnum2)
returns: the fixnum modulus of fixnum1 and fixnum2

The result of fxmodulo has the same sign as fixnum2.

(fxmodulo 16 4)  0
(fxmodulo 5 2)  1
(fxmodulo -45 7)  4
(fxmodulo 10 -3)  -2
(fxmodulo -17 -9)  -8

procedure: (fxabs fixnum)
returns: the absolute value of fixnum

(fxabs 1)  1
(fxabs -1)  1
(fxabs 0)  0

procedure: (fxmax fixnum1 fixnum2 ...)
returns: the maximum of fixnum1 fixnum2 ...

(fxmax 4 -7 2 0 -6)  4

(let ([ls '(7 3 5 2 9 8)])
(apply fxmax ls))  9

procedure: (fxmin fixnum1 fixnum2 ...)
returns: the minimum of fixnum1 fixnum2 ...

(fxmin 4 -7 2 0 -6)  -7

(let ([ls '(7 3 5 2 9 8)])
(apply fxmin ls))  2

### Section 8.3. Flonum Operations

Inexact real numbers are normally represented by flonums. A flonum is a single 64-bit double-precision floating point number. This section describes operations on flonums, most of which accept flonum arguments and return flonum values. In most cases, the operations are inline-coded or coded as machine language subroutines at optimize-level 3 with no argument type checking; full type checking is performed at lower optimize levels. Flonum-specific procedure names begin with the prefix "fl" to set them apart from their generic counterparts.

Inexact real numbers may also be represented by inexact complexnums with imaginary parts equal to zero, which cannot be used as input to the flonum-specific operators. Such numbers are produced, however, only from operations involving complex numbers with nonzero imaginary parts, by explicit calls to fl-make-rectangular, make-rectangular, or make-polar, or by numeric input in either polar or rectangular format.

procedure: (fixnum->flonum fixnum)
returns: the flonum representation for fixnum

fixnum->flonum is a restricted version of inexact, which converts any numeric representation to its inexact equivalent if one exists.

(fixnum->flonum 0)  0.0
(fixnum->flonum 13)  13.0

procedure: (flonum->fixnum flonum)
returns: the fixnum representation of flonum, truncated

The truncated value of flonum must fall within the fixnum range. flonum->fixnum is a restricted version of exact, which converts any numeric representation to its exact equivalent.

(flonum->fixnum 0.0)  0
(flonum->fixnum 3.9)  3
(flonum->fixnum -2.2)  -2

procedure: (fl= flonum1 flonum2 ...)
procedure: (fl< flonum1 flonum2 ...)
procedure: (fl> flonum1 flonum2 ...)
procedure: (fl<= flonum1 flonum2 ...)
procedure: (fl>= flonum1 flonum2 ...)
returns: #t if the relation holds, #f otherwise

The predicate fl= returns #t if its arguments are equal. The predicate fl< returns #t if its arguments are monotonically increasing, i.e., each argument is greater than the preceding ones, while fl> returns #t if its arguments are monotonically decreasing. The predicate fl<= returns #t if its arguments are monotonically nondecreasing, i.e., each argument is not less than the preceding ones, while fl>= returns #t if its arguments are monotonically nonincreasing. When passed only one argument, each of these predicates returns #t.

IEEE NANs are not comparable, i.e., comparisons involving NANs always return #f.

(fl= 0.0)  #t
(fl= 0.0 0.0)  #t
(fl< -1.0 0.0 1.0)  #t
(fl> -1.0 0.0 1.0)  #f
(fl<= 0.0 3.0 3.0)  #t
(fl>= 4.0 3.0 3.0)  #t
(fl< 7.0 +inf.0)  #t
(fl= +nan.0 0.0)  #f
(fl= +nan.0 +nan.0)  #f
(fl< +nan.0 +nan.0)  #f
(fl> +nan.0 +nan.0)  #f

procedure: (fl+ flonum ...)
returns: the sum of the arguments flonum ...

When called with no arguments, fl+ returns 0.0.

(fl+)  0.0
(fl+ 1.0 2.0)  3.0
(fl+ 3.0 4.0 5.0)  12.0
(apply fl+ '(1.0 2.0 3.0 4.0 5.0))  15.0

procedure: (fl- flonum1 flonum2 ...)
returns: see explanation

When called with one argument, fl- returns the negative of flonum1. When called with two or more arguments, fl- returns the result of subtracting the sum of the numbers flonum2 ... from flonum1.

fl- for one argument is equivalent to

(lambda (x) (fl* -1.0 x))

or

(lambda (x) (fl- -0.0 x))

but not

(lambda (x) (fl- 0.0 x))

since the latter returns 0.0 for 0.0.

(fl- 0.0)  -0.0
(fl- 3.0)  -3.0
(fl- 4.0 3.0)  1.0
(fl- 4.0 3.0 2.0 1.0)  -2.0

procedure: (fl* flonum ...)
returns: the product of the arguments flonum ...

When called with no arguments, fl* returns 1.0.

(fl*)  1.0
(fl* 1.0 2.0)  2.0
(fl* 3.0 -4.0 5.0)  -60.0
(apply fl* '(1.0 -2.0 3.0 -4.0 5.0))  120.0

procedure: (fl/ flonum1 flonum2 ...)
returns: see explanation

When called with one argument, fl/ returns the reciprocal of flonum1. That is, (fl/ flonum1) is an idiom for (fl/ 1.0 flonum1).

When called with two or more arguments, fl/ returns the result of dividing flonum1 by the product of the remaining arguments flonum2 ....

(fl/ -4.0)  -0.25
(fl/ 8.0 -2.0)  -4.0
(fl/ -9.0 2.0)  -4.5
(fl/ 60.0 5.0 3.0 2.0)  2.0

procedure: (flround flonum)
returns: the integer closest to flonum

If flonum is exactly between two integers, the closest even integer is returned.

(flround 17.3)  17.0
(flround 2.5)  2.0
(flround 3.5)  4.0

procedure: (flabs flonum)
returns: absolute value of flonum

flabs is a restricted version of abs or magnitude, which allow either argument to be any valid representation for a real number.

(flabs 3.2)  3.2
(flabs -2e-20)  2e-20

procedure: (decode-float x)
returns: see below

x must be a flonum. decode-float returns a vector with three integer elements, m, e, and s, such that x = sm2e. It is useful primarily in the printing of floating-point numbers.

(decode-float 1.0)  #3(4503599627370496 -52 1)
(decode-float -1.0)  #3(4503599627370496 -52 -1)

(define slow-identity
(lambda (x)
(inexact
(let ((v (decode-float x)))
(let ((m (vector-ref v 0))
(e (vector-ref v 1))
(s (vector-ref v 2)))
(* s m (expt 2 e)))))))

(slow-identity 1.0)  1.0
(slow-identity -1e20)  -1e20

procedure: (fllp flonum)
returns: see below

fllp returns the 12-bit integer consisting of the exponent plus highest order represented bit of a flonum (ieee 64-bit floating-point number). It can be used to compute a fast approximation of the logarithm of the number.

(fllp 0.0)  0
(fllp 1.0)  2046
(fllp -1.0)  2046

(fllp 1.5)  2047

(fllp +inf.0)  4094
(fllp -inf.0)  4094

(fllp #b1.0e-1111111111)  1
(fllp #b1.0e-10000000000)  0

### Section 8.4. Inexact Complex Operations

The procedures described in this section provide mechanisms for creating and operating on inexact complex numbers. Inexact complex numbers with nonzero imaginary parts are represented as inexact complexnums. An inexact complexnum contains two 64-bit double-precision floating point numbers. Inexact complex numbers with imaginary parts equal to zero (in other words, inexact real numbers) may be represented as either inexact complexnums or flonums. The operations described in this section accept any mix of inexact complexnum and flonum arguments (collectively, "cflonums").

In most cases, the operations are performed with minimal type checking at optimize-level 3; full type checking is performed at lower optimize levels. Inexact complex procedure names begin with the prefix "cfl" to set them apart from their generic counterparts.

procedure: (fl-make-rectangular flonum1 flonum2)
returns: an inexact complexnum

The inexact complexnum produced by fl-make-rectangular has real part equal to flonum1 and imaginary part equal to flonum2.

(fl-make-rectangular 2.0 -3.0)  2.0-3.0i
(fl-make-rectangular 2.0 0.0)  2.0+0.0i
(fl-make-rectangular 2.0 -0.0)  2.0-0.0i

procedure: (cfl-real-part cflonum)
returns: the real part of cflonum
procedure: (cfl-imag-part cflonum)
returns: the imaginary part of cflonum

(cfl-real-part 2.0-3.0i)  2.0
(cfl-imag-part 2.0-3.0i)  -3.0
(cfl-imag-part 2.0-0.0i)  -0.0
(cfl-imag-part 2.0-inf.0i)  -inf.0

procedure: (cfl= cflonum1 cflonum2)
returns: #t if cflonum1 is equal to cflonum2, #f otherwise

(cfl= 7.0+0.0i 7.0)  #t
(cfl= 1.0+2.0i 1.0+2.0i)  #t
(cfl= 1.0+2.0i 1.0-2.0i)  #f

procedure: (cfl+ cflonum1 cflonum2)
procedure: (cfl- cflonum1 cflonum2)
procedure: (cfl* cflonum1 cflonum2)
procedure: (cfl/ cflonum1 cflonum2)
returns: a cflonum

These procedures compute the sum, difference, product, or quotient of inexact complex quantities, whether these quantities are represented by flonums or inexact complexnums. For example, if cfl+ receives two flonum arguments a and b, it returns the sum a + b; in this case, it behaves the same as fl+. With two inexact complexnum arguments a + bi and c + di, it returns the sum (a + c) + (b + d)i. If one argument is a flonum a and the other an inexact complexnum c + di, cfl+ returns (a + c) + di.

(cfl+ 1.0+2.2i -3.7+5.3i)  -2.7+7.5i
(cfl+ 1.0 -5.3)  -4.3
(cfl+ 1.0 -5.3i)  1.0-5.3i
(cfl- 1.0+2.5i -3.7)  4.7+2.5i
(cfl* 1.0+2.0i 3.0+4.0i)  -5.0+10.0i
(cfl/ -5.0+10.0i 1.0+2.0i)  3.0+4.0i

procedure: (cfl-conjugate cflonum)
returns: complex conjugate of cflonum

The procedure cfl-conjugate, when passed an inexact complex argument a + bi, returns its complex conjugate a + (-b)i.

See also conjugate, which is a generic version of this operator that returns the complex conjugate of any valid representation for a complex number.

(cfl-conjugate 3.0)  3.0
(cfl-conjugate 3.0+4.0i)  3.0-4.0i
(cfl-conjugate 1e-20-2e-30i)  1e-20+2e-30i

procedure: (cfl-magnitude-squared cflonum)
returns: magnitude of cflonum squared

The procedure cfl-magnitude-squared, when passed an inexact complex argument a + bi returns a flonum representing the magnitude of the argument squared, i.e., a2 + b2.

See also magnitude-squared, which is a generic version of this operator that returns the magnitude squared of any valid representation for a complex number. Both operations are similar to the magnitude procedure, which returns the magnitude, sqrt(a2 + b2), of its generic complex argument.

(cfl-magnitude-squared 3.0)  9.0
(cfl-magnitude-squared 3.0-4.0i)  25.0

### Section 8.5. Bitwise and Logical Operators

Chez Scheme provides a set of logical operators that allow exact integers (fixnums and bignums) to be treated as sets or sequences of bits. These operators include logand (bitwise logical and), logior (bitwise logical or), logxor (bitwise logical exclusive or), lognot (bitwise logical not), logtest (test multiple bits), logbit? (test single bit), logbit0 (reset single bit), logbit1 (set single bit), and ash (arithmetic shift). Each of these operators treats its arguments as two's complement integers, regardless of the underlying representation. This treatment can be exploited to represent infinite sets: a negative number represents an infinite number of one bits beyond the leftmost zero, and a nonnegative number represents an infinite number of zero bits beyond the leftmost one bit.

Fixnum equivalents of the logical operators are provided, as fxlogand, fxlogior, fxlogxor, fxlognot, fxlogtest, fxlogbit?, fxlogbit0, and fxlogbit1. Three separate fixnum operators are provided for shifting: fxsll (shift-left logical), fxsrl (shift-right logical), fxsra (shift-right arithmetic). Logical and arithmetic shifts differ only for right shifts. Shift-right logical shifts in zero bits on the left end, and shift-right arithmetic replicates the sign bit.

Logical shifts do not make sense for arbitrary-precision integers, since these have no "left end" into which bits must be shifted.

procedure: (logand int ...)
returns: the logical "and" of the arguments int ...

The arguments must be exact integers (fixnums or bignums) and are treated as two's complement integers, regardless of the underlying representation. With no arguments, logand returns -1, i.e., all bits set.

(logand)  -1
(logand 15)  15
(logand -1 -1)  -1
(logand -1 0)  0
(logand 5 3)  1
(logand #x173C8D95 7)  5
(logand #x173C8D95 -8)  #x173C8D90
(logand #b1100 #b1111 #b1101)  #b1100

procedure: (logior int ...)
procedure: (logor int ...)
returns: the logical "or" of the arguments int ...

The arguments must be exact integers (fixnums or bignums) and are treated as two's complement integers, regardless of the underlying representation. With no arguments, logior returns 0, i.e., all bits reset.

(logior)  0
(logior 15)  15
(logior -1 -1)  -1
(logior -1 0)  -1
(logior 5 3)  7
(logior #b111000 #b101010)  #b111010
(logior #b1000 #b0100 #b0010)  #b1110
(apply logior '(1 2 4 8 16))  31

procedure: (logxor int ...)
returns: the logical "exclusive or" of the arguments int ...

The arguments must be exact integers (fixnums or bignums) and are treated as two's complement integers, regardless of the underlying representation. With no arguments, logxor returns 0, i.e., all bits reset.

(logxor)  0
(logxor 15)  15
(logxor -1 -1)  0
(logxor -1 0)  -1
(logxor 5 3)  6
(logxor #b111000 #b101010)  #b010010
(logxor #b1100 #b0100 #b0110)  #b1110

procedure: (lognot int)
returns: the logical "not" of int

The argument must be an exact integer (fixnum or bignum) and is treated as a two's complement integer, regardless of the underlying representation.

(lognot -1)  0
(lognot 0)  -1
(lognot 7)  -8
(lognot -8)  7

procedure: (logbit? index int)
returns: #t if the specified bit is set, otherwise #f

index must be a nonnegative exact integer. int must be an exact integer (fixnum or bignum) and is treated as a two's complement integer, regardless of the underlying representation.

logbit? returns #t if the bit at index index of int is set (one) and #f otherwise. The index is zero-based, counting from the lowest-order toward higher-order bits. There is no upper limit on the index; for nonnegative values of int, the bits above the highest order set bit are all considered to be zero, and for negative values, the bits above the highest order reset bit are all considered to be one.

logbit? is equivalent to

(lambda (k n) (not (zero? (logand n (ash 1 k)))))

but more efficient.

(logbit? 0 #b1110)  #f
(logbit? 1 #b1110)  #t
(logbit? 2 #b1110)  #t
(logbit? 3 #b1110)  #t
(logbit? 4 #b1110)  #f
(logbit? 100 #b1110)  #f

(logbit? 0 -6)  #f  ; the two's complement of -6 is 1...1010
(logbit? 1 -6)  #t
(logbit? 2 -6)  #f
(logbit? 3 -6)  #t
(logbit? 100 -6)  #t

(logbit? (random 1000000) 0)  #f
(logbit? (random 1000000) -1)  #t

(logbit? 20000 (ash 1 20000))  #t

procedure: (logtest int1 int2)
returns: #t if any common bits are set, otherwise #f

The arguments must be exact integers (fixnums or bignums) and are treated as two's complement integers, regardless of the underlying representation.

logtest returns #t if any bit set in one argument is also set in the other. It returns #f if the two arguments have no set bits in common.

logtest is equivalent to

(lambda (n1 n2) (not (zero? (logand n1 n2))))

but more efficient.

(logtest #b10001 #b1110)  #f
(logtest #b10101 #b1110)  #t
(logtest #b111000 #b110111)  #t

(logtest #b101 -6)  #f  ; the two's complement of -6 is 1...1010
(logtest #b1000 -6)  #t
(logtest 100 -6)  #t

(logtest (+ (random 1000000) 1) 0)  #f
(logtest (+ (random 1000000) 1) -1)  #t

(logtest (ash #b101 20000) (ash #b111 20000))  #t

procedure: (logbit0 index int)
returns: the result of clearing bit index of int

index must be a nonnegative exact integer. int must be an exact integer (fixnum or bignum) and is treated as a two's complement integer, regardless of the underlying representation.

The index is zero-based, counting from the lowest-order toward higher-order bits. As with logbit?, there is no upper limit on the index.

logbit0 is equivalent to

(lambda (i n) (logand (lognot (ash 1 i)) n))

but more efficient.

(logbit0 3 #b10101010)  #b10100010
(logbit0 4 #b10101010)  #b10101010
(logbit0 0 -1)  -2

procedure: (logbit1 index int)
returns: the result of setting bit index of int

index must be a nonnegative exact integer. int must be an exact integer (fixnum or bignum) and is treated as a two's complement integer, regardless of the underlying representation.

The index is zero-based, counting from the lowest-order toward higher-order bits. As with logbit?, there is no upper limit on the index.

logbit1 is equivalent to

(lambda (i n) (logor (ash 1 i) n))

but more efficient.

(logbit1 3 #b10101010)  #b10101010
(logbit1 4 #b10101010)  #b10111010
(logbit1 4 0)  #b10000
(logbit1 0 -2)  -1

procedure: (ash int count)
returns: int shifted left arithmetically by count.

Both arguments must be exact integers. The first argument is treated as a two's complement integer, regardless of the underlying representation. If count is negative, int is shifted right by -count bits.

(ash 8 0)  8
(ash 8 2)  32
(ash 8 -2)  2
(ash -1 2)  -4
(ash -1 -2)  -1

procedure: (fxlogand fixnum ...)
returns: the logical "and" of the arguments fixnum ...

The arguments are treated as two's complement integers, regardless of the underlying representation. With no arguments, fxlogand returns -1, i.e., all bits set.

(fxlogand)  -1
(fxlogand 15)  15
(fxlogand -1 -1)  -1
(fxlogand -1 0)  0
(fxlogand 5 3)  1
(fxlogand #b111000 #b101010)  #b101000
(fxlogand #b1100 #b1111 #b1101)  #b1100

procedure: (fxlogior fixnum ...)
procedure: (fxlogor fixnum ...)
returns: the logical "or" of the arguments fixnum ...

The arguments are treated as two's complement integers, regardless of the underlying representation. With no arguments, fxlogior returns 0, i.e., all bits reset.

(fxlogior)  0
(fxlogior 15)  15
(fxlogior -1 -1)  -1
(fxlogior -1 0)  -1
(fxlogior #b111000 #b101010)  #b111010
(fxlogior #b1000 #b0100 #b0010)  #b1110
(apply fxlogior '(1 2 4 8 16))  31

procedure: (fxlogxor fixnum ...)
returns: the logical "exclusive or" of the arguments fixnum ...

The arguments are treated as two's complement integers, regardless of the underlying representation. With no arguments, fxlogxor returns 0, i.e., all bits reset.

(fxlogxor)  0
(fxlogxor 15)  15
(fxlogxor -1 -1)  0
(fxlogxor -1 0)  -1
(fxlogxor 5 3)  6
(fxlogxor #b111000 #b101010)  #b010010
(fxlogxor #b1100 #b0100 #b0110)  #b1110

procedure: (fxlognot fixnum)
returns: the logical "not" of fixnum

The argument is treated as a two's complement integer, regardless of the underlying representation.

(fxlognot -1)  0
(fxlognot 0)  -1
(fxlognot 1)  -2
(fxlognot -2)  1

procedure: (fxlogbit? index fixnum)
returns: #t if the specified bit is set, otherwise #f

index must be a nonnegative fixnum. fixnum is treated as a two's complement integer, regardless of the underlying representation.

fxlogbit? returns #t if the bit at index index of fixnum is set (one) and #f otherwise. The index is zero-based, counting from the lowest-order toward higher-order bits. The index is limited only by the fixnum range; for nonnegative values of fixnum, the bits above the highest order set bit are all considered to be zero, and for negative values, the bits above the highest order reset bit are all considered to be one.

(fxlogbit? 0 #b1110)  #f
(fxlogbit? 1 #b1110)  #t
(fxlogbit? 2 #b1110)  #t
(fxlogbit? 3 #b1110)  #t
(fxlogbit? 4 #b1110)  #f
(fxlogbit? 100 #b1110)  #f

(fxlogbit? 0 -6)  #f  ; the two's complement of -6 is 1...1010
(fxlogbit? 1 -6)  #t
(fxlogbit? 2 -6)  #f
(fxlogbit? 3 -6)  #t
(fxlogbit? 100 -6)  #t

(fxlogbit? (random 1000000) 0)  #f
(fxlogbit? (random 1000000) -1)  #t

procedure: (fxlogtest fixnum1 fixnum2)
returns: #t if any common bits are set, otherwise #f

The arguments are treated as two's complement integers, regardless of the underlying representation.

fxlogtest returns #t if any bit set in one argument is also set in the other. It returns #f if the two arguments have no set bits in common.

(fxlogtest #b10001 #b1110)  #f
(fxlogtest #b10101 #b1110)  #t
(fxlogtest #b111000 #b110111)  #t

(fxlogtest #b101 -6)  #f  ; the two's complement of -6 is 1...1010
(fxlogtest #b1000 -6)  #t
(fxlogtest 100 -6)  #t

(fxlogtest (+ (random 1000000) 1) 0)  #f
(fxlogtest (+ (random 1000000) 1) -1)  #t

procedure: (fxlogbit0 index fixnum)
returns: the result of clearing bit index of fixnum

fixnum is treated as a two's complement integer, regardless of the underlying representation. index must be nonnegative and less than the number of bits in a fixnum, excluding the sign bit, i.e., less than (integer-length (most-positive-fixnum)). The index is zero-based, counting from the lowest-order toward higher-order bits.

fxlogbit0 is equivalent to

(lambda (i n) (fxlogand (fxlognot (fxsll 1 i)) n))

but more efficient.

(fxlogbit0 3 #b10101010)  #b10100010
(fxlogbit0 4 #b10101010)  #b10101010
(fxlogbit0 0 -1)  -2

procedure: (fxlogbit1 index fixnum)
returns: the result of setting bit index of fixnum

fixnum is treated as a two's complement integer, regardless of the underlying representation. index must be nonnegative and less than the number of bits in a fixnum, excluding the sign bit, i.e., less than (integer-length (most-positive-fixnum)). The index is zero-based, counting from the lowest-order toward higher-order bits.

fxlogbit1 is equivalent to

(lambda (i n) (fxlogor (fxsll 1 i) n))

but more efficient.

(fxlogbit1 3 #b10101010)  #b10101010
(fxlogbit1 4 #b10101010)  #b10111010
(fxlogbit1 4 0)  #b10000
(fxlogbit1 0 -2)  -1

procedure: (fxsll fixnum count)
returns: fixnum shifted left by count

fixnum is treated as a two's complement integer, regardless of the underlying representation. count must be nonnegative and not more than the number of bits in a fixnum, i.e., (+ (integer-length (most-positive-fixnum)) 1). An overflow error is signaled if the result cannot be represented as a fixnum.

(fxsll 1 2)  4
(fxsll -1 2)  -4

procedure: (fxsrl fixnum count)
returns: fixnum logically shifted right by count

fixnum is treated as a two's complement integer, regardless of the underlying representation. count must be nonnegative and not more than the number of bits in a fixnum, i.e., (+ (integer-length (most-positive-fixnum)) 1).

(fxsrl 4 2)  1
(= (fxsrl -1 1) (most-positive-fixnum))  #t

procedure: (fxsra fixnum count)
returns: fixnum arithmetically shifted right by count

fixnum is treated as a two's complement integer, regardless of the underlying representation. count must be nonnegative and not more than the number of bits in a fixnum, i.e., (+ (integer-length (most-positive-fixnum)) 1).

(fxsra 64 3)  8
(fxsra -1 1)  -1
(fxsra -64 3)  -8

### Section 8.6. Random Number Generation

procedure: (random real)
returns: a nonnegative pseudo-random number less than real

real must be a positive integer or positive inexact real number.

(random 1)  0
(random 1029384535235)  1029384535001, every now and then
(random 1.0)  0.5, every now and then

parameter: random-seed

The random number generator allows the current random seed to be obtained and modified via the parameter random-seed.

When called without arguments, random-seed returns the current random seed. When called with one argument, which must be a nonnegative exact integer ranging from 1 through 232 - 1, random-seed sets the current random seed to the argument.

(let ([s (random-seed)])
(let ([r1 (random 1.0)])
(random-seed s)
(eqv? (random 1.0) r1)))  #t

### Section 8.7. Miscellaneous Numeric Operations

procedure: (1+ num)
procedure: (1- num)
procedure: (-1+ num)
procedure: (sub1 num)
returns: num plus 1 or num minus 1

1+ and add1 are equivalent to (lambda (x) (+ x 1)); 1-, -1+, and sub1 are equivalent to (lambda (x) (- x 1)).

(define plus
; x should be a nonnegative integer
(lambda (x y)
(if (zero? x)
y
(plus (1- x) (1+ y)))))

(plus 7 8)  15

(define double
; x should be a nonnegative integer
(lambda (x)
(if (zero? x)
0

(double 7)  14

procedure: (expt-mod int1 int2 int3)
returns: int1 raised to the int2 power, modulo int3

int1, int2 and int3 must be nonnegative integers. expt-mod performs its computation in such a way that the intermediate results are never much larger than int3. This means that when int2 is large, expt-mod is more efficient than the equivalent procedure (lambda (x y z) (modulo (expt x y) z)).

(expt-mod 2 4 3)  1
(expt-mod 2 76543 76543)  2

procedure: (isqrt n)
returns: the integer square root of n

n must be a nonnegative integer. The integer square root of n is defined to be .

(isqrt 0)  0
(isqrt 16)  4
(isqrt 16.0)  4.0
(isqrt 20)  4
(isqrt 20.0)  4.0
(isqrt (* 2 (expt 10 20)))  14142135623

procedure: (integer-length n)
returns: see below

The procedure integer-length returns the length in bits of the smallest two's complement representation for n, with an assumed leading 1 (sign) bit for negative numbers. For zero, integer-length returns 0.

(integer-length 0)  0
(integer-length 1)  1
(integer-length 2)  2
(integer-length 3)  2
(integer-length 4)  3
(integer-length #b10000000)  8
(integer-length #b11111111)  8
(integer-length -1)  0
(integer-length -2)  1
(integer-length -3)  2
(integer-length -4)  2

procedure: (nonpositive? real)
returns: #t if real is not greater than zero, #f otherwise

nonpositive? is equivalent to (lambda (x) (<= x 0)).

(nonpositive? 128)  #f
(nonpositive? 0.0)  #t
(nonpositive? 1.8e-15)  #f
(nonpositive? -2/3)  #t

procedure: (nonnegative? real)
returns: #t if real is not less than zero, #f otherwise

nonnegative? is equivalent to (lambda (x) (>= x 0)).

(nonnegative? -65)  #f
(nonnegative? 0)  #t
(nonnegative? -0.0121)  #f
(nonnegative? 15/16)  #t

procedure: (conjugate num)
returns: complex conjugate of num

The procedure conjugate, when passed a complex argument a + bi, returns its complex conjugate a + (-b)i.

(conjugate 3.0+4.0i)  3.0-4.0i
(conjugate 1e-20-2e-30i)  1e-20+2e-30i
(conjugate 3)  3

procedure: (magnitude-squared num)
returns: magnitude of num squared

The procedure magnitude-squared, when passed a complex argument a + bi returns its magnitude squared, i.e., a2 + b2.

(magnitude-squared 3.0-4.0i)  25.0
(magnitude-squared 3.0)  9.0

procedure: (sinh num)
procedure: (cosh num)
procedure: (tanh num)
returns: the hyperbolic sine, cosine, or tangent of num

(sinh 0.0)  0.0
(cosh 0.0)  1.0
(tanh -0.0)  -0.0

procedure: (asinh num)
procedure: (acosh num)
procedure: (atanh num)
returns: the hyperbolic arc sine, arc cosine, or arc tangent of num

(acosh 0.0)  0.0+1.5707963267948966i
(acosh 1.0)  0.0
(atanh -1.0)  -inf.0

procedure: (inexact num)
returns: an inexact representation for num

If num is already inexact, it is returned unchanged. If no inexact representation for num is supported by the implementation, an error may be signaled.

inexact and exact->inexact are identical. The former is the Revised6 Report name.

(inexact 3)  3.0
(inexact 3.0)  3.0
(inexact -1/4)  -.25
(inexact 3+4i)  3.0+4.0i
(inexact (expt 10 20))  1e20

procedure: (exact num)
returns: an exact representation for num

If num is already exact, it is returned unchanged. If no exact representation for num is supported by the implementation, an error may be signaled.

(exact 3.0)  3
(exact 3)  3
(exact -.25)  -1/4
(exact 3.0+4.0i)  3+4i
(exact 1e20)  100000000000000000000

exact and inexact->exact are identical. The former is the Revised6 Report name.

R. Kent Dybvig / Chez Scheme Version 7 User's Guide