(std maths)

Reference

Overview

Numbers beyond the operators: the Num members, integer division, gcd and powers, and System.Math over doubles.

(import (std maths))

(modulo -7 3)              ; 2
(quotient/remainder 17 5)  ; (3, 2)
(gcd 12 18)                ; 6
(expt 2L 40)               ; 1099511627776L
(exact-round 2.7)          ; 3

The prelude re-exports abs, sign, min, max, clamp and zero? from here. Everything else needs (import (std maths)).

Integer division has Racket’s names. quotient and remainder are what / and % already do at an integer type: the quotient rounds toward zero and the remainder takes the sign of the dividend. modulo takes the sign of the divisor, which is the one to use for wrapping an index round: (modulo -1 n) is n - 1. R7RS’s truncate/ family is quotient and remainder, and floor-remainder is modulo.

The integer functions work at every integer type, signed and unsigned, and wrap on overflow as the operators do. They are generic over .NET’s numeric interfaces, so nothing is boxed and no dictionary is passed.

The double functions are System.Math’s, over double: an integer argument widens at the call, as in C#. There is one logarithm per base, loge, log2, log10 and log-base, because log is the prelude’s logging effect. round rounds a half to the even neighbour.

See also: modulo, quotient/remainder, gcd, expt, integer-sqrt, exact-round, pi

Reference

Types

Functions

Values

Types

Bits

trait ↑ Types

The bit counts of an integer of any type.

%a
The integer type: int, long, byte, bigint and the others.

Answered by .NET’s generic math (System.Numerics.IBinaryInteger) for every integer type. There is nothing to implement: a type has it when .NET says it is a binary integer.

See also: popcount, trailing-zeros, leading-zeros

Functions

abs

function ↑ Functions

(: abs (-> %a %a))

The magnitude of a number.

x
The number.
returns
x without its sign.
raises System.OverflowException
For the smallest value of a signed integer type, which has no positive counterpart.
(abs -5)     ; 5
(abs -2.5)   ; 2.5

See also: sign, negate

sign

function ↑ Functions

(: sign (-> %a int))

Which side of zero a number is on.

x
The number.
returns
-1, 0 or 1.
raises System.ArithmeticException
For a NaN.

See also: abs, positive?, negative?

min

function ↑ Functions

(: min (-> %a %a %a))

The smaller of two numbers.

a
One.
b
The other.
returns
Whichever is smaller. A NaN in either gives NaN.

See also: max, clamp, least

max

function ↑ Functions

(: max (-> %a %a %a))

The larger of two numbers.

a
One.
b
The other.
returns
Whichever is larger. A NaN in either gives NaN.

See also: min, clamp, greatest

clamp

function ↑ Functions

(: clamp (-> %a %a %a %a))

A number held between two bounds.

x
The number.
lo
The least it may be.
hi
The most it may be. Not less than lo.
returns
lo when x is below it, hi when x is above it, and x otherwise.
raises System.ArgumentException
When lo is greater than hi.
(clamp 5 1 3)    ; 3
(clamp -2 1 3)   ; 1

See also: min, max

zero?

function ↑ Functions

(: zero? (-> %a bool))

Whether a number is zero.

x
The number.
returns
#t for 0, and for both zeros of a double.

See also: positive?, negative?

even?

function ↑ Functions

(: even? (-> %a bool))

Whether a number is an even integer.

x
The number. A double counts when it is whole.
returns
#t when x is an integer divisible by 2. 2.5 is neither even nor odd.

See also: odd?, modulo

odd?

function ↑ Functions

(: odd? (-> %a bool))

Whether a number is an odd integer.

x
The number. A double counts when it is whole.
returns
#t when x is an integer not divisible by 2.

See also: even?

sqr

function ↑ Functions

(: sqr (-> %a %a))
(sqr x)

A number times itself.

x
The number.
returns
x * x, which wraps at an integer type as * does.

See also: expt, integer-sqrt

positive?

function ↑ Functions

(: positive? (-> %a bool))
(positive? x)

Whether a number is greater than zero.

x
The number.
returns
#t when x is above 0. Zero is not positive, and neither is NaN.

