Documentation

Calculation

Module for calculations and processing of numeric values.

These definitions are part of the calc module and not imported by default. In addition to the functions listed below, the calc module also defines the constants pi, tau, e, and inf.

Functions

absGo to source

Calculates the absolute value of a numeric value.

ExpandView example
#calc.abs(-5) \
#calc.abs(5pt - 2cm) \
#calc.abs(2fr) \
#calc.abs(decimal("-342.440"))

value
int or float or length or angle or ratio or fraction or decimal
RequiredPositional
Question mark

The value whose absolute value to calculate.

powGo to source

Raises a value to some exponent.

ExpandView example
#calc.pow(2, 3) \
#calc.pow(decimal("2.5"), 2)

base
int or float or decimal
RequiredPositional
Question mark

The base of the power.

If this is a decimal, the exponent can only be an integer.

exponent
int or float
RequiredPositional
Question mark

The exponent of the power.

expGo to source

Raises a value to some exponent of 𝑒.

ExpandView example
#calc.exp(1)
calc.exp(intfloat) → float

exponent
int or float
RequiredPositional
Question mark

The exponent of the power.

sqrtGo to source

Calculates the square root of a number.

ExpandView example
#calc.sqrt(16) \
#calc.sqrt(2.5)
calc.sqrt(intfloat) → float

value
int or float
RequiredPositional
Question mark

The number whose square root to calculate. Must be non-negative.

rootGo to source

Calculates the real 𝑛th root of a number.

If the number is negative, then 𝑛 must be odd.

ExpandView example
#calc.root(16.0, 4) \
#calc.root(27.0, 3)
calc.root() → float

radicand
float
RequiredPositional
Question mark

The expression to take the root of.

index
int
RequiredPositional
Question mark

The value of 𝑛.

sinGo to source

Calculates the sine of an angle.

When called with an integer or a float, they will be interpreted as radians.

ExpandView example
#calc.sin(1.5) \
#calc.sin(90deg)
calc.sin(intfloatangle) → float

angle
int or float or angle
RequiredPositional
Question mark

The angle whose sine to calculate.

cosGo to source

Calculates the cosine of an angle.

When called with an integer or a float, they will be interpreted as radians.

ExpandView example
#calc.cos(1.5) \
#calc.cos(90deg)
calc.cos(intfloatangle) → float

angle
int or float or angle
RequiredPositional
Question mark

The angle whose cosine to calculate.

tanGo to source

Calculates the tangent of an angle.

When called with an integer or a float, they will be interpreted as radians.

ExpandView example
#calc.tan(1.5) \
#calc.tan(90deg)
calc.tan(intfloatangle) → float

angle
int or float or angle
RequiredPositional
Question mark

The angle whose tangent to calculate.

asinGo to source

Calculates the arcsine of a number.

ExpandView example
#calc.asin(0) \
#calc.asin(1)
calc.asin(intfloat) → angle

value
int or float
RequiredPositional
Question mark

The number whose arcsine to calculate. Must be between 1 and 1.

acosGo to source

Calculates the arccosine of a number.

ExpandView example
#calc.acos(0) \
#calc.acos(1)
calc.acos(intfloat) → angle

value
int or float
RequiredPositional
Question mark

The number whose arccosine to calculate. Must be between 1 and 1.

atanGo to source

Calculates the arctangent of a number.

ExpandView example
#calc.atan(0) \
#calc.atan(1)
calc.atan(intfloat) → angle

value
int or float
RequiredPositional
Question mark

The number whose arctangent to calculate.

atan2Go to source

Calculates the four-quadrant arctangent of a coordinate.

The four-quadrant arctangent of (𝑥,𝑦) is defined as the argument of the complex number 𝑥+𝑖𝑦.

Returns an angle between -180deg and 180deg.

Note that this function accepts (𝑥,𝑦), not (𝑦,𝑥).

ExpandView example
#calc.atan2(1, 1) \
#calc.atan2(-2, -3)
calc.atan2() → angle

x
int or float
RequiredPositional
Question mark

The 𝑥 coordinate.

y
int or float
RequiredPositional
Question mark

The 𝑦 coordinate.

sinhGo to source

Calculates the hyperbolic sine of a hyperbolic angle.

The hyperbolic sine of 𝑥 is defined as follows:

𝑒𝑥𝑒𝑥2
ExpandView example
#calc.sinh(0) \
#calc.sinh(1.5)
calc.sinh(float) → float

value
float
RequiredPositional
Question mark

The hyperbolic angle whose hyperbolic sine to calculate.

coshGo to source

Calculates the hyperbolic cosine of a hyperbolic angle.

The hyperbolic cosine of 𝑥 is defined as follows:

