6.2 Numbers

Gauche supports the following types of numbers

multi-precision exact integer

There's no limit of the size of number except the memory of the machine.

multi-precision exact non-integral rational numbers.

Both denominator and numerator are represented by exact integers. There's no limit of the size of number except the memory of the machine.

inexact floating-point real numbers

Using double-type of underlying C compiler, usually IEEE 64-bit floating point number.

inexact floating-point complex numbers

Real part and imaginary part are represented by inexact floating-point real numbers.

6.2.1 Number classes

Builtin Class: <number>

Builtin Class: <complex>

Builtin Class: <real>

Builtin Class: <rational>

Builtin Class: <integer>

These classes consist a class hierarchy of number objects. <complex> inherits <number>, <real> inherits <complex>,<rational> inherits <real> and <integer> inherits <rational>.

Note that these classes does not exactly corresponds to the number hierarchy defined in R5RS. Especially, only exact integers are the instances of the <integer> class. That is,

(integer? 1) ⇒ #t (is-a? 1 <integer>) ⇒ #t (is-a? 1 <real>) ⇒ #t (integer? 1.0) ⇒ #t (is-a? 1.0 <integer>) ⇒ #f (is-a? 1.0 <real>) ⇒ #t (class-of (expt 2 100)) ⇒ #<class <integer>> (class-of (sqrt -3)) ⇒ #<class <complex>>

6.2.2 Numerical predicates

Function: number? obj

Function: complex? obj

Function: real? obj

Function: rational? obj

Function: integer? obj

[R5RS] Returns #t if obj is a number, a complex number, a real number, a rational number or an integer, respectively. In Gauche, a set of numbers is the same as a set of complex numbers, and a set of rational numbers is the same as a set of real numbers (since we have only limited-precision floating numbers).

(complex? 3+4i) ⇒ #t (complex? 3) ⇒ #t (real? 3) ⇒ #t (real? -2.5+0.0i) ⇒ #t (real? #e1e10) ⇒ #t (integer? 3+0i) ⇒ #t (integer? 3.0) ⇒ #t

Function: exact? obj

Function: inexact? obj

[R5RS] Returns #t if obj is an exact number and an inexact number, respectively.

(exact? 1) ⇒ #t (exact? 1.0) ⇒ #f (inexact? 1) ⇒ #f (inexact? 1.0) ⇒ #t (exact? (modulo 5 3)) ⇒ #t (inexact? (modulo 5 3.0)) ⇒ #f

Function: zero? z

[R5RS] Returns #t if a number z equals to zero.

(zero? 1) ⇒ #f (zero? 0) ⇒ #t (zero? 0.0) ⇒ #t (zero? 0.0+0.0i) ⇒ #t

Function: positive? x

Function: negative? x

[R5RS] Returns #t if a real number x is positive and negative, respectively. It is an error to pass a non-real number.

Function: odd? n

Function: even? n

[R5RS] Returns #t if an integer n is odd and even, respectively. It is an error to pass a non-integral number.

(odd? 3) ⇒ #t (even? 3) ⇒ #f (odd? 3.0) ⇒ #t

Function: fixnum? n

Function: bignum? n

Returns #t iff n is an exact integer whose internal representation is fixnum and bignum, respectively. Portable Scheme programs don't need to care about the internal representation of integer. These are for certain low-level routines that does particular optimization.

6.2.3 Numerical comparison

Function: = z1 z2 z3 …

[R5RS] If all the numbers z are equal, returns #t.

(= 2 2) ⇒ #t (= 2 3) ⇒ #f (= 2 2.0) ⇒ #t (= 2 2.0 2.0+0i) ⇒ #t (= 2/4 1/2) ⇒ #t

Function: < x1 x2 x3 …

Function: <= x1 x2 x3 …

Function: > x1 x2 x3 …

Function: >= x1 x2 x3 …

[R5RS] Returns #t If all the real numbers x are monotonically increasing, monotonically nondecreasing, monotonically decreasing, or monotonically nonincreasing, respectively.

Function: max x1 x2 …

Function: min x1 x2 …

[R5RS] Returns a maximum or minimum number in the given real numbers, respectively.

Function: min&max x1 x2 …

Returns a maximum and minimum number in the given real numbers.