See also: negative?, sign, zero?

negative?

function ↑ Functions

(: negative? (-> %a bool))
(negative? x)

Whether a number is less than zero.

x
The number.
returns
#t when x is below 0. -0.0 is not negative, and neither is NaN.

See also: positive?, sign

quotient

function ↑ Functions

(: quotient (-> %a %a %a))
(quotient a b)

Integer division, rounding toward zero.

a
The dividend.
b
The divisor.
returns
a divided by b with the fraction dropped: (quotient -7 2) is -3.
raises System.DivideByZeroException
When b is zero.

The same as / at an integer type, under a name that says which rounding is meant and can be passed to a function.

See also: remainder, modulo, quotient/remainder

remainder

function ↑ Functions

(: remainder (-> %a %a %a))
(remainder a b)

What integer division leaves, with the sign of the dividend.

a
The dividend.
b
The divisor.
returns
a - b * (quotient a b): (remainder -7 2) is -1.
raises System.DivideByZeroException
When b is zero.

The same as %. Use modulo for a result matching the sign of the divisor.

See also: modulo, quotient

modulo

function ↑ Functions

(: modulo (-> %a %a %a))
(modulo a b)

What integer division leaves, with the sign of the divisor.

a
The dividend.
b
The divisor.
returns
The number from 0 toward b that differs from a by a multiple of b.
raises System.DivideByZeroException
When b is zero.
(modulo -7 2)    ; 1
(modulo 7 -2)    ; -1
(modulo -1 10)   ; 9, the last index of ten

It differs from remainder only when the two signs differ, and then by one divisor. With a positive divisor it is never negative, which is what makes it the one for wrapping round: an index, an hour, a position on a ring.

See also: remainder, quotient

quotient/remainder

function ↑ Functions

(: quotient/remainder (-> %a %a (Tuple %a %a)))
(quotient/remainder a b)

Integer division’s quotient and remainder at once.

a
The dividend.
b
The divisor.
returns
(Tuple (quotient a b) (remainder a b)).
raises System.DivideByZeroException
When b is zero.
(def (q r) (quotient/remainder 17 5))   ; q is 3, r is 2

See also: quotient, remainder

gcd

function ↑ Functions

(: gcd (-> %a %a %a))
(gcd a b)

The greatest common divisor of two integers.

a
One.
b
The other.
returns
The largest integer dividing both, never negative. (gcd 0 0) is 0.
raises System.OverflowException
When a or b is the smallest value of a signed type, whose magnitude does not fit.
(gcd 12 18)    ; 6
(gcd -12 18)   ; 6

See also: lcm

lcm

function ↑ Functions

(: lcm (-> %a %a %a))
(lcm a b)

The least common multiple of two integers.

a
One.
b
The other.
returns
The smallest positive integer both divide, or 0 when either is 0.

Computed as a / (gcd a b) * b, so intermediate arithmetic does not overflow prematurely.

See also: gcd

expt

function ↑ Functions

(: expt (-> %a int %a))
(expt base n)

An integer raised to a whole power.

base
The integer.
n
The power. Not negative.
returns
base multiplied by itself n times; (expt b 0) is 1. It wraps on overflow, as * does.
raises System.ArgumentOutOfRangeException
When n is negative.
(expt 2 10)     ; 1024
(expt 10L 18)   ; 1000000000000000000L

By squaring, so it takes a number of multiplications in proportion to the number of bits in n. pow is the one over doubles, for a fractional or negative power.

See also: pow, sqr

integer-sqrt

function ↑ Functions

(: integer-sqrt (-> %a %a))
(integer-sqrt n)

The integer square root: the largest integer whose square is not more than a number.

n
The number. Not negative.
returns
The floor of the square root of n: (integer-sqrt 15) is 3.
raises System.ArgumentOutOfRangeException
When n is negative.

Exact at every size, where going through the prelude’s sqrt rounds once a long has more digits than a double holds. Newton’s method, which never overflows, even at the type’s largest value.

See also: sqr, expt

nan?

function ↑ Functions

Whether a double is NaN, not a number.

x
The double.
returns
#t for NaN, such as (/ 0.0 0.0) gives.

NaN is unequal to everything, itself included, so (= x x) cannot test for it and this is the way to.

See also: finite?, infinite?

infinite?

function ↑ Functions

Whether a double is positive or negative infinity.

x
The double.
returns
#t for either infinity.

See also: finite?, nan?

finite?

function ↑ Functions

Whether a double is an ordinary number: neither infinite nor NaN.

x
The double.
returns
#t unless x is an infinity or NaN.

See also: nan?, infinite?

cbrt

function ↑ Functions

The cube root of a double.

x
The double. A negative one has a negative root.
returns
The number whose cube is x.

The square root is the prelude’s sqrt.

See also: pow

exp

function ↑ Functions

e raised to a power.

x
The power.
returns
e to the x.

See also: loge, pow

pow

function ↑ Functions

A double raised to a power.

x
The base.
y
The power, which may be fractional or negative.
returns
x to the y. NaN for a negative x and a fractional y.

See also: expt, exp, sqr

loge

function ↑ Functions

(: loge (-> double double))

The natural logarithm.

x
The number. Positive.
returns
The power e is raised to to give x. Negative infinity for 0, NaN for a negative x.

See also: log2, log10, log-base, exp

log-base

function ↑ Functions

(: log-base (-> double double double))

The logarithm to a given base.

x
The number. Positive.
b
The base.
returns
The power b is raised to to give x.
(log-base 8.0 2.0)   ; 3.0

See also: loge, log2, log10

log2

function ↑ Functions

The logarithm to base 2.

x
The number. Positive.
returns
The power 2 is raised to to give x.

See also: loge, log10, log-base

log10

function ↑ Functions

The logarithm to base 10.

x
The number. Positive.
returns
The power 10 is raised to to give x.

See also: loge, log2, log-base

floor

function ↑ Functions

A double rounded down, as a double.

x
The double.
returns
The largest whole number not above x: (floor -2.5) is -3.0.

See also: ceiling, truncate, round, exact-floor

ceiling

function ↑ Functions

A double rounded up, as a double.

x
The double.
returns
The smallest whole number not below x: (ceiling -2.5) is -2.0.

See also: floor, exact-ceiling

truncate

function ↑ Functions

A double rounded toward zero, as a double.

x
The double.
returns
x with its fraction dropped: (truncate -2.5) is -2.0.

See also: floor, exact-truncate

round

function ↑ Functions

A double rounded to the nearest whole number, a half to the even one, as a double.

x
The double.
returns
The nearest whole number; between two, the even one: (round 2.5) is 2.0 and (round 3.5) is 4.0.

Rounding a half to even is what Math.Round does, and what R7RS and Racket do: it keeps a long sum of rounded values from drifting upward.

See also: floor, exact-round

exact-floor

function ↑ Functions

(: exact-floor (-> double int))
(exact-floor x)

A double rounded down, as an int.

x
The double.
returns
(floor x) as an int.
raises System.OverflowException
When x is NaN, an infinity, or rounds outside an int's range.

A cast from double produces arbitrary numbers for NaN or out-of-range values; exact-floor throws an OverflowException instead.

See also: floor, exact-round

exact-ceiling

function ↑ Functions

(: exact-ceiling (-> double int))
(exact-ceiling x)

A double rounded up, as an int.

x
The double.
returns
(ceiling x) as an int.
raises System.OverflowException
When x is NaN, an infinity, or rounds outside an int's range.

See also: ceiling, exact-floor

exact-truncate

function ↑ Functions

(: exact-truncate (-> double int))
(exact-truncate x)

A double rounded toward zero, as an int.

x
The double.
returns
(truncate x) as an int.
raises System.OverflowException
When x is NaN, an infinity, or rounds outside an int's range.

See also: truncate, exact-floor

exact-round

function ↑ Functions

(: exact-round (-> double int))
(exact-round x)

A double rounded to the nearest whole number, a half to the even one, as an int.

x
The double.
returns
(round x) as an int: (exact-round 2.5) is 2.
raises System.OverflowException
When x is NaN, an infinity, or rounds outside an int's range.

See also: round, exact-floor

sin

function ↑ Functions

The sine of an angle in radians.

