Extended Real Number Line

The (affine) extended real number line, where real numbers are enriched with positive and negative infinity, compactifying their order. Positive infinity is represented by IEEE number +inf.0 while negative infinity is represented by IEEE number -inf.0, so that common operations like < <= + *, etc., already work. However, a few operations are provided in a library so that max and min functions work better with infinities. Notably:

(xmin) will return +inf.0 where (min) throws an error, and similarly (xmax) will return -inf.0 where (max) throws an error.
(xmax -inf.0 (+ 1 (expt 2 54))) will return the exact integer 18014398509481985, where (max -inf.0 (+ 1 (expt 2 54))) returns the rounded 1.8014398509481984e16. More generally, xmin and xmax preserve the type of the argument they return.

To use the bindings from this module:

(import :std/misc/number)

xmin

(xmin <x1> ... <xn>) -> real

xmin returns the lower bound of the set of its extended real arguments. In particular, it returns +inf.0 (the positive infinity) if provided zero arguments, and is the identity function when given a single argument.

xmin/list

(xmin/list <l>) -> real

xmin/list returns the lower bound of the list of extended real arguments passed as its arguments. In particular, it returns +inf.0 (the positive infinity) if provided an empty list.

xmin!

(xmin! <var> <x> ...) -> void

xmin! side-effects a variable to change it to the xmin of the previous value and the provided arguments.

xmin/map

(xmin/map <f> <l> [<base>]) -> real

Given a list <l> or any thing you can iterate on, and a function <f>, xmin/map returns the lower bound of the images by <f> of the items in <l>, and of a <base> real, by default +inf.0 (the positive infinity). The function is short-circuiting and will not evaluate further values and their side-effects after the bottom value -inf.0 is reached.

xmax

(xmax <x1> ... <xn>) -> real

xmax returns the upper bound of the set of its extended real arguments. In particular, it returns -inf.0 (the negative infinity) if provided zero arguments, and is the identity function when given a single argument.

xmax/list

(xmax/list <l>) -> real

xmax/list returns the lower bound of the list of extended real arguments passed as its arguments. In particular, it returns -inf.0 (the negative infinity) if provided an empty list.

xmax!

(xmax! <var> <x> ...) -> void

xmax! side-effects a variable to change it to the xmax of the previous value and the provided arguments.

xmax/map

(xmax/map <f> <l> [<base>]) -> real

Given a list <l> or any thing you can iterate on, and a function <f>, xmax/map returns the upper bound of the images by <f> of the items in <l>, and of a <base> xreal, by default -inf.0 (the negative infinity). The function is short-circuiting and will not evaluate further values and their side-effects after the top value +inf.0 is reached.

increment!, pre-increment!, post-increment!, decrement!, pre-decrement!, post-decrement!

(increment! place) -> (void)
(increment! place increment ...) -> (void)
(pre-increment! place) -> number
(pre-increment! place increment ...) -> number
(post-increment! place) -> number
(post-increment! place increment ...) -> number
(decrement! place) -> (void)
(decrement! place decrement ...) -> (void)
(pre-decrement! place) -> number
(pre-decrement! place decrement ...) -> number
(post-decrement! place) -> number
(post-decrement! place decrement ...) -> number

These macro will modify a variable or other place containing a number to increment (respectively, decrement) its value, adding to it (respectively, subtracting from it) one (if no further argument is specified) or the provided arguments (if specified). increment! and decrement! return #!void, pre-increment! and pre-decrement! return the value after addition (respectively, subtraction), and post-increment! and post-decrement! return the value before addition (respectively, subtraction).

make-counter

(make-counter) -> counter
(make-counter n) -> counter

This function creates a new counter, a function that takes zero or more arguments, adds the sum of these arguments to the counter (or 1, not 0, if no argument was provided), and returns the original value of the counter before the addition (post-increment). You can thus reserve how many entries you are counting before the next call.

integer-part

(integer-part x) -> integer

Given a real number x, integer-part will return the integer part as an exact integer, i.e. the number with largest absolute value whose absolute value is no greater than that of x.

fractional-part

(fractional-part x) -> integer

floor-align, ceiling-align

(floor-align n alignment) -> integer
(ceiling-align n alignment) -> integer

Given an integer n, and a non-zero integer alignment, if alignment is positive, floor-align returns the largest multiple of alignment non-greater than n, and ceiling-align returns the smallest multiple of alignment non-lesser than n; if alignment is negative, the roles of floor-align and ceiling-align are swapped.

Examples:

> (floor-align 20 10)
20
> (floor-align 25 10)
20
> (floor-align 25 -10)
30
> (ceiling-align 20 10)
20
> (ceiling-align 25 10)
30
> (ceiling-align 25 -10)
20

real->sign

(real->sign x) -> -1, 0 or 1

Given a real number x, return an integer, -1 if the number is negative, 0 if it is zero, and 1 if it is positive.

Examples:

> (real->sign 2.7)
1
> (real->sign 1e-100)
1
> (real->sign -42)
-1
> (real->sign -inf.0)
-1
> (real->sign 0.0)
0
> (real->sign 0)
0

nat?

(nat? x) -> Bool

Given any object x, return true if it is an non-negative exact integer.

fxnat?

(fxnat? x) -> Bool

Given any object x, return true if it is an non-negative fixnum.

nat-below?

(nat-below? x end) -> Bool

Given any object x, return true if it is an non-negative exact integer less than end (not included).

nat-of-length?

(nat-of-length? x length-in-bits) -> Bool

Given any object x, return true if it is an non-negative exact integer that can be stored in length-in-bits bits, as witnessed by its integer-length being no greater than length-in-bits (included).

integer-of-length?

(nat-of-length? x length-in-bits) -> Bool

Given any object x, return true if it is a (negative, zero or positive) exact integer that can be stored in length-in-bits bits, as witnessed by its integer-length being strictly less than length-in-bits (not included).

for-each-integer

(for-each-integer fun from below)

Given fun a function of one argument, call fun with each successive increasing integer starting with from up to and not including below.

half

(half n)

Given an integer n, return half of n if it is even, or half of n-1 if it is odd.

least-integer?

(least-integer pred? start end) -> integer

Do a binary search in interval [start, end) to find the least integer for which pred? holds, assuming pred? is “increasing”, i.e. if true for some integer in the interval, it is true for all greater integers in the interval. If no integer in the interval satisfies pred?, return end. If all do, return start. If pred? isn't actually increasing, return some integer in the interval.

most-integer?

(most-integer pred? start end) -> integer

Do a binary search in interval (start, end] to find the most integer for which pred? holds, assuming pred? is “decreasing”, i.e. if true for some integer in the interval, it is true for all lesser integers in the interval. If no integer in the interval satisfies pred?, return start. If all do, return end. If pred? isn't actually decreasing, return some integer in the interval.

bezout

(bezout a b) -> (values integer integer integer)

Given two integers a and b, return three values x y and d, such that d is the (non-negative) gcd of a and b, and a*x+b+y=d, thus forming a Bezout relationship.

Note: the current implementation doesn't use constant-time computations and shouldn't be used for production-grade cryptography.

mult-mod a b n

(mult-mod a b n) -> integer

Given two integers a, b and a positive integer n, return the product m of a and b modulo n.