6.2.4 Arithmetics

Function: + z …

Function: * z …

[R5RS] Returns the sum or the product of given numbers, respectively. If no argument is given, (+) yields 0 and (*) yields 1.

Function: - z1 z2 …

Function: / z1 z2 …

[R5RS] If only one number z1 is given, returns its negation and reciprocal, respectively.

If more than one number are given, returns:

z1 - z2 - z3 … z1 / z2 / z3 …

respectively.

(- 3) ⇒ -3 (- -3.0) ⇒ 3.0 (- 5+2i) ⇒ -5.0-2.0i (/ 3) ⇒ 1/3 (/ 5+2i) ⇒ 0.172413793103448-0.0689655172413793i (- 5 2 1) ⇒ 2 (- 5 2.0 1) ⇒ 2.0 (- 5+3i -i) ⇒ 5.0+2.0i (/ 14 6) ⇒ 7/3 (/ 6+2i 2) ⇒ 3.0+1.0i

Note: Gauche didn't have exact rational number support until 0.8.8; before that, / coerced the result to inexact even if both divisor and dividend were exact numbers, when the result wasn't a whole number. It is not the case anymore.

If the existing code relies on the old behavior, it runs very slowly on the newer versions of Gauche, since the calculation proceeds with exact rational arithmetics that is much slower than floating point arithmetics. You want to use /. below to use fast inexact arithmetics (unless you need exact results).

Function: +. z …

Function: *. z …

Function: -. z1 z2 …

Function: /. z1 z2 …

Like +, *, -, and /, but the arguments are coerced to inexact number. So they always return inexact number. These are useful when you know you don't need exact calculation and want to avoid accidental overhead of bignums and/or exact rational numbers.

Function: abs z

[R5RS+] For real number z, returns an absolute value of it. For complex number z, returns the magnitude of the number. The complex part is Gauche extension.

(abs -1) ⇒ 1 (abs -1.0) ⇒ 1.0 (abs 1+i) ⇒ 1.4142135623731

Function: quotient n1 n2

Function: remainder n1 n2

Function: modulo n1 n2

[R5RS] Returns the quotient, remainder and modulo of dividing an integer n1 by an integer n2. The result is an exact number only if both n1 and n2 are exact numbers.

Remainder and modulo differ when either one of the arguments is negative. Remainder R and quotient Q have the following relationship.

n1 = Q * n2 + R

where abs(Q) = floor(abs(n1)/abs(n2)). Consequently, R's sign is always the same as n1's.

On the other hand, modulo works as expected for positive n2, regardless of the sign of n1 (e.g. (modulo -1 n2) == n2 - 1). If n2 is negative, it is mapped to the positive case by the following relationship.

modulo(n1, n2) = -modulo(-n1, -n2)

Consequently, modulo's sign is always the same as n2's.

(remainder 10 3) ⇒ 1 (modulo 10 3) ⇒ 1 (remainder -10 3) ⇒ -1 (modulo -10 3) ⇒ 2 (remainder 10 -3) ⇒ 1 (modulo 10 -3) ⇒ -2 (remainder -10 -3) ⇒ -1 (modulo -10 -3) ⇒ -1

Function: quotient&remainder n1 n2

Calculates the quotient and the remainder of dividing integer n1 by integer n2 simultaneously, and returns them as two values.

Function: gcd n …

Function: lcm n …

[R5RS] Returns the greatest common divisor or the least common multiplier of the given integers, respectively

Function: numerator q

Function: denominator q

[R5RS] Returns the numerator and denominator of a rational number q.

Function: floor x

Function: ceiling x

Function: truncate x

Function: round x

[R5RS] The argument x must be a real number. Floor and ceiling return a maximum integer that isn't greater than x and a minimum integer that isn't less than x, respectively. Truncate returns an integer that truncates x towards zero. Round returns an integer that is closest to x. If fractional part of x is exactly 0.5, round returns the closest even integer.

Function: floor->exact x

Function: ceiling->exact x

Function: truncate->exacte x

Function: round->exact x

These are convenience procedures of the popular phrase (inexact->exact (floor x)) etc.

Function: clamp x &optional min max

Returns

min if x < min x if min <= x <= max max if max < x

If min or max is omitted or #f, it is regarded as -infinity or +infinity, respectively. Returns an exact integer only if all the given numbers are exact integers.

(clamp 3.1 0.0 1.0) ⇒ 1.0 (clamp 0.5 0.0 1.0) ⇒ 0.5 (clamp -0.3 0.0 1.0) ⇒ 0.0 (clamp -5 0) ⇒ 0 (clamp 3724 #f 256) ⇒ 256

Function: exp z

Function: log z

Function: log z1 z2

Function: sin z

Function: cos z

Function: tan z

Function: asin z

Function: acos z

Function: atan z

[R5RS][R6RS] Transcendental functions. Work for complex numbers as well.

The two-argument version of log is added in R6RS, and returns base-z2 logarithm of z1.

Function: atan y x

[R5RS] For real numbers x and y, returns atan(y/x).

Function: sinh z

Function: cosh z

Function: tanh z

Function: asinh z

Function: acosh z

Function: atanh z

Hyperbolic trigonometric functions. Work for complex numbers as well.

Function: sqrt z

[R5RS] Returns a square root of a complex number z. The branch cut scheme is the same as Common Lisp. For real numbers, it returns a positive root.

Function: expt z1 z2

[R5RS] Returns z1^z2 (z1 powered by z2), where z1 and z2 are complex numbers.

Function: fixnum-width

Function: greatest-fixnum

Function: least-fixnum

[R6RS] These procedures return the width of fixnum (w), the greatest integer representable by fixnum (2^w - 1), and the least integer representable by fixnum (- 2^w), respectively. You might want to care the fixnum range when you are writing a performance-critical section.

These names are defined in R6RS. Common Lisp and ChezScheme have most-positive-fixnum and most-negative-fixnum.

6.2.5 Numerical conversions

Function: make-rectangular x1 x2

Function: make-polar x1 x2

[R5RS] Creates a complex number from two real numbers, x1 and x2. make-rectangular returns x1 + ix2. make-polar returns x1e^(ix2).

Function: real-part z

Function: imag-part z

Function: magnitude z

Function: angle z

[R5RS] Decompose a complex number z and returns a real number. real-part and imag-part return z's real and imaginary part, respectively. magnitude and angle return z's magnitude and angle, respectively.

Function: decode-float x

For a given floating-point number, returns a vector of three exact integers, #(m, e, sign), where

x = (* sign m (expt 2.0 e)) sign is either 1, 0 or -1.

The API is taken from ChezScheme.

(decode-float 3.1415926) ⇒ #(7074237631354954 -51 1) (* 7074237631354954 (expt 2.0 -51)) ⇒ 3.1415926

Function: fmod x y

Function: modf x

Function: frexp x

Function: ldexp x n

[POSIX] These procedures can be used to compose and decompose floating point numbers. Fmod computes the remainder of dividing x by y, that is, it returns x-n*y where n is the quotient of x/y rounded towards zero to an integer. Modf returns two values; a fractional part of x and an integral part of x. Frexp returns two values, fraction and exponent of x, where x = fraction * 2^exponent, and 0 <= fraction <= 0.5. Ldexp is a reverse operation of frexp; it returns a real number x * 2^n.

(fmod 32.1 10.0) ⇒ 2.1 (fmod 1.5 1.4) ⇒ 0.1 (modf 12.5) ⇒ 0.5 and 12.0 (frexp 3.14) ⇒ 0.785 and 2 (ldexp 0.785 2) ⇒ 3.14

Function: exact->inexact z

Function: inexact->exact z

[R5RS] Converts an exact number to an inexact number, or vice versa.

Since we have finite precision to represent floating numbers, it is always possible to convert arbitrary inexact real number to an exact rational number. It may not be what you want, though. See the following example:

(inexact->exact 3.1415926535879) ⇒ 7074237752024177/2251799813685248

If you intend to obtain an exact integer by rounding an inexact real number, you have to use one of floor, ceiling, truncate or round explicitly. You may also use floor->exact, round->exact etc.

(inexact->exact (round 3.1415926535879)) ⇒ 3 (round->exact 3.1415926535879) ⇒ 3

Gauche doesn't support exact complex numbers. Passing an inexact complex number with non-zero imaginary part to inexact->exact causes an error.

If you pass an inexact number to exact->inexact or an exact number to inexact->exact, Gauche returns the argument as is, instead of reporting an error. This is also an implementation dependent behavior and you shouldn't count on that.

Function: number->string z &optional radix use-upper?

Function: string->number string &optional radix

[R5RS+] These procedures convert a number and its string representation in radix radix system. radix must be between 2 and 36 inclusive. If radix is omitted, 10 is assumed.

Number->string takes a number z and returns a string. If z is not an exact integer, radix must be 10. For the numbers with radix more than 10, lower case alphabet character is used for digits, unless the optional argument use-upper? is true, in that case upper case characters are used. The argument use-upper? is Gauche's extension.

String->number takes a string string and parses it as a number in radix radix system. If the number looks like non-exact number, only radix 10 is allowed. If the given string can't be a number, #f is returned.

Generic Function: x->number obj

Generic Function: x->integer obj

Generic coercion functions. Returns `natural' interpretation of obj as a number or an exact integer, respectively. The default methods are defined for numbers and strings; a string is interpreted by string->number, and if the string can't be interpreted as a number, 0 is returned. Other obj is simply converted to 0. If obj is naturally interpreted as a number that is not an exact integer, x->integer uses round and inexact->exact to obtain an integer.

Other class may provide a method to customize the behavior.

6.2.6 Bitwise operations

These procedures treat integers as half-open bit vectors. If an integer is positive, it is regarded as if infinite number of zeros are padded to the left. If an integer is negative, it is regarded in 2's complement form, and infinite number of 1's are padded to the left.

The API is consistent to SLIB's “logical” module.

Function: ash n count

Shifts integer n left with count bits. If count is negative, ash shifts n right with -count bits.

; Note: 6 ≡ [...00110], and ; -6 ≡ [...11010] (ash 6 2) ⇒ 24 ;[...0011000] (ash 6 -2) ⇒ 1 ;[...0000001] (ash -6 2) ⇒ -24 ;[...1101000] (ash -6 -2) ⇒ -2 ;[...1111110]

Function: logand n1 n2 …

Function: logior n1 n2 …

Function: logxor n1 n2 …

Returns bitwise and, bitwise inclusive or and bitwise exclusive or of two or more integers n1, n2 ….

Function: lognot n

Returns bitwise not of an integer n.

Function: logtest n1 n2 …

≡ (not (zero? (logand n1 n2 …)))

Function: logbit? index n

Returns #t if index-th bit of integer n is 1, #f otherwise.

Function: bit-field n start end

Extracts start-th bit (inclusive) to end-th bit (exclusive) from an exact integer n, where start < end.

Function: copy-bit index n bit

If bit is true, sets index-th bit of an exact integer n. If bit is false, resets index-th bit of an exact integer n.

Function: copy-bit-field n start end from

Returns an exact integer, each bit of which is the same as n except the start-th bit (inclusive) to end-th bit (exclusive), which is a copy of the lower (end-start)-th bits of an exact integer from.

(number->string (copy-bit-field #b10000000 1 5 -1) 2) ⇒ "10011110" (number->string (copy-bit-field #b10000000 1 7 #b010101010) 2) ⇒ "11010100"

Function: logcount n

If n is positive, returns the number of 1's in the bits of n. If n is negative, returns the number of 0's in the bits of 2's complement representation of n.

(logcount 0) ⇒ 0 (logcount #b0010) ⇒ 1 (logcount #b0110) ⇒ 2 (logcount #b1111) ⇒ 4 (logcount #b-0001) ⇒ 0 ;; 2's complement: ....111111 (logcount #b-0010) ⇒ 1 ;; 2's complement: ....111110 (logcount #b-0011) ⇒ 1 ;; 2's complement: ....111101 (logcount #b-0100) ⇒ 2 ;; 2's complement: ....111100

Function: integer-length n

Returns the minimum number of bits required to represent an exact integer n. Negative integer is assumed to be in 2's complement form. A sign bit is not considered.

(integer-length 255) ⇒ 8 (integer-length 256) ⇒ 9 (integer-length -256) ⇒ 8 (integer-length -257) ⇒ 9

This document was generated by Shiro Kawai on October, 7 2008 using texi2html 1.78.