 Documentation

# Calculation functions

Calculations and processing of numeric values.

These functions 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`

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

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

calc.perm() -> int
``````#calc.perm(10, 5)
`````` #### `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.

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)
#assert(calc.trunc(15.9) == 15)
`````` #### `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.

calc.rem() -> intfloat
``````#calc.rem(20, 6) \
#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 of two numbers.

calc.quo() -> int
``````#calc.quo(14, 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.