𝑒𝑥+𝑒𝑥2
ExpandView example
#calc.cosh(0) \
#calc.cosh(1.5)
calc.cosh(float) → float

value
float
RequiredPositional
Question mark

The hyperbolic angle whose hyperbolic cosine to calculate.

tanhGo to source

Calculates the hyperbolic tangent of a hyperbolic angle.

The hyperbolic tangent of 𝑥 is defined as follows:

𝑒𝑥𝑒𝑥𝑒𝑥+𝑒𝑥
ExpandView example
#calc.tanh(0) \
#calc.tanh(1.5)
calc.tanh(float) → float

value
float
RequiredPositional
Question mark

The hyperbolic angle whose hyperbolic tangent to calculate.

asinhGo to source

Calculates the inverse hyperbolic sine of a number.

The inverse hyperbolic sine of 𝑥 is defined as follows:

ln(𝑥+𝑥2+1)
ExpandView example
#calc.asinh(0) \
#calc.asinh(1)
calc.asinh(float) → float

value
float
RequiredPositional
Question mark

The number whose inverse hyperbolic sine to calculate.

acoshGo to source

Calculates the inverse hyperbolic cosine of a number.

The inverse hyperbolic cosine of 𝑥 is defined as follows:

ln(𝑥+𝑥21)
ExpandView example
#calc.acosh(1) \
#calc.acosh(2.5)
calc.acosh(float) → float

value
float
RequiredPositional
Question mark

The number whose inverse hyperbolic cosine to calculate. Must be greater than or equal to 1.

atanhGo to source

Calculates the inverse hyperbolic tangent of a number.

The inverse hyperbolic tangent of 𝑥 is defined as follows:

12ln(1+𝑥1𝑥)
ExpandView example
#calc.atanh(0) \
#calc.atanh(0.5)
calc.atanh(float) → float

value
float
RequiredPositional
Question mark

The number whose inverse hyperbolic tangent to calculate. Must be between 1 and 1 (exclusive).

logGo to source

Calculates the logarithm of a number.

If the base is not specified, the logarithm is calculated in base ten.

ExpandView example
#calc.log(100)
calc.log() → float

value
int or float
RequiredPositional
Question mark

The number whose logarithm to calculate. Must be strictly positive.

baseDefault: 10.0

The base of the logarithm. May not be zero.

lnGo to source

Calculates the natural logarithm of a number.

ExpandView example
#calc.ln(calc.e)
calc.ln(intfloat) → float

value
int or float
RequiredPositional
Question mark

The number whose logarithm to calculate. Must be strictly positive.

erfGo to source

Applies the error function to a number.

The value of the error function at 𝑥 is defined as follows:

2𝜋0𝑥𝑒𝑡2d𝑡
ExpandView example
#calc.erf(0.2)
calc.erf(float) → float

value
float
RequiredPositional
Question mark

The number at which to calculate the error function.

factGo to source

Calculates the factorial of a number.

ExpandView example
#calc.fact(5)
calc.fact(int) → int

number
int
RequiredPositional
Question mark

The number whose factorial to calculate. Must be non-negative.

permGo to source

Calculates a permutation.

Returns the 𝑘-permutation of 𝑛, or the number of ways to choose 𝑘 items from a set of 𝑛 with regard to order, defined as follows:

{0if𝑘>𝑛𝑛!(𝑛𝑘)!if𝑘𝑛
ExpandView example
#calc.perm(5, 3)
calc.perm() → int

base
int
RequiredPositional
Question mark

The value of 𝑛: The number of items to choose from. Must be non-negative.

numbers
int
RequiredPositional
Question mark

The value of 𝑘: The number of items to choose. Must be non-negative.

binomGo to source

Calculates a binomial coefficient.

Returns the 𝑘-combination of 𝑛, or the number of ways to choose 𝑘 items from a set of 𝑛 without regard to order, defined as follows:

{𝑛!𝑘!(𝑛𝑘)!if0𝑘𝑛0otherwise
ExpandView example
#calc.binom(10, 5)
calc.binom() → int

n
int
RequiredPositional
Question mark

The value of 𝑛: The numbers of items to choose from. Must be non-negative.

k
int
RequiredPositional
Question mark

The value of 𝑘: The number of items to choose. Must be non-negative.

gcdGo to source

Calculates the greatest common divisor of two integers.

This will error if the result of integer division would be larger than the maximum 64-bit signed integer.

ExpandView example
#calc.gcd(7, 42)
calc.gcd() → int

a
int
RequiredPositional
Question mark

The first integer.

b
int
RequiredPositional
Question mark

The second integer.

lcmGo to source

Calculates the least common multiple of two integers.

ExpandView example
#calc.lcm(96, 13)
calc.lcm() → int

a
int
RequiredPositional
Question mark

The first integer.

b
int
RequiredPositional
Question mark

The second integer.

floorGo to source

Rounds a number down to the nearest integer.

If the number is already an integer, it is returned unchanged.

Note that this function will always return an integer, and will error if the resulting float or decimal is larger than the maximum 64-bit signed integer or smaller than the minimum for that type.

ExpandView example
#calc.floor(500.1)
#assert(calc.floor(3) == 3)
#assert(calc.floor(3.14) == 3)
#assert(calc.floor(decimal("-3.14")) == -4)
calc.floor(intfloatdecimal) → int

value
int or float or decimal
RequiredPositional
Question mark

The number to round down.

ceilGo to source

Rounds a number up to the nearest integer.

If the number is already an integer, it is returned unchanged.

Note that this function will always return an integer, and will error if the resulting float or decimal is larger than the maximum 64-bit signed integer or smaller than the minimum for that type.

ExpandView example
#calc.ceil(500.1)
#assert(calc.ceil(3) == 3)
#assert(calc.ceil(3.14) == 4)
#assert(calc.ceil(decimal("-3.14")) == -3)
calc.ceil(intfloatdecimal) → int

value
int or float or decimal
RequiredPositional
Question mark

The number to round up.

truncGo to source

Returns the integer part of a number.

If the number is already an integer, it is returned unchanged.

Note that this function will always return an integer, and will error if the resulting float or decimal is larger than the maximum 64-bit signed integer or smaller than the minimum for that type.

ExpandView example
#calc.trunc(15.9)
#assert(calc.trunc(3) == 3)
#assert(calc.trunc(-3.7) == -3)
#assert(calc.trunc(decimal("8493.12949582390")) == 8493)
calc.trunc(intfloatdecimal) → int

value
int or float or decimal
RequiredPositional
Question mark

The number to truncate.

fractGo to source

Returns the fractional part of a number.

If the number is an integer, returns 0.

ExpandView example
#calc.fract(-3.1)
#assert(calc.fract(3) == 0)
#assert(calc.fract(decimal("234.23949211")) == decimal("0.23949211"))

value
int or float or decimal
RequiredPositional
Question mark

The number to truncate.

roundGo to source

Rounds a number to the nearest integer.

Half-integers are rounded away from zero.

Optionally, a number of decimal places can be specified. If negative, its absolute value will indicate the amount of significant integer digits to remove before the decimal point.

Note that this function will return the same type as the operand. That is, applying round to a float will return a float, and to a decimal, another decimal. You may explicitly convert the output of this function to an integer with int, but note that such a conversion will error if the float or decimal is larger than the maximum 64-bit signed integer or smaller than the minimum integer.

In addition, this function can error if there is an attempt to round beyond the maximum or minimum integer or decimal. If the number is a float, such an attempt will cause float.inf or -float.inf to be returned for maximum and minimum respectively.

ExpandView example
#calc.round(3.1415, digits: 2)
#assert(calc.round(3) == 3)
#assert(calc.round(3.14) == 3)
#assert(calc.round(3.5) == 4.0)
#assert(calc.round(3333.45, digits: -2) == 3300.0)
#assert(calc.round(-48953.45, digits: -3) == -49000.0)
#assert(calc.round(3333, digits: -2) == 3300)
#assert(calc.round(-48953, digits: -3) == -49000)
#assert(calc.round(decimal("-6.5")) == decimal("-7"))
#assert(calc.round(decimal("7.123456789"), digits: 6) == decimal("7.123457"))
#assert(calc.round(decimal("3333.45"), digits: -2) == decimal("3300"))
#assert(calc.round(decimal("-48953.45"), digits: -3) == decimal("-49000"))

value
int or float or decimal
RequiredPositional
Question mark

The number to round.

digitsDefault: 0

If positive, the number of decimal places.

If negative, the number of significant integer digits that should be removed before the decimal point.

clampGo to source

Clamps a number between a minimum and maximum value.

ExpandView example
#calc.clamp(5, 0, 4)
#assert(calc.clamp(5, 0, 10) == 5)
#assert(calc.clamp(5, 6, 10) == 6)
#assert(calc.clamp(decimal("5.45"), 2, decimal("45.9")) == decimal("5.45"))
#assert(calc.clamp(decimal("5.45"), decimal("6.75"), 12) == decimal("6.75"))

value
int or float or decimal
RequiredPositional
Question mark

The number to clamp.

min
int or float or decimal
RequiredPositional
Question mark

The inclusive minimum value.

max
int or float or decimal
RequiredPositional
Question mark

The inclusive maximum value.

minGo to source

Determines the minimum of a sequence of values.

ExpandView example
#calc.min(1, -3, -5, 20, 3, 6) \
#calc.min("typst", "is", "cool")
calc.min(..any) → any

values
any
RequiredPositional
Question mark
Variadic
Question mark

The sequence of values from which to extract the minimum. Must not be empty.

maxGo to source

Determines the maximum of a sequence of values.

ExpandView example
#calc.max(1, -3, -5, 20, 3, 6) \
#calc.max("typst", "is", "cool")
calc.max(..any) → any

values
any
RequiredPositional
Question mark
Variadic
Question mark

The sequence of values from which to extract the maximum. Must not be empty.

evenGo to source

Determines whether an integer is even.

ExpandView example
#calc.even(4) \
#calc.even(5) \
#range(10).filter(calc.even)
calc.even(int) → bool

value
int
RequiredPositional
Question mark

The number to check for evenness.

oddGo to source

Determines whether an integer is odd.

ExpandView example
#calc.odd(4) \
#calc.odd(5) \
#range(10).filter(calc.odd)
calc.odd(int) → bool

value
int
RequiredPositional
Question mark

The number to check for oddness.

remGo to source

Calculates the remainder of two numbers.

The value calc.rem(x, y) always has the same sign as x, and is smaller in magnitude than y.

This can error if given a decimal input and the dividend is too small in magnitude compared to the divisor.

ExpandView example
#calc.rem(7, 3) \
#calc.rem(7, -3) \
#calc.rem(-7, 3) \
#calc.rem(-7, -3) \
#calc.rem(1.75, 0.5)

dividend
int or float or decimal
RequiredPositional
Question mark

The dividend of the remainder.

divisor
int or float or decimal
RequiredPositional
Question mark

The divisor of the remainder.

div-euclidGo to source

Performs euclidean division of two numbers.

The result of this computation is that of a division rounded to the integer n such that the dividend is greater than or equal to n times the divisor.

This can error if the resulting number is larger than the maximum value or smaller than the minimum value for its type.

ExpandView example
#calc.div-euclid(7, 3) \
#calc.div-euclid(7, -3) \
#calc.div-euclid(-7, 3) \
#calc.div-euclid(-7, -3) \
#calc.div-euclid(1.75, 0.5) \
#calc.div-euclid(decimal("1.75"), decimal("0.5"))

dividend
int or float or decimal
RequiredPositional
Question mark

The dividend of the division.

divisor
int or float or decimal
RequiredPositional
Question mark

The divisor of the division.

rem-euclidGo to source

This calculates the least nonnegative remainder of a division.

Warning: Due to a floating point round-off error, the remainder may equal the absolute value of the divisor if the dividend is much smaller in magnitude than the divisor and the dividend is negative. This only applies for floating point inputs.

In addition, this can error if given a decimal input and the dividend is too small in magnitude compared to the divisor.

ExpandView example
#calc.rem-euclid(7, 3) \
#calc.rem-euclid(7, -3) \
#calc.rem-euclid(-7, 3) \
#calc.rem-euclid(-7, -3) \
#calc.rem-euclid(1.75, 0.5) \
#calc.rem-euclid(decimal("1.75"), decimal("0.5"))

dividend
int or float or decimal
RequiredPositional
Question mark

The dividend of the remainder.

divisor
int or float or decimal
RequiredPositional
Question mark

The divisor of the remainder.

quoGo to source

Calculates the quotient (floored division) of two numbers.

Note that this function will always return an integer, and will error if the resulting number is larger than the maximum 64-bit signed integer or smaller than the minimum for that type.

ExpandView example
$ "quo"(a, b) &= floor(a/b) \
  "quo"(14, 5) &= #calc.quo(14, 5) \
  "quo"(3.46, 0.5) &= #calc.quo(3.46, 0.5) $

dividend
int or float or decimal
RequiredPositional
Question mark

The dividend of the quotient.

divisor
int or float or decimal
RequiredPositional
Question mark

The divisor of the quotient.

normGo to source

Calculates the 𝑝-norm of a sequence of values.

The 𝑝-norm of 𝑥1,,𝑥𝑛 is defined as follows:

{(𝑖=1𝑛|𝑥𝑖|𝑝)1/𝑝if0<𝑝<+max𝑖=1𝑛|𝑥𝑖|if𝑝=+
ExpandView example
#calc.norm(1, 2, -3, 0.5) \
#calc.norm(p: 3, 1, 2)
calc.norm() → float

pDefault: 2.0

The value of 𝑝. Must be greater than zero.

The default value of 2.0 corresponds to the Euclidean norm:

𝑖=1𝑛𝑥𝑖2

values
float
RequiredPositional
Question mark
Variadic
Question mark

The sequence of values to calculate the 𝑝-norm of. Returns 0.0 if empty.