x
The angle, in radians.
returns
Its sine, from -1 to 1.

See also: cos, tan, asin, pi

cos

function ↑ Functions

The cosine of an angle in radians.

x
The angle, in radians.
returns
Its cosine, from -1 to 1.

See also: sin, tan, acos

tan

function ↑ Functions

The tangent of an angle in radians.

x
The angle, in radians.
returns
Its tangent.

See also: sin, cos, atan

asin

function ↑ Functions

The angle whose sine is a number.

x
The sine, from -1 to 1.
returns
The angle in radians, from -pi/2 to pi/2. NaN outside -1 to 1.

See also: sin, acos

acos

function ↑ Functions

The angle whose cosine is a number.

x
The cosine, from -1 to 1.
returns
The angle in radians, from 0 to pi. NaN outside -1 to 1.

See also: cos, asin

atan

function ↑ Functions

The angle whose tangent is a number.

x
The tangent.
returns
The angle in radians, from -pi/2 to pi/2.

See also: tan, atan2

atan2

function ↑ Functions

The angle of a point from the positive x axis.

y
The point's y. First, as in C and .NET.
x
The point's x.
returns
The angle in radians, from -pi to pi, in the point's own quadrant.
(atan2 1.0 -1.0)   ; 2.356..., 3pi/4: up and to the left

See also: atan

sinh

function ↑ Functions

The hyperbolic sine.

x
The number.
returns
Its hyperbolic sine.

See also: cosh, tanh, asinh

cosh

function ↑ Functions

The hyperbolic cosine.

x
The number.
returns
Its hyperbolic cosine, never below 1.

See also: sinh, tanh, acosh

tanh

function ↑ Functions

The hyperbolic tangent.

x
The number.
returns
Its hyperbolic tangent, from -1 to 1.

See also: sinh, cosh, atanh

asinh

function ↑ Functions

The inverse hyperbolic sine.

x
The number.
returns
The number whose hyperbolic sine is x.

See also: sinh

acosh

function ↑ Functions

The inverse hyperbolic cosine.

x
The number. At least 1.
returns
The non-negative number whose hyperbolic cosine is x. NaN below 1.

See also: cosh

atanh

function ↑ Functions

The inverse hyperbolic tangent.

x
The number, between -1 and 1.
returns
The number whose hyperbolic tangent is x. NaN outside -1 to 1, and an infinity at either end.

See also: tanh

popcount

function ↑ Functions

(: popcount (-> %a %a))

How many bits of an integer are set.

x
The integer.
returns
The number of one bits, of the type of x.
(popcount 13)      ; 3, for 1101
(popcount 255uy)   ; 8
(popcount -1)      ; 32: an int is 32 bits, all set

PopCount of the type, which the JIT compiles to the CPU’s instruction where there is one. A negative number counts its two’s-complement bits.

See also: Bits

trailing-zeros

function ↑ Functions

(: trailing-zeros (-> %a %a))

How many zero bits an integer has below its lowest one bit.

x
The integer.
returns
The index of the lowest set bit, of the type of x. For 0, the width of the type.
(trailing-zeros 12)   ; 2, for 1100
(trailing-zeros 0)    ; 32: an int is 32 bits

TrailingZeroCount of the type, one instruction on x86-64 and ARM64. With (bitwise-and b (- b 1)), which clears the lowest set bit, it walks the set bits of a mask from simd-mask-bits of (std simd) in order.

See also: leading-zeros, popcount

leading-zeros

function ↑ Functions

(: leading-zeros (-> %a %a))

How many zero bits an integer has above its highest one bit.

x
The integer.
returns
The count, of the type of x. For 0, the width of the type.
(leading-zeros 1)     ; 31
(leading-zeros 1L)    ; 63
(leading-zeros -1)    ; 0

LeadingZeroCount of the type, one instruction on x86-64 and ARM64. (- 31 (leading-zeros x)) is the index of the highest set bit of a positive int: its base-2 logarithm, rounded down.

See also: trailing-zeros, popcount

Values

pi

value ↑ Values

The ratio of a circle’s circumference to its diameter, as a double.

See also: sin, cos, atan2