Numbers and Arithmetic¶
Kaappi supports a full numeric tower: fixnums (63-bit integers), bignums
(arbitrary precision), exact rationals, flonums (IEEE 754 f64), and complex
numbers. These procedures are available from (scheme base) and
(scheme inexact).
Basic Arithmetic¶
+¶
Syntax: (+ z1 ...)
Returns the sum of its arguments. With no arguments, returns 0 (the
additive identity). Accepts any combination of number types: when all
arguments are exact integers the result is exact, when any argument is
inexact the result is inexact, and when any argument is complex the
result is complex. Arithmetic on fixnums that overflows is transparently
promoted to bignums.
-¶
Syntax: (- z) or (- z1 z2 ...)
With one argument, returns the additive inverse (negation). With two or
more arguments, returns the result of subtracting all subsequent arguments
from the first. Like +, the result type follows the usual exactness
and type-promotion rules.
See also: +
*¶
Syntax: (* z1 ...)
Returns the product of its arguments. With no arguments, returns 1
(the multiplicative identity). Handles exact integers, rationals,
flonums, and complex numbers. Fixnum overflow is transparently promoted
to bignums.
/¶
Syntax: (/ z) or (/ z1 z2 ...)
With one argument, returns the multiplicative inverse (reciprocal). With
two or more arguments, divides the first argument by all subsequent ones.
Division of exact integers produces exact rationals rather than inexact
flonums: (/ 1 3) returns 1/3, not 0.333.... Division by zero
raises an error that can be caught with guard.
kaappi> (/ 10 2)
;=> 5
kaappi> (/ 1 3)
;=> 1/3
kaappi> (/ 4)
;=> 1/4
kaappi> (/ 10 3)
;=> 10/3
kaappi> (/ 6.0 2.0)
;=> 3.0
Note
Exact integer division always produces an exact result. Use
(inexact (/ 1 3)) if you need a flonum.
See also: quotient, remainder, floor/
quotient¶
Syntax: (quotient n1 n2)
Returns the integer quotient of n1 divided by n2, truncated toward
zero. This is the same operation as truncate-quotient. Works with
fixnums, bignums, and flonums. Division by zero raises an error.
See also: remainder, modulo, truncate-quotient
remainder¶
Syntax: (remainder n1 n2)
Returns the remainder after dividing n1 by n2 with truncation toward
zero. The sign of the result always matches the sign of n1. This is
the same operation as truncate-remainder.
See also: quotient, modulo, truncate-remainder
modulo¶
Syntax: (modulo n1 n2)
Returns the modulo of n1 divided by n2. Unlike remainder, the sign
of the result always matches the sign of n2. This makes modulo useful
for cyclic arithmetic (e.g., clock calculations). Works with fixnums,
bignums, and flonums.
See also: remainder, floor-remainder
Comparisons¶
=¶
Syntax: (= z1 z2 z3 ...)
Returns #t if all arguments are numerically equal. Compares across
number types: (= 1 1.0) is #t. Comparisons involving NaN always
return #f. Complex numbers are compared component-wise.
kaappi> (= 1 1)
;=> #t
kaappi> (= 1 1.0)
;=> #t
kaappi> (= 1 2)
;=> #f
kaappi> (= +nan.0 +nan.0)
;=> #f
<¶
Syntax: (< x1 x2 x3 ...)
Returns #t if the arguments are monotonically increasing (each
argument is strictly less than the next). Works with all real number
types. Comparisons involving NaN return #f.
>¶
Syntax: (> x1 x2 x3 ...)
Returns #t if the arguments are monotonically decreasing (each
argument is strictly greater than the next). Works with all real number
types. Comparisons involving NaN return #f.
<=¶
Syntax: (<= x1 x2 x3 ...)
Returns #t if the arguments are monotonically non-decreasing (each
argument is less than or equal to the next). Works with all real number
types. Comparisons involving NaN return #f.
>=¶
Syntax: (>= x1 x2 x3 ...)
Returns #t if the arguments are monotonically non-increasing (each
argument is greater than or equal to the next). Works with all real
number types. Comparisons involving NaN return #f.
Predicates¶
zero?¶
Syntax: (zero? z)
Returns #t if z is zero. Works with fixnums, flonums, bignums, and
complex numbers (both real and imaginary parts must be zero).
positive?¶
Syntax: (positive? x)
Returns #t if x is strictly greater than zero. Works with fixnums,
flonums, bignums, and rationals. For rationals, the sign is determined by
the numerator (the denominator is always positive).
kaappi> (positive? 1)
;=> #t
kaappi> (positive? 1.5)
;=> #t
kaappi> (positive? 0)
;=> #f
kaappi> (positive? -1)
;=> #f
negative?¶
Syntax: (negative? x)
Returns #t if x is strictly less than zero. Works with fixnums,
flonums, bignums, and rationals.
kaappi> (negative? -1)
;=> #t
kaappi> (negative? -2.3)
;=> #t
kaappi> (negative? 0)
;=> #f
kaappi> (negative? 1)
;=> #f
even?¶
Syntax: (even? n)
Returns #t if the integer n is even. Works with fixnums, bignums,
and integer-valued flonums.
See also: odd?
odd?¶
Syntax: (odd? n)
Returns #t if the integer n is odd. Works with fixnums, bignums,
and integer-valued flonums.
See also: even?
exact?¶
Syntax: (exact? z)
Returns #t if z is an exact number: fixnums, bignums, and exact
rationals are exact. Flonums are inexact. Complex numbers are exact only
when both parts carry the exact flag.
inexact?¶
Syntax: (inexact? z)
Returns #t if z is an inexact number. Flonums are inexact. Complex
numbers are inexact if either part is inexact.
exact-integer?¶
Syntax: (exact-integer? z)
Returns #t if z is both exact and an integer. Fixnums and bignums
return #t; flonums (even integer-valued ones like 3.0) return #f.
kaappi> (exact-integer? 42)
;=> #t
kaappi> (exact-integer? 3.0)
;=> #f
kaappi> (exact-integer? 1/3)
;=> #f
finite?¶
Syntax: (finite? z)
Returns #t if z is finite. All exact numbers (fixnums, bignums,
rationals) are always finite. Flonums are finite unless they are
+inf.0, -inf.0, or +nan.0. For complex numbers, both parts must
be finite.
infinite?¶
Syntax: (infinite? z)
Returns #t if z is positive or negative infinity. Exact numbers are
never infinite. For complex numbers, returns #t if either part is
infinite.
nan?¶
Syntax: (nan? z)
Returns #t if z is NaN (Not a Number). Exact numbers are never NaN.
For complex numbers, returns #t if either part is NaN.
Min / Max / Abs¶
abs¶
Syntax: (abs x)
Returns the absolute value of x. Works with fixnums, bignums, flonums,
and rationals. For rationals, only the numerator's sign changes (the
denominator is always positive).
See also: magnitude
min¶
Syntax: (min x1 x2 ...)
Returns the smallest of its arguments. If any argument is inexact, the result is inexact. Works with fixnums, bignums, flonums, and rationals.
See also: max
max¶
Syntax: (max x1 x2 ...)
Returns the largest of its arguments. If any argument is inexact, the result is inexact. Works with fixnums, bignums, flonums, and rationals.
See also: min
GCD / LCM¶
gcd¶
Syntax: (gcd n1 ...)
Returns the greatest common divisor of its arguments. With no arguments,
returns 0. The result is always non-negative. Works with fixnums,
bignums, and flonums (which return an inexact result).
See also: lcm
lcm¶
Syntax: (lcm n1 ...)
Returns the least common multiple of its arguments. With no arguments,
returns 1. The result is always non-negative. Works with fixnums,
bignums, and flonums. Computed as |a * b| / gcd(a, b).
See also: gcd
Rounding¶
floor¶
Syntax: (floor x)
Returns the largest integer not greater than x. For exact integers
(fixnums and bignums), returns the argument unchanged. For rationals,
returns an exact integer. For flonums, returns an inexact integer.
See also: ceiling, truncate, round
ceiling¶
Syntax: (ceiling x)
Returns the smallest integer not less than x. For exact integers,
returns the argument unchanged. For rationals, returns an exact integer.
For flonums, returns an inexact integer.
See also: floor, truncate, round
truncate¶
Syntax: (truncate x)
Returns the integer closest to x whose absolute value is not greater
than |x| -- that is, it rounds toward zero. For exact integers,
returns the argument unchanged. For rationals, returns an exact integer.
For flonums, returns an inexact integer.
See also: floor, ceiling, round
round¶
Syntax: (round x)
Rounds x to the nearest integer. When x is exactly halfway between
two integers, Kaappi uses banker's rounding (round to even): (round 0.5)
returns 0.0 while (round 1.5) returns 2.0. For exact integers,
returns the argument unchanged. For rationals, returns an exact integer.
kaappi> (round 3.5)
;=> 4.0
kaappi> (round 4.5)
;=> 4.0
kaappi> (round 3.2)
;=> 3.0
kaappi> (round -3.7)
;=> -4.0
Note
Kaappi implements banker's rounding (round half to even) as required by R7RS. This avoids the statistical bias of always rounding 0.5 upward.
See also: floor, ceiling, truncate
Exactness¶
exact¶
Syntax: (exact z)
Converts z to its exact representation. Fixnums, bignums, and
rationals are returned as-is. Integer-valued flonums become fixnums;
other flonums are converted to exact rationals using 2^52 scaling.
Raises an error for +inf.0, -inf.0, and +nan.0 since these have
no exact representation.
See also: inexact, inexact->exact
inexact¶
Syntax: (inexact z)
Converts z to its inexact (flonum) representation. Flonums are
returned as-is. Fixnums and bignums are converted to the nearest f64.
Rationals are divided to produce a flonum.
kaappi> (inexact 42)
;=> 42.0
kaappi> (inexact 1/3)
;=> 0.3333333333333333
kaappi> (inexact 3.14)
;=> 3.14
See also: exact, exact->inexact
exact->inexact¶
Syntax: (exact->inexact z)
Alias for inexact. Converts an exact number to its inexact
representation. Provided for R5RS compatibility.
See also: inexact, inexact->exact
inexact->exact¶
Syntax: (inexact->exact z)
Alias for exact. Converts an inexact number to its exact
representation. Provided for R5RS compatibility.
See also: exact, exact->inexact
Powers and Roots¶
expt¶
Syntax: (expt z1 z2)
Returns z1 raised to the power z2. When both arguments are exact
integers and the exponent is non-negative, the result is exact (using
bignum arithmetic for large results). A negative exact exponent produces
an exact rational. Complex exponentiation uses the formula
z^w = e^(w * ln(z)).
kaappi> (expt 2 10)
;=> 1024
kaappi> (expt 2 -1)
;=> 1/2
kaappi> (expt 2.0 0.5)
;=> 1.4142135623730951
square¶
Syntax: (square z)
Returns z * z. This is more readable than (* z z) and the
implementation handles fixnum overflow by promoting to bignums. Also
works with flonums and exact rationals.
sqrt¶
Syntax: (sqrt z)
Returns the principal square root of z. For negative real numbers,
the result is a complex number: (sqrt -1) returns 0+1i. For exact
integers that are perfect squares, the result is an exact integer.
Otherwise the result is a flonum. Also handles complex arguments.
kaappi> (sqrt 4)
;=> 2
kaappi> (sqrt 2.0)
;=> 1.4142135623730951
kaappi> (sqrt -1)
;=> 0+1i
kaappi> (sqrt 9)
;=> 3
See also: exact-integer-sqrt, expt
exact-integer-sqrt¶
Syntax: (exact-integer-sqrt k)
Returns two values: the largest integer s such that s^2 <= k, and
the remainder k - s^2. The argument k must be a non-negative exact
integer. Works with both fixnums and bignums (using Newton's method for
large values).
kaappi> (exact-integer-sqrt 14)
;=> 3
;=> 5
kaappi> (exact-integer-sqrt 4)
;=> 2
;=> 0
kaappi> (exact-integer-sqrt 0)
;=> 0
;=> 0
Note
exact-integer-sqrt returns two values. Use call-with-values or
let-values to capture both the root and the remainder.
See also: sqrt
Trigonometry¶
sin¶
Syntax: (sin z)
Returns the sine of z in radians. The result is always an inexact
flonum.
cos¶
Syntax: (cos z)
Returns the cosine of z in radians. The result is always an inexact
flonum.
tan¶
Syntax: (tan z)
Returns the tangent of z in radians. The result is always an inexact
flonum.
asin¶
Syntax: (asin z)
Returns the arcsine of z in radians. The argument should be in the
range [-1, 1]. The result is always an inexact flonum.
acos¶
Syntax: (acos z)
Returns the arccosine of z in radians. The argument should be in the
range [-1, 1]. The result is always an inexact flonum.
atan¶
Syntax: (atan z) or (atan y x)
With one argument, returns the arctangent of z in radians. With two
arguments, returns the angle in radians between the positive x-axis and
the point (x, y), equivalent to C's atan2(y, x). The two-argument
form correctly handles all quadrants and the case where x is zero.
kaappi> (atan 1.0)
;=> 0.7853981633974483
kaappi> (atan 0 1)
;=> 0.0
kaappi> (atan 1 0)
;=> 1.5707963267948966
kaappi> (atan -1 -1)
;=> -2.356194490192345
Exponentials¶
exp¶
Syntax: (exp z)
Returns e raised to the power z. The result is always an inexact
flonum.
See also: log
log¶
Syntax: (log z) or (log z base)
With one argument, returns the natural logarithm (base e) of z. With
two arguments, returns the logarithm of z in the given base, computed
as (/ (log z) (log base)). The result is always an inexact flonum.
kaappi> (log 1)
;=> 0.0
kaappi> (log 2.718281828459045)
;=> 1.0
kaappi> (log 8 2)
;=> 3.0
kaappi> (log 100 10)
;=> 2.0
See also: exp
Conversion¶
number->string¶
Syntax: (number->string z) or (number->string z radix)
Converts the number z to its string representation. The optional
radix argument (default 10) specifies the base for integer output;
valid values range from 2 to 36. Works with fixnums, bignums, rationals,
flonums, and complex numbers.
kaappi> (number->string 42)
;=> "42"
kaappi> (number->string 3.14)
;=> "3.14"
kaappi> (number->string 255 16)
;=> "ff"
kaappi> (number->string 42 2)
;=> "101010"
kaappi> (number->string +inf.0)
;=> "+inf.0"
See also: string->number
string->number¶
Syntax: (string->number string) or (string->number string radix)
Parses string as a number and returns the result. Returns #f if the
string cannot be parsed. The optional radix argument (default 10)
specifies the base for integer parsing; valid values are 2, 8, 10, and
16. Recognizes special float syntax (+inf.0, -inf.0, +nan.0),
rational syntax (1/3), and complex number syntax (3+4i).
kaappi> (string->number "42")
;=> 42
kaappi> (string->number "3.14")
;=> 3.14
kaappi> (string->number "ff" 16)
;=> 255
kaappi> (string->number "101010" 2)
;=> 42
kaappi> (string->number "hello")
;=> #f
kaappi> (string->number "+inf.0")
;=> +inf.0
See also: number->string
Integer Division¶
floor-quotient¶
Syntax: (floor-quotient n1 n2)
Returns the integer quotient of n1 divided by n2, rounded toward
negative infinity. This differs from quotient/truncate-quotient when
the arguments have different signs. Works with fixnums, bignums, and
flonums.
kaappi> (floor-quotient 7 2)
;=> 3
kaappi> (floor-quotient -7 2)
;=> -4
kaappi> (floor-quotient 7 -2)
;=> -4
See also: floor-remainder, floor/, truncate-quotient
floor-remainder¶
Syntax: (floor-remainder n1 n2)
Returns the remainder from floor division. The sign of the result always
matches the sign of n2. This is equivalent to modulo for integers.
Works with fixnums, bignums, and flonums.
kaappi> (floor-remainder 7 2)
;=> 1
kaappi> (floor-remainder -7 2)
;=> 1
kaappi> (floor-remainder 7 -2)
;=> -1
See also: floor-quotient, floor/, truncate-remainder
floor/¶
Syntax: (floor/ n1 n2)
Returns two values: the floor quotient and the floor remainder of n1
divided by n2. Equivalent to calling floor-quotient and
floor-remainder together but may be more efficient.
See also: floor-quotient, floor-remainder, truncate/
truncate-quotient¶
Syntax: (truncate-quotient n1 n2)
Returns the integer quotient of n1 divided by n2, truncated toward
zero. This is the same operation as quotient. Works with fixnums,
bignums, and flonums.
kaappi> (truncate-quotient 7 2)
;=> 3
kaappi> (truncate-quotient -7 2)
;=> -3
kaappi> (truncate-quotient 7 -2)
;=> -3
See also: truncate-remainder, truncate/, floor-quotient
truncate-remainder¶
Syntax: (truncate-remainder n1 n2)
Returns the remainder from truncated division. The sign of the result
always matches the sign of n1. This is the same operation as
remainder. Works with fixnums, bignums, and flonums.
kaappi> (truncate-remainder 7 2)
;=> 1
kaappi> (truncate-remainder -7 2)
;=> -1
kaappi> (truncate-remainder 7 -2)
;=> 1
See also: truncate-quotient, truncate/, floor-remainder
truncate/¶
Syntax: (truncate/ n1 n2)
Returns two values: the truncated quotient and the truncated remainder
of n1 divided by n2. Equivalent to calling truncate-quotient and
truncate-remainder together.
See also: truncate-quotient, truncate-remainder, floor/
Rationals¶
numerator¶
Syntax: (numerator q)
Returns the numerator of the rational number q. For integers, the
numerator is the integer itself. For flonums, converts to the best
rational approximation first and returns an inexact numerator.
kaappi> (numerator 1/3)
;=> 1
kaappi> (numerator 5)
;=> 5
kaappi> (numerator -2/3)
;=> -2
kaappi> (numerator 0.5)
;=> 1.0
See also: denominator, rationalize
denominator¶
Syntax: (denominator q)
Returns the denominator of the rational number q. For integers, the
denominator is always 1. For flonums, converts to the best rational
approximation first and returns an inexact denominator.
See also: numerator, rationalize
rationalize¶
Syntax: (rationalize x y)
Returns the simplest rational number that differs from x by no more
than y. "Simplest" means the rational with the smallest denominator
within the tolerance interval [x - |y|, x + |y|]. If an integer falls
within the interval, that integer is returned (since integers have
denominator 1). When x is exact, the result is exact; when x is
inexact, the result is inexact.
See also: numerator, denominator
Complex Numbers¶
make-rectangular¶
Syntax: (make-rectangular x1 x2)
Constructs a complex number from real part x1 and imaginary part x2.
If x2 is zero, returns a real number instead. The exactness of each
part is preserved from the input arguments.
kaappi> (make-rectangular 3 4)
;=> 3+4i
kaappi> (make-rectangular 1 0)
;=> 1
kaappi> (make-rectangular 0 1)
;=> 0+1i
See also: make-polar, real-part, imag-part
make-polar¶
Syntax: (make-polar mag ang)
Constructs a complex number from magnitude mag and angle ang (in
radians). Computes real = mag * cos(ang) and imag = mag * sin(ang).
If the imaginary part is zero, returns a real number.
See also: make-rectangular, magnitude, angle
real-part¶
Syntax: (real-part z)
Returns the real part of the complex number z. For real numbers
(fixnums and flonums), returns the argument itself. For exact complex
numbers whose real part is integer-valued, returns an exact integer.
See also: imag-part, make-rectangular
imag-part¶
Syntax: (imag-part z)
Returns the imaginary part of the complex number z. For real numbers,
returns 0 (exact) for fixnums or 0.0 (inexact) for flonums. For
exact complex numbers whose imaginary part is integer-valued, returns an
exact integer.
See also: real-part, make-rectangular
magnitude¶
Syntax: (magnitude z)
Returns the magnitude (absolute value) of z. For complex numbers,
this is sqrt(real^2 + imag^2). For real numbers, this is the absolute
value. Fixnum inputs return exact fixnum results; all other inputs return
flonums.
angle¶
Syntax: (angle z)
Returns the angle (argument) of the complex number z in radians. For
complex numbers, this is atan2(imag, real). For non-negative reals,
returns 0.0. For negative reals, returns pi.
kaappi> (angle 0+1i)
;=> 1.5707963267948966
kaappi> (angle 1)
;=> 0.0
kaappi> (angle -1)
;=> 3.141592653589793
See also: magnitude, make-polar