6.3.2 Numerical predicates

Function: number?obj

Function: complex?obj

Function: real?obj

Function: rational?obj

Function: integer?obj

[R7RS]
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.
A set of rational numbers is the same as a set of real numbers,
except +inf.0, -inf.0 and +nan.0
(since we have only limited-precision floating numbers).

Note: R6RS adopts more strict definition on exactness,
and notably, it defines a complex number with non-exact zero imaginary
part is not a real number. Currently Gauche doesn’t have
exact complex numbers, and automatically coerces complex
numbers with zero imaginary part to a real number.
Thus R6RS code that relies on the fact that (real? 1+0.0i) is
#f won’t work with Gauche.

Function: real-valued?obj

Function: rational-valued?obj

Function: integer-valued?obj

[R6RS]
In Gauche these are just an alias of real?, rational?
and integer?. They are provided for R6RS compatibility.

The difference of those and non -valued versions in R6RS is
that these returns #t if obj is a complex number
with nonexact zero imaginary part. Since Gauche doesn’t distinguish
complex numbers with zero imaginary part and real numbers, we don’t
have the difference.

Function: exact?obj

Function: inexact?obj

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

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

Function: finite?z

Function: infinite?z

Function: nan?z

[R7RS]
For real numbers, returns #f iff the given number
is finite, infinite, or NaN, respectively.

For non-real complex numbers, finite? returns #t iff
both real and imaginary components are finite, infinite?
returns #t if at least either real or imaginary component
is infinite, and nan? returns #t if at least either
real or imaginary component is NaN. (Note: It is incompatible
to R6RS, in which these procedures must raise an error if
the given argument is non-real number.)

In R7RS, these procedures are in (scheme inexact) library.

Function: odd?n

Function: even?n

[R7RS]
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.

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: absz

[R7RS+]
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: quotientn1 n2

Function: remaindern1 n2

Function: modulon1 n2

[R7RS]
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.

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

Function: divx y

Function: modx y

Function: div-and-modx y

Function: div0x y

Function: mod0x y

Function: div0-and-mod0x y

[R6RS]
These are integer division procedures introduced in R6RS.
Unlike quotient, modulo and remainder,
these procedures can take non-integral values.
The dividend x can be an arbitrary real number,
and the divisor y can be non-zero real number.

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

Arguments must be integers, but doesn’t need to be exact.
If any of arguments is inexact, the result is inexact.

Function: continued-fractionx

Returns a lazy sequence of regular continued fraction expansion of
finite real number x. An error is raised if x is infinite or
NaN, or not a real number.
The returned sequence is lazy, so the terms are calculated as needed.

[R7RS]
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.

Following Scheme’s general rule, the result is inexact if x is an
inexact number; e.g. (round 2.3) is 2.0. If you need
an exact integer by rounding an inexact number, you have to use exact
on the result, or use one of the following procedure ((floor->exact etc).

Function: floor->exactx

Function: ceiling->exactx

Function: truncate->exactx

Function: round->exactx

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

Function: clampx :optional min max

Returns

minifx<minxifmin<=x<=maxmaxifmax<x

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

NB: Mathematically these functions are defined in complex domain, but
currently we only supports real number argument.

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) - 1),
and the least integer representable by fixnum (- 2^(w-1)),
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.

NB: Before 0.9.5, fixnum-width had a bug
to return one smaller than the supposed value.

