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`, `inf`, and `nan`.

## Functions

### `abs`

Calculates the absolute value of a numeric value.

calc.abs(
) -> any
``````#calc.abs(-5) \
#calc.abs(5pt - 2cm) \
#calc.abs(2fr)
``````

#### `value`int or float or length or angle or ratio or fractionRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The value whose absolute value to calculate.

### `pow`

Raises a value to some exponent.

calc.pow() -> intfloat
``````#calc.pow(2, 3)
``````

#### `base`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The base of the power.

#### `exponent`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The exponent of the power.

### `exp`

Raises a value to some exponent of e.

calc.exp(
) -> float
``````#calc.exp(1)
``````

#### `exponent`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The exponent of the power.

### `sqrt`

Calculates the square root of a number.

calc.sqrt(
) -> float
``````#calc.sqrt(16) \
#calc.sqrt(2.5)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

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

### `root`

Calculates the real nth root of a number.

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

calc.root() -> float
``````#calc.root(16.0, 4) \
#calc.root(27.0, 3)
``````

#### `radicand`floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The expression to take the root of

#### `index`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

Which root of the radicand to take

### `sin`

Calculates the sine of an angle.

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

calc.sin(
) -> float
``````#assert(calc.sin(90deg) == calc.sin(-270deg))
#calc.sin(1.5) \
#calc.sin(90deg)
``````

#### `angle`int or float or angleRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The angle whose sine to calculate.

### `cos`

Calculates the cosine of an angle.

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

calc.cos(
) -> float
``````#calc.cos(90deg) \
#calc.cos(1.5) \
#calc.cos(90deg)
``````

#### `angle`int or float or angleRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The angle whose cosine to calculate.

### `tan`

Calculates the tangent of an angle.

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

calc.tan(
) -> float
``````#calc.tan(1.5) \
#calc.tan(90deg)
``````

#### `angle`int or float or angleRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The angle whose tangent to calculate.

### `asin`

Calculates the arcsine of a number.

calc.asin(
) -> angle
``````#calc.asin(0) \
#calc.asin(1)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

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

### `acos`

Calculates the arccosine of a number.

calc.acos(
) -> angle
``````#calc.acos(0) \
#calc.acos(1)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

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

### `atan`

Calculates the arctangent of a number.

calc.atan(
) -> angle
``````#calc.atan(0) \
#calc.atan(1)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number whose arctangent to calculate.

### `atan2`

Calculates the four-quadrant arctangent of a coordinate.

The arguments are `(x, y)`, not `(y, x)`.

calc.atan2() -> angle
``````#calc.atan2(1, 1) \
#calc.atan2(-2, -3)
``````

#### `x`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The X coordinate.

#### `y`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The Y coordinate.

### `sinh`

Calculates the hyperbolic sine of a hyperbolic angle.

calc.sinh() -> float
``````#calc.sinh(0) \
#calc.sinh(1.5)
``````

#### `value`floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The hyperbolic angle whose hyperbolic sine to calculate.

### `cosh`

Calculates the hyperbolic cosine of a hyperbolic angle.

calc.cosh() -> float
``````#calc.cosh(0) \
#calc.cosh(1.5)
``````

#### `value`floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The hyperbolic angle whose hyperbolic cosine to calculate.

### `tanh`

Calculates the hyperbolic tangent of an hyperbolic angle.

calc.tanh() -> float
``````#calc.tanh(0) \
#calc.tanh(1.5)
``````

#### `value`floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The hyperbolic angle whose hyperbolic tangent to calculate.

### `log`

Calculates the logarithm of a number.

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

calc.log() -> float
``````#calc.log(100)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

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

#### `base`float

The base of the logarithm. May not be zero.

Default: `10.0`

### `ln`

Calculates the natural logarithm of a number.

calc.ln(
) -> float
``````#calc.ln(calc.e)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

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

### `fact`

Calculates the factorial of a number.

calc.fact() -> int
``````#calc.fact(5)
``````

#### `number`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

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

### `perm`

Calculates a permutation.

Returns the `k`-permutation of `n`, or the number of ways to choose `k` items from a set of `n` with regard to order.

calc.perm() -> int
``````\$ "perm"(n, k) &= n!/((n - k)!) \
"perm"(5, 3) &= #calc.perm(5, 3) \$
``````

#### `base`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The base number. Must be non-negative.

#### `numbers`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number of permutations. Must be non-negative.

### `binom`

Calculates a binomial coefficient.

Returns the `k`-combination of `n`, or the number of ways to choose `k` items from a set of `n` without regard to order.

calc.binom() -> int
``````#calc.binom(10, 5)
``````

#### `n`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The upper coefficient. Must be non-negative.

#### `k`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The lower coefficient. Must be non-negative.

### `gcd`

Calculates the greatest common divisor of two integers.

calc.gcd() -> int
``````#calc.gcd(7, 42)
``````

#### `a`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The first integer.

#### `b`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The second integer.

### `lcm`

Calculates the least common multiple of two integers.

calc.lcm() -> int
``````#calc.lcm(96, 13)
``````

#### `a`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The first integer.

#### `b`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The second integer.

### `floor`

Rounds a number down to the nearest integer.

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

calc.floor(
) -> int
``````#assert(calc.floor(3.14) == 3)
#assert(calc.floor(3) == 3)
#calc.floor(500.1)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to round down.

### `ceil`

Rounds a number up to the nearest integer.

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

calc.ceil(
) -> int
``````#assert(calc.ceil(3.14) == 4)
#assert(calc.ceil(3) == 3)
#calc.ceil(500.1)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to round up.

### `trunc`

Returns the integer part of a number.

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

calc.trunc(
) -> int
``````#assert(calc.trunc(3) == 3)
#assert(calc.trunc(-3.7) == -3)
#calc.trunc(15.9)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to truncate.

### `fract`

Returns the fractional part of a number.

If the number is an integer, returns `0`.

calc.fract(
) -> intfloat
``````#assert(calc.fract(3) == 0)
#calc.fract(-3.1)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to truncate.

### `round`

Rounds a number to the nearest integer.

Optionally, a number of decimal places can be specified.

calc.round() -> intfloat
``````#assert(calc.round(3.14) == 3)
#assert(calc.round(3.5) == 4)
#calc.round(3.1415, digits: 2)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to round.

#### `digits`int

The number of decimal places.

Default: `0`

### `clamp`

Clamps a number between a minimum and maximum value.

calc.clamp() -> intfloat
``````#assert(calc.clamp(5, 0, 10) == 5)
#assert(calc.clamp(5, 6, 10) == 6)
#calc.clamp(5, 0, 4)
``````

#### `value`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to clamp.

#### `min`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The inclusive minimum value.

#### `max`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The inclusive maximum value.

### `min`

Determines the minimum of a sequence of values.

calc.min(
..any
) -> any
``````#calc.min(1, -3, -5, 20, 3, 6) \
#calc.min("typst", "in", "beta")
``````

#### `values`anyRequiredPositionalQuestion markPositional parameters are specified in order, without names.VariadicQuestion markVariadic parameters can be specified multiple times.

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

### `max`

Determines the maximum of a sequence of values.

calc.max(
..any
) -> any
``````#calc.max(1, -3, -5, 20, 3, 6) \
#calc.max("typst", "in", "beta")
``````

#### `values`anyRequiredPositionalQuestion markPositional parameters are specified in order, without names.VariadicQuestion markVariadic parameters can be specified multiple times.

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

### `even`

Determines whether an integer is even.

calc.even() -> bool
``````#calc.even(4) \
#calc.even(5) \
#range(10).filter(calc.even)
``````

#### `value`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to check for evenness.

### `odd`

Determines whether an integer is odd.

calc.odd() -> bool
``````#calc.odd(4) \
#calc.odd(5) \
#range(10).filter(calc.odd)
``````

#### `value`intRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The number to check for oddness.

### `rem`

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

calc.rem() -> intfloat
``````#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 floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The dividend of the remainder.

#### `divisor`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The divisor of the remainder.

### `div-euclid`

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.

calc.div-euclid() -> intfloat
``````#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)
``````

#### `dividend`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The dividend of the division.

#### `divisor`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The divisor of the division.

### `rem-euclid`

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.

calc.rem-euclid() -> intfloat
``````#calc.rem-euclid(7, 3) \
#calc.rem-euclid(7, -3) \
#calc.rem-euclid(-7, 3) \
#calc.rem-euclid(-7, -3) \
#calc.rem(1.75, 0.5)
``````

#### `dividend`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The dividend of the remainder.

#### `divisor`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The divisor of the remainder.

### `quo`

Calculates the quotient (floored division) of two numbers.

calc.quo() -> int
``````\$ "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 floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The dividend of the quotient.

#### `divisor`int or floatRequiredPositionalQuestion markPositional parameters are specified in order, without names.

The divisor of the quotient.