Document string functions

book/build.py

@@ -78,7 +78,8 @@ def list_of_functions(file_name, document):
             links = []
             for section in sections:
                 if title := section.get("title"):
-                    links.append(f"[{title}](#{title.lower().replace(' ', '-')})")
+                    link = title.lower().replace(" ", "-").replace(",", "")
+                    links.append(f"[{title}](#{link})")
             print(f"{' · '.join(links)}\n", file=f, flush=True)
 
         for section in sections:
@@ -136,7 +137,7 @@ def list_of_functions(file_name, document):
             },
             {
                 "title": "Number theory",
-                "modules": ["core::number_theory"],
+                "modules": ["math::number_theory"],
             },
             {
                 "title": "Numerical methods",

book/src/conversion-functions.md

@@ -27,8 +27,8 @@ now() -> tz("Asia/Kathmandu")
 # Convert a number to a custom base
 42 -> base(16)
 
-# Convert an ASCII code point number to a character
-78 -> chr
+# Convert a code point number to a character
+0x2764 -> chr
 
 # Convert a string to upper/lower case
 "numbat is awesome" -> uppercase

book/src/list-functions-math.md

@@ -1,6 +1,6 @@
 # Mathematical functions
 
-[Basics](#basics) · [Transcendental functions](#transcendental-functions) · [Trigonometry](#trigonometry) · [Statistics](#statistics) · [Random sampling, distributions](#random-sampling,-distributions) · [Number theory](#number-theory) · [Numerical methods](#numerical-methods) · [Geometry](#geometry) · [Algebra](#algebra) · [Trigonometry (extra)](#trigonometry-(extra))
+[Basics](#basics) · [Transcendental functions](#transcendental-functions) · [Trigonometry](#trigonometry) · [Statistics](#statistics) · [Random sampling, distributions](#random-sampling-distributions) · [Number theory](#number-theory) · [Numerical methods](#numerical-methods) · [Geometry](#geometry) · [Algebra](#algebra) · [Trigonometry (extra)](#trigonometry-(extra))
 
 ## Basics
 
@@ -14,23 +14,23 @@ fn id<A>(x: A) -> A
 ```
 
 ### `abs` (Absolute value)
-Return the absolute value of the input, \\( |x| \\). This works for quantities, too: `abs(-5 m) = 5 m`.
+Return the absolute value \\( |x| \\) of the input. This works for quantities, too: `abs(-5 m) = 5 m`.
 More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.abs).
 
 ```nbt
 fn abs<T: Dim>(x: T) -> T
 ```
 
 ### `sqrt` (Square root)
-Return the square root of the input, \\( \sqrt{x} \\): `sqrt(121 m^2) = 11 m`.
+Return the square root \\( \sqrt{x} \\) of the input: `sqrt(121 m^2) = 11 m`.
 More information [here](https://en.wikipedia.org/wiki/Square_root).
 
 ```nbt
 fn sqrt<D: Dim>(x: D^2) -> D
 ```
 
 ### `cbrt` (Cube root)
-Return the cube root of the input, \\( \sqrt[3]{x} \\): `cbrt(8 m^3) = 2 m`.
+Return the cube root \\( \sqrt[3]{x} \\) of the input: `cbrt(8 m^3) = 2 m`.
 More information [here](https://en.wikipedia.org/wiki/Cube_root).
 
 ```nbt
@@ -45,31 +45,31 @@ fn sqr<D: Dim>(x: D) -> D^2
 ```
 
 ### `round` (Rounding)
-Round to the nearest integer. If the value is half-way between two integers, round away from 0.
+Round to the nearest integer. If the value is half-way between two integers, round away from \\( 0 \\).
 More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.round).
 
 ```nbt
 fn round<T: Dim>(x: T) -> T
 ```
 
 ### `floor` (Floor function)
-Returns the largest integer less than or equal to `x`.
+Returns the largest integer less than or equal to \\( x \\).
 More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.floor).
 
 ```nbt
 fn floor<T: Dim>(x: T) -> T
 ```
 
 ### `ceil` (Ceil function)
-Returns the smallest integer greater than or equal to `x`.
+Returns the smallest integer greater than or equal to \\( x \\).
 More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.ceil).
 
 ```nbt
 fn ceil<T: Dim>(x: T) -> T
 ```
 
 ### `mod` (Modulo)
-Calculates the least nonnegative remainder of `a (mod b)`.
+Calculates the least nonnegative remainder of \\( a (\mod b) \\).
 More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.rem_euclid).
 
 ```nbt
@@ -293,15 +293,15 @@ fn rand_uniform<T: Dim>(a: T, b: T) -> T
 ```
 
 ### `rand_int` (Discrete uniform distribution sampling)
-Uniformly samples the integers in the interval \\( [a, b] \\).
+Uniformly samples integers from the interval \\( [a, b] \\).
 More information [here](https://en.wikipedia.org/wiki/Discrete_uniform_distribution).
 
 ```nbt
 fn rand_int(a: Scalar, b: Scalar) -> Scalar
 ```
 
 ### `rand_bernoulli` (Bernoulli distribution sampling)
-Samples a Bernoulli random variable, that is, \\( 1 \\) with probability \\( p \\), \\( 0 \\) with probability \\( 1-p \\). The parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)).
+Samples a Bernoulli random variable. That is, \\( 1 \\) with probability \\( p \\) and \\( 0 \\) with probability \\( 1-p \\). The parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)).
 More information [here](https://en.wikipedia.org/wiki/Bernoulli_distribution).
 
 ```nbt
@@ -367,7 +367,23 @@ fn rand_pareto<T: Dim>(α: Scalar, min: T) -> T
 
 ## Number theory
 
-Defined in: `core::number_theory`
+Defined in: `math::number_theory`
+
+### `gcd` (Greatest common divisor)
+The largest positive integer that divides each of the integers \\( a \\) and \\( b \\).
+More information [here](https://en.wikipedia.org/wiki/Greatest_common_divisor).
+
+```nbt
+fn gcd(a: Scalar, b: Scalar) -> Scalar
+```
+
+### `lcm` (Least common multiple)
+The smallest positive integer that is divisible by both \\( a \\) and \\( b \\).
+More information [here](https://en.wikipedia.org/wiki/Least_common_multiple).
+
+```nbt
+fn lcm(a: Scalar, b: Scalar) -> Scalar
+```
 
 ## Numerical methods
 
@@ -386,52 +402,58 @@ Find the root of the function \\( f \\) in the interval \\( [x_1, x_2] \\) using
 More information [here](https://en.wikipedia.org/wiki/Bisection_method).
 
 ```nbt
-fn root_bisect<A: Dim, B: Dim>(f: Fn[(A) -> B], x1: A, x2: A, x_tol: A, y_tol: B) -> A
+fn root_bisect<X: Dim, Y: Dim>(f: Fn[(X) -> Y], x1: X, x2: X, x_tol: X, y_tol: Y) -> X
 ```
 
 ### `root_newton` (Newton's method)
 Find the root of the function \\( f(x) \\) and its derivative \\( f'(x) \\) using Newton's method.
 More information [here](https://en.wikipedia.org/wiki/Newton%27s_method).
 
 ```nbt
-fn root_newton<A: Dim, B: Dim>(f: Fn[(A) -> B], f_prime: Fn[(A) -> B / A], x0: A, y_tol: B) -> A
+fn root_newton<X: Dim, Y: Dim>(f: Fn[(X) -> Y], f_prime: Fn[(X) -> Y / X], x0: X, y_tol: Y) -> X
 ```
 
 ## Geometry
 
 Defined in: `math::geometry`
 
 ### `hypot2`
+The length of the hypotenuse of a right-angled triangle \\( \sqrt{x^2+y^2} \\).
 
 ```nbt
 fn hypot2<T: Dim>(x: T, y: T) -> T
 ```
 
 ### `hypot3`
+The Euclidean norm of a 3D vector \\( \sqrt{x^2+y^2+z^2} \\).
 
 ```nbt
 fn hypot3<T: Dim>(x: T, y: T, z: T) -> T
 ```
 
 ### `circle_area`
+The area of a circle, \\( \pi r^2 \\).
 
 ```nbt
 fn circle_area<L: Dim>(radius: L) -> L^2
 ```
 
 ### `circle_circumference`
+The circumference of a circle, \\( 2\pi r \\).
 
 ```nbt
 fn circle_circumference<L: Dim>(radius: L) -> L
 ```
 
 ### `sphere_area`
+The surface area of a sphere, \\( 4\pi r^2 \\).
 
 ```nbt
 fn sphere_area<L: Dim>(radius: L) -> L^2
 ```
 
 ### `sphere_volume`
+The volume of a sphere, \\( \frac{4}{3}\pi r^3 \\).
 
 ```nbt
 fn sphere_volume<L: Dim>(radius: L) -> L^3

book/src/list-functions-strings.md

@@ -3,90 +3,105 @@
 Defined in: `core::strings`
 
 ### `str_length`
+The length of a string.
 
 ```nbt
 fn str_length(s: String) -> Scalar
 ```
 
 ### `str_slice`
+Subslice of a string.
 
 ```nbt
 fn str_slice(s: String, start: Scalar, end: Scalar) -> String
 ```
 
 ### `chr`
+Get a single-character string from a Unicode code point. Example: `0x2764 -> chr`.
 
 ```nbt
 fn chr(n: Scalar) -> String
 ```
 
 ### `lowercase`
+Convert a string to lowercase.
 
 ```nbt
 fn lowercase(s: String) -> String
 ```
 
 ### `uppercase`
+Convert a string to uppercase.
 
 ```nbt
 fn uppercase(s: String) -> String
 ```
 
 ### `str_append`
+Concatenate two strings.
 
 ```nbt
 fn str_append(a: String, b: String) -> String
 ```
 
 ### `str_find`
+Find the first occurrence of a substring in a string.
 
 ```nbt
 fn str_find(haystack: String, needle: String) -> Scalar
 ```
 
 ### `str_contains`
+Check if a string contains a substring.
 
 ```nbt
 fn str_contains(haystack: String, needle: String) -> Bool
 ```
 
 ### `str_replace`
+Replace all occurrences of a substring in a string.
 
 ```nbt
 fn str_replace(s: String, pattern: String, replacement: String) -> String
 ```
 
 ### `str_repeat`
+Repeat the input string `n` times.
 
 ```nbt
 fn str_repeat(a: String, n: Scalar) -> String
 ```
 
 ### `bin`
+Get a binary representation of a number. Example: `42 -> bin`.
 
 ```nbt
 fn bin(x: Scalar) -> String
 ```
 
 ### `oct`
+Get an octal representation of a number. Example: `42 -> oct`.
 
 ```nbt
 fn oct(x: Scalar) -> String
 ```
 
 ### `dec`
+Get a decimal representation of a number.
 
 ```nbt
 fn dec(x: Scalar) -> String
 ```
 
 ### `hex`
+Get a hexadecimal representation of a number. Example: `2^31-1 -> hex`.
 
 ```nbt
 fn hex(x: Scalar) -> String
 ```
 
 ### `base`
+Convert a number to the given base. Example: `42 -> base(16)`.
 
 ```nbt
 fn base(b: Scalar) -> Fn[(Scalar) -> String]

numbat/modules/core/functions.nbt

@@ -3,17 +3,17 @@
 fn id<A>(x: A) -> A = x
 
 @name("Absolute value")
-@description("Return the absolute value of the input, $|x|$. This works for quantities, too: `abs(-5 m) = 5 m`.")
+@description("Return the absolute value $|x|$ of the input. This works for quantities, too: `abs(-5 m) = 5 m`.")
 @url("https://doc.rust-lang.org/std/primitive.f64.html#method.abs")
 fn abs<T: Dim>(x: T) -> T
 
 @name("Square root")
-@description("Return the square root of the input, $\\sqrt\{x\}$: `sqrt(121 m^2) = 11 m`.")
+@description("Return the square root $\\sqrt\{x\}$ of the input: `sqrt(121 m^2) = 11 m`.")
 @url("https://en.wikipedia.org/wiki/Square_root")
 fn sqrt<D: Dim>(x: D^2) -> D = x^(1/2)
 
 @name("Cube root")
-@description("Return the cube root of the input, $\\sqrt[3]\{x\}$: `cbrt(8 m^3) = 2 m`.")
+@description("Return the cube root $\\sqrt[3]\{x\}$ of the input: `cbrt(8 m^3) = 2 m`.")
 @url("https://en.wikipedia.org/wiki/Cube_root")
 fn cbrt<D: Dim>(x: D^3) -> D = x^(1/3)
 
@@ -22,21 +22,21 @@ fn cbrt<D: Dim>(x: D^3) -> D = x^(1/3)
 fn sqr<D: Dim>(x: D) -> D^2 = x^2
 
 @name("Rounding")
-@description("Round to the nearest integer. If the value is half-way between two integers, round away from 0.")
+@description("Round to the nearest integer. If the value is half-way between two integers, round away from $0$.")
 @url("https://doc.rust-lang.org/std/primitive.f64.html#method.round")
 fn round<T: Dim>(x: T) -> T
 
 @name("Floor function")
-@description("Returns the largest integer less than or equal to `x`.")
+@description("Returns the largest integer less than or equal to $x$.")
 @url("https://doc.rust-lang.org/std/primitive.f64.html#method.floor")
 fn floor<T: Dim>(x: T) -> T
 
 @name("Ceil function")
-@description("Returns the smallest integer greater than or equal to `x`.")
+@description("Returns the smallest integer greater than or equal to $x$.")
 @url("https://doc.rust-lang.org/std/primitive.f64.html#method.ceil")
 fn ceil<T: Dim>(x: T) -> T
 
 @name("Modulo")
-@description("Calculates the least nonnegative remainder of `a (mod b)`.")
+@description("Calculates the least nonnegative remainder of $a (\\mod b)$.")
 @url("https://doc.rust-lang.org/std/primitive.f64.html#method.rem_euclid")
 fn mod<T: Dim>(a: T, b: T) -> T