[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.5 <= |fraction| < 1.0, unless x is zero.
(When x is zero, both fraction and exponent are zero).
Ldexp is a reverse operation of
frexp; it returns a real number x * 2^n.

[R7RS]
Returns an exact or an inexact representation of the
given number z, respectively. Passing an exact number
to exact, and an inexact number to inexact, are no-op.

Gauche doesn’t have exact complex number with non-zero imaginary part,
nor exact infinites and NaNs, so passing those to exact raises
an error.

(inexact 1) ⇒ 1.0
(inexact 1/10) ⇒ 0.1

If an inexact finite real number is passed to exact,
the simplest exact rational number within the precision of the
floating point representation is returned.

(exact 1.0) ⇒ 1
(exact 0.1) ⇒ 1/10
(exact (/ 3.0)) ⇒ 1/3

For all finite inexact real number x,
(inexact (exact x)) is always eqv? to
the original number x.

(Note that the inverse doesn’t hold, that is, an exact number n
and (exact (inexact n)) aren’t necessarily the same.
It’s because many (actually, infinite number of) exact numbers
can be mapped to one inexact number.)

To specify the error tolerance when converting inexact real numbers
to exact rational numbers, use rationalize or real->rational.

Function: exact->inexactz

Function: inexact->exactz

[R5RS]
Converts exact number to inexact one, and vice versa.

In fact, exact->inexact returns the argument as is
if an inexact number is passed, and inexact->exact
returns the argument if an exact number is passed, so
in Gauche they are equivalent to inexact and exact,
respectively. Note that other R5RS implementation may raise
an error if passing an inexact number to exact->inexact,
for example.

Generally exact and inexact are preferred,
for they are more concise, and you don’t need to care
whether the argument is exact or inexact numbers.
These procedures are for compatibility with R5RS programs.

Function: real->rationalx :optional hi lo open?

Find the simplest rational representation of a finite real
number x within the specified error bounds. This is the low-level
routine called by rationalize and exact.

If hi and/or lo is omitted, it is determined by x:
if x is exact, hi and lo are defaulted to zero; if
x is inexact, hi and lo depend on
the precision of the floating point representation of x.
In the latter case, the open? also depends on x—it is true
if the mantissa of x is odd, and false otherwise, reflecting
the round-to-even rule. So, if you call real->rational with
one finite number, you’ll get the same result as exact:

(real->rational 0.1) ⇒ 1/10

Passing zeros to the error bounds makes it return the exact
conversion of the floating number itself (that is, the exact
calculation of (* sign mantissa (expt 2 exponent))).

(real->rational 0.1 0 0) ⇒ 3602879701896397/36028797018963968

(If you give both hi and lo, but omit open?,
we assume closed range.)

Function: number->stringz :optional radix use-upper?

Function: string->numberstring :optional radix

[R7RS+]
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->numberobj

Generic Function: x->integerobj

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.

6.3.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.

In regard to the names of those operations, there are two groups
in the Scheme world; Gauche follows the names of the
original SLIB’s “logical” module, which was rooted in CL.
Another group uses a bit long but descriptive name such as
arithmetic-shift.

SRFI-60 (see Integers as bits) defines both names, and also
some additional procedures. If you’re porting libraries written
for other Scheme, you might want to check it.

Function: ashn count

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

[SRFI-60]
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-fieldn from start end

[SRFI-60]
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.

Note: The API of this procedure was originally taken from SLIB,
and at that time,
the argument order was (copy-bit-field n start end from).
During the discussion of SRFI-60 the argument order was changed
for the consistency, and the new versions of SLIB followed it.
We didn’t realize the change until recently - before 0.9.4,
this procedure had the old argument order. Code that is using
this procedure needs to be fixed. If you need your code to work
with both versions of Gauche, have the following definition
in your code.

6.3.7 Endianness

In the Scheme world you rarely need to know about how the numbers
are represented inside the machine. However, it matters
when you have to exchange data to/from the outer world in
binary representation.

Gauche’s binary I/O procedures, such as in
the binary.io module (see Binary I/O) and
write-uvector/read-uvector!
(see Uniform vectors), take optional endian argument
to specify the endianness.

Currently Gauche recognizes the following endiannesses.

big-endian

Big endian. With this endianness, a 32-bit integer #x12345678
will be written out as an octet sequence #x12 #x34 #x56 #x78.

little-endian

Little endian. With this endianness, a 32-bit integer #x12345678
is written out as an octet sequence #x78 #x56 #x34 #x12.

arm-little-endian

This is a variation of little-endian, and used in ARM
processors in some specific modes. It works just like little-endian,
except reading/writing double-precision floating point number (f64),
which is written as two little-endian 32bit words ordered by big-endian
(e.g. If machine register’s representation is #x0102030405060708,
it is written as #x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05.

When the endian argument is omitted, those procedures
use the parameter default-endian:

Parameter: default-endian

This is a dynamic parameter (see Parameters) to specify
the endianness the binary I/O routines use when its endian
argument is omitted. The initial value of this parameter is
the system’s native endianness.

The system’s native endianness can be queried with the following
procedure: