---
title: "Standard Library: Math and Numeric Functions"
output: arl::arl_html_vignette
pkgdown:
  as_is: true
vignette: >
  %\VignetteIndexEntry{Standard Library: Math and Numeric Functions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- AUTO-GENERATED from inst/arl/ source files. Do not edit manually. -->
<!-- Regenerate with: make lang-docs -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
arl::register_knitr_engine()
```

*Examples on this page may reference functions from other stdlib modules
without showing explicit `(import ...)` statements. In the REPL or your
own code, you will need to import non-prelude modules before using their
exports — see [Importing modules](lang-reference.html#importing-modules).*


## Arithmetic Helpers {#section-arithmetic-helpers}

### % {#percent}

Modulo helper using R %%.

**Signature:** `(% x y)`

**Parameters:**
- **`x`** — Dividend
- **`y`** — Divisor

**Examples:**
```{arl}
(% 10 3)   ; => 1
(% 17 5)   ; => 2
```

```{arl, include=FALSE}
(assert-equal 1 (% 10 3))
(assert-equal 2 (% 17 5))
```

---

### inc {#inc}

Increment numeric value by n (default 1).

**Signature:** `(inc x [n 1])`

**Parameters:**
- **`x`** — Number to increment
- **`n`** — Amount to add (default 1)

**Examples:**
```{arl}
(inc 5)       ; => 6
(inc 5 3)     ; => 8
```

```{arl, include=FALSE}
(assert-equal 6 (inc 5))
(assert-equal 8 (inc 5 3))
```

**See also:** [dec](#dec)

---

### dec {#dec}

Decrement numeric value by n (default 1).

**Signature:** `(dec x [n 1])`

**Parameters:**
- **`x`** — Number to decrement
- **`n`** — Amount to subtract (default 1)

**Examples:**
```{arl}
(dec 5)       ; => 4
(dec 5 3)     ; => 2
```

```{arl, include=FALSE}
(assert-equal 4 (dec 5))
(assert-equal 2 (dec 5 3))
```

**See also:** [inc](#inc)

---

### clamp {#clamp}

Clamp numeric value x to the inclusive range [lo, hi].

**Signature:** `(clamp x lo hi)`

**Parameters:**
- **`x`** — Value to clamp
- **`lo`** — Lower bound (inclusive)
- **`hi`** — Upper bound (inclusive)

**Examples:**
```{arl}
(clamp 5 0 10)   ; => 5
(clamp -3 0 10)  ; => 0
(clamp 15 0 10)  ; => 10
```

```{arl, include=FALSE}
(assert-equal 5 (clamp 5 0 10))
(assert-equal 0 (clamp -3 0 10))
(assert-equal 10 (clamp 15 0 10))
```

**See also:** [within?](#within-p)

---

### within? {#within-p}

Return #t if x is within the inclusive range [lo, hi].

**Signature:** `(within? x lo hi)`

**Parameters:**
- **`x`** — Value to test
- **`lo`** — Lower bound (inclusive)
- **`hi`** — Upper bound (inclusive)

**Examples:**
```{arl}
(within? 5 0 10)   ; => #t
(within? -3 0 10)  ; => #f
(within? 10 0 10)  ; => #t
```

```{arl, include=FALSE}
(assert-true (within? 5 0 10))
(assert-false (within? -3 0 10))
(assert-true (within? 10 0 10))
```

**See also:** [clamp](#clamp)

---

### signum {#signum}

Return sign of x: -1, 0, or 1.

**Signature:** `(signum x)`

**Parameters:**
- **`x`** — Numeric value

**Examples:**
```{arl}
(signum 42)    ; => 1
(signum -5)    ; => -1
(signum 0)     ; => 0
```

```{arl, include=FALSE}
(assert-equal 1 (signum 42))
(assert-equal -1 (signum -5))
(assert-equal 0 (signum 0))
```

---

## Power and Roots {#section-power-and-roots}

### expt {#expt}

Return base raised to power.

**Signature:** `(expt base power)`

**Parameters:**
- **`base`** — Base number
- **`power`** — Exponent

**Examples:**
```{arl}
(expt 2 10)   ; => 1024
(expt 3 3)    ; => 27
```

```{arl, include=FALSE}
(assert-equal 1024 (expt 2 10))
(assert-equal 27 (expt 3 3))
```

---

## Integer Division {#section-integer-division}

### quotient {#quotient}

Return integer quotient of x divided by y.

**Signature:** `(quotient x y)`

**Parameters:**
- **`x`** — Dividend
- **`y`** — Divisor

**Examples:**
```{arl}
(quotient 10 3)   ; => 3
(quotient -10 3)  ; => -3
```

```{arl, include=FALSE}
(assert-equal 3 (quotient 10 3))
(assert-equal -3 (quotient -10 3))
```

**See also:** [remainder](#remainder), [modulo](#modulo)

---

### remainder {#remainder}

Return remainder of x divided by y (same sign as x).

**Signature:** `(remainder x y)`

**Parameters:**
- **`x`** — Dividend
- **`y`** — Divisor

**Examples:**
```{arl}
(remainder 10 3)   ; => 1
(remainder -10 3)  ; => -1
```

```{arl, include=FALSE}
(assert-equal 1 (remainder 10 3))
(assert-equal -1 (remainder -10 3))
```

**See also:** [quotient](#quotient), [modulo](#modulo)

---

### modulo {#modulo}

Return modulo of x and y (same sign as y).

**Signature:** `(modulo x y)`

**Parameters:**
- **`x`** — Dividend
- **`y`** — Divisor

**Examples:**
```{arl}
(modulo 10 3)    ; => 1
(modulo -10 3)   ; => 2
```

```{arl, include=FALSE}
(assert-equal 1 (modulo 10 3))
(assert-equal 2 (modulo -10 3))
```

**See also:** [quotient](#quotient), [remainder](#remainder), [%](#percent)

---

## Number Theory {#section-number-theory}

### gcd {#gcd}

Return greatest common divisor of arguments.

**Signature:** `(gcd a b ...)`

**Parameters:**
- **`args`** — Two or more integers

**Examples:**
```{arl}
(gcd 12 8)      ; => 4
(gcd 12 8 6)    ; => 2
```

```{arl, include=FALSE}
(assert-equal 4 (gcd 12 8))
(assert-equal 2 (gcd 12 8 6))
```

**See also:** [lcm](#lcm)

---

### lcm {#lcm}

Return least common multiple of arguments.

**Signature:** `(lcm a b ...)`

**Parameters:**
- **`args`** — Two or more integers

**Examples:**
```{arl}
(lcm 4 6)       ; => 12
(lcm 3 4 5)     ; => 60
```

```{arl, include=FALSE}
(assert-equal 12 (lcm 4 6))
(assert-equal 60 (lcm 3 4 5))
```

**See also:** [gcd](#gcd)

---

## Complex Number Utilities {#section-complex-number-utilities}

### make-rectangular {#make-rectangular}

Construct a complex number from real and imaginary parts.

**Signature:** `(make-rectangular real imag)`

**Parameters:**
- **`real`** — Real component
- **`imag`** — Imaginary component

**Examples:**
```{arl}
(make-rectangular 3 4)  ; => 3+4i
```

```{arl, include=FALSE}
(assert-equal (complex :real 3 :imaginary 4) (make-rectangular 3 4))
```

**See also:** [make-polar](#make-polar), [real-part](#real-part), [imag-part](#imag-part)

---

### make-polar {#make-polar}

Construct a complex number from polar coordinates (magnitude and angle).

**Signature:** `(make-polar magnitude angle)`

**Parameters:**
- **`magnitude`** — Distance from origin
- **`angle`** — Angle in radians

**Examples:**
```{arl}
(make-polar 5 0)      ; => 5+0i
```

```{arl, include=FALSE}
(assert-equal (complex :modulus 5 :argument 0) (make-polar 5 0))
```

**See also:** [make-rectangular](#make-rectangular), [magnitude](#magnitude), [angle](#angle)

---

### real-part {#real-part}

Extract the real part of a complex number.

**Signature:** `(real-part z)`

**Parameters:**
- **`z`** — Complex number

**Examples:**
```{arl}
(real-part (make-rectangular 3 4))  ; => 3.0
```

```{arl, include=FALSE}
(assert-equal 3.0 (real-part (make-rectangular 3 4)))
```

**See also:** [imag-part](#imag-part), [make-rectangular](#make-rectangular)

---

### imag-part {#imag-part}

Extract the imaginary part of a complex number.

**Signature:** `(imag-part z)`

**Parameters:**
- **`z`** — Complex number

**Examples:**
```{arl}
(imag-part (make-rectangular 3 4))  ; => 4.0
```

```{arl, include=FALSE}
(assert-equal 4.0 (imag-part (make-rectangular 3 4)))
```

**See also:** [real-part](#real-part), [make-rectangular](#make-rectangular)

---

### magnitude {#magnitude}

Compute the magnitude (modulus) of a complex number.

**Signature:** `(magnitude z)`

**Parameters:**
- **`z`** — Complex number

**Examples:**
```{arl}
(magnitude (make-rectangular 3 4))  ; => 5.0
```

```{arl, include=FALSE}
(assert-equal 5.0 (magnitude (make-rectangular 3 4)))
```

**See also:** [angle](#angle), [make-polar](#make-polar)

---

### angle {#angle}

Compute the angle (argument) of a complex number.

**Signature:** `(angle z)`

**Parameters:**
- **`z`** — Complex number

**Examples:**
```{arl}
(angle (make-rectangular 1 1))  ; => 0.7853981633974483 (pi/4)
```

```{arl, include=FALSE}
(assert-true (< (abs (- (angle (make-rectangular 1 1)) (/ pi 4))) 1e-10))
```

**See also:** [magnitude](#magnitude), [make-polar](#make-polar)

---