The math Lib — Safe Division, Number Theory, and Statistics

10.1. Why Does the math Lib Exist? (The Real-World Problem & Ridgun Philosophy)

"Why do I need a math lib written from scratch in pure Ridgun instead of just linking a legacy C library?"

That is the first question every systems engineer asks when meeting math. And the answer captures the entire philosophy of ridgun-libs:

Let's be honest: an unexpected division by zero in production or the % operator returning negative remainders in C or Java has crashed more services than anyone likes to admit.

The math lib provides total division primitives safe against d == 0 (div ceil, div floor, div euclid, mod euclid), $O(\log E)$ modular exponentiation and inverse, integer roots/logs, combinatorics, primality testing, and the clamp x between lo and hi mixfix operator.

In a traditional ecosystem, solving MATH tasks means pulling in external C dependencies, wrestling with raw pointers, opaque type conversions, unchecked exceptions, or unpredictable garbage-collector pauses. In Ridgun, the math lib (src/main/ridgun/lib/math.rg) tackles the problem with four non-negotiable principles:

1. Declare import math (or import math as alias) at the top of your file: every lib defines its module :: math namespace, and under --strict multi-word functions are always called with natural spaces.
2. Chain your data pipelines left-to-right with ->: write input step one -> step two -> result, use (+ _ _ +) sequence masks to destructure tuples/lists, and omit _ = on sequential statements (or discard with -> ()).
3. Tail-Call Optimization (TCO): all internal loops in math are tail-recursive and compile into native hardware loops using $O(1)$ stack space.
4. Deterministic Memory (RMM1 / RMM2): every intermediate allocation is reclaimed at the exact instruction where its last read finishes, with no Garbage Collector.

---

10.2. Native Artifacts, Imports, and Complete math API Catalog

In ridgun-libs, math is a first-class lib located at src/main/ridgun/lib/math.rg (domain MATH). When built with stable bundle, it compiles into three native artifacts:

Artifact	Path	Purpose
Ridgun Bundle	target/bundles/math.rglib	Portable distribution and direct import math resolution
Compiled Archive	target/math.rgc	Type-checked intermediate artifact verified by ridgunc
ELF64 Shared Object	target/libmath.so	Native dynamic shared library with zero C or libc dependencies

Every lib declares its own namespace via module :: math: simply write import math (or import math as alias) at the top and call its functions with natural spaces (my fn x) and left-to-right -> pipelines (x my fn -> result).

10.2.1. Summary of math Functional Families

Signature / Function / Type	Purpose & Usage
math abs / math sign / math min / math max	Magnitude, sign (-1, 0, 1), and extrema
clamp x between lo and hi	Mixfix operator (op ::) clamping x into [lo, hi]
math div ceil / math div floor / math div euclid / math mod euclid	Division-by-zero-safe rounding and non-negative Euclidean remainder
math pow / math isqrt / math ilog2 / math ilog10	$O(\log E)$ power, Newton integer square root, and integer logarithms
math gcd / math lcm / math mod pow / math mod inv / math is prime	Euclidean GCD/LCM, modular arithmetic, and $6k \pm 1$ primality
math sum / math mean floor / math median floor / math variance floor	Overflow-safe combinatorics (nCr) and integer list statistics

10.2.2. Exhaustive Catalog of Types and Signatures in src/main/ridgun/lib/math.rg

Below is the complete inventory of algebraic data types (type), mixfix operators (op ::), and function signatures (fn ::) defined in src/main/ridgun/lib/math.rg (0 types, 1 operators, and 56 functions):

Mixfix Operators (op ::) in math:

op :: clamp Int between Int and Int => Int

#	Function / Signature (fn ::)	Return Type
1	fn :: math abs Int	Int
2	fn :: math sign Int	Int
3	fn :: math min Int Int	Int
4	fn :: math max Int Int	Int
5	fn :: math clamp Int Int Int	Int
6	fn :: math is even Int	Bool
7	fn :: math is odd Int	Bool
8	fn :: m fix mod Int Int	Int
9	fn :: math mod euclid Int Int	Int
10	fn :: math div euclid Int Int	Int
11	fn :: m adjust floor Int Int Int Int	Int
12	fn :: math div floor Int Int	Int
13	fn :: m adjust ceil Int Int Int Int	Int
14	fn :: math div ceil Int Int	Int
15	fn :: m pow loop Int Int Int	Int
16	fn :: math pow Int Int	Int
17	fn :: m isqrt step Int Int Int	Int
18	fn :: m isqrt loop Int Int	Int
19	fn :: math isqrt Int	Int
20	fn :: m ilog2 loop Int Int	Int
21	fn :: math ilog2 Int	Int
22	fn :: m ilog10 loop Int Int	Int
23	fn :: math ilog10 Int	Int
24	fn :: m next pow2 loop Int Int	Int
25	fn :: math next power of two Int	Int
26	fn :: math is power of two Int	Bool
27	fn :: m gcd loop Int Int	Int
28	fn :: math gcd Int Int	Int
29	fn :: math lcm Int Int	Int
30	fn :: m mod pow loop Int Int Int Int	Int
31	fn :: math mod pow Int Int Int	Int
32	fn :: m egcd loop Int Int Int Int	Int Int
33	fn :: m finish mod inv (Int Int) Int	Int
34	fn :: math mod inv Int Int	Int
35	fn :: m prime loop Int Int	Bool
36	fn :: math is prime Int	Bool
37	fn :: m fact loop Int Int	Int
38	fn :: math factorial Int	Int
39	fn :: m ncr loop Int Int Int Int	Int
40	fn :: math ncr Int Int	Int
41	fn :: m fib loop Int Int Int	Int
42	fn :: math fibonacci Int	Int
43	fn :: m list len [Int]	Int
44	fn :: m nth int [Int] Int	Int
45	fn :: math sum [Int]	Int
46	fn :: math product [Int]	Int
47	fn :: m mean len [Int] Int	Int
48	fn :: math mean [Int]	Int
49	fn :: m min loop [Int] Int	Int
50	fn :: math min list [Int]	Int
51	fn :: m max loop [Int] Int	Int
52	fn :: math max list [Int]	Int
53	fn :: m insert sorted Int [Int]	[Int]
54	fn :: m sort ints [Int]	[Int]
55	fn :: m median sorted [Int] Int Int	Int
56	fn :: math median [Int]	Int

---

10.3. Deep Dive into math: Step-by-Step Examples for Every Feature

A signature table alone is never enough: let's explore every capability of the math lib through progressive, runnable Ridgun examples. We will start with two everyday tabular recipes and then walk through every functional scenario, transformation, and boundary condition verified in src/test/ridgun/test math.rg.

10.3.1. Example 1: Core Tabular Workflow with math

Notice how in Ridgun the = signs and transformation steps using math align into a clean, scannable table without unnecessary mutable variables or hidden side effects:

import math

fn :: verificar clave modular Int Int => Int Int Bool
      verificar clave modular base primo =
        primo math is prime -> es_p
        math mod pow base (primo - 1) primo -> pot
        math mod inv base primo -> inv
        (pot, inv, es_p)

10.3.2. Example 2: Safe Composition and Boundary Handling

Every function in the math lib is designed to compose cleanly with boolean guards | and with the rest of the 32 libs in ridgun-libs:

import math

fn :: calcular paginas y cuota Int Int Int => Int Int
      calcular paginas y cuota items por_pag uso =
        math div ceil items por_pag -> pags
        clamp uso between 0 and 100 -> cuota
        (pags, cuota)

10.3.3. Example 3: Bounds (abs, sign, min, max), Mixfix clamp ... between ... and ..., and Division-by-Zero-Safe Rounding (div ceil, div floor, div euclid, mod euclid)

In this hands-on walkthrough we thoroughly exercise how math behaves across this functional area, covering standard inputs, parameter combinations, and corner cases:

fn :: test math bounds and division => ()
      test math bounds and division =
        assert int equals (math abs (0 - 42)) 42 "math abs negative"
        assert int equals (math abs 42) 42 "math abs positive"
        assert int equals (math abs 0) 0 "math abs zero"
        assert int equals (math sign (0 - 99)) (0 - 1) "math sign negative"
        assert int equals (math sign 0) 0 "math sign zero"
        assert int equals (math sign 99) 1 "math sign positive"
        assert int equals (math min 10 (0 - 5)) (0 - 5) "math min"
        assert int equals (math max 10 (0 - 5)) 10 "math max"
        assert int equals (math clamp (0 - 10) 0 100) 0 "math clamp low"
        assert int equals (math clamp 50 0 100) 50 "math clamp mid"
        assert int equals (math clamp 250 0 100) 100 "math clamp high"
        assert int equals (clamp 150 between 10 and 100) 100 "op clamp between and"
        assert true (math is even 42) "math is even 42"
        assert false (math is even 41) "math is even 41"
        assert true (math is odd (0 - 7)) "math is odd -7"
        assert int equals (math div ceil 7 3) 3 "math div ceil 7/3"
        assert int equals (math div ceil 6 3) 2 "math div ceil 6/3"
        assert int equals (math div ceil (0 - 7) 3) (0 - 2) "math div ceil -7/3"
        assert int equals (math div floor (0 - 7) 3) (0 - 3) "math div floor -7/3"
        assert int equals (math div floor 7 3) 2 "math div floor 7/3"
        assert int equals (math mod euclid (0 - 7) 3) 2 "math mod euclid -7 % 3 == 2"
        assert int equals (math div euclid (0 - 7) 3) (0 - 3) "math div euclid -7 / 3 == -3"
        -- Division by zero safety
        assert int equals (math div ceil 10 0) 0 "math div ceil / 0 == 0"
        assert int equals (math div floor 10 0) 0 "math div floor / 0 == 0"
        assert int equals (math div euclid 10 0) 0 "math div euclid / 0 == 0"
        assert int equals (math mod euclid 10 0) 0 "math mod euclid % 0 == 0"
        ()

10.3.4. Example 4: Powers, Integer Roots & Logs (pow, isqrt, ilog2, ilog10), Number Theory (gcd, lcm, mod pow, mod inv, is prime), and Combinatorics (factorial, nCr, fib)

In this hands-on walkthrough we thoroughly exercise how math behaves across this functional area, covering standard inputs, parameter combinations, and corner cases:

fn :: test math powers number theory and combinatorics => ()
      test math powers number theory and combinatorics =
        assert int equals (math pow 2 10) 1024 "2^10 == 1024"
        assert int equals (math pow 5 0) 1 "5^0 == 1"
        assert int equals (math pow 5 (0 - 2)) 0 "negative exp -> 0"
        assert int equals (math isqrt 0) 0 "isqrt 0"
        assert int equals (math isqrt 1) 1 "isqrt 1"
        assert int equals (math isqrt 15) 3 "isqrt 15"
        assert int equals (math isqrt 16) 4 "isqrt 16"
        assert int equals (math isqrt 10000) 100 "isqrt 10000"
        assert int equals (math isqrt (0 - 4)) (0 - 1) "isqrt negative -> -1"
        assert int equals (math ilog2 1) 0 "ilog2 1 == 0"
        assert int equals (math ilog2 1024) 10 "ilog2 1024 == 10"
        assert int equals (math ilog2 0) (0 - 1) "ilog2 0 == -1"
        assert int equals (math ilog10 999) 2 "ilog10 999 == 2"
        assert int equals (math ilog10 1000) 3 "ilog10 1000 == 3"
        assert true (math is power of two 64) "64 is power of two"
        assert false (math is power of two 63) "63 is not power of two"
        assert false (math is power of two 0) "0 is not power of two"
        assert int equals (math next power of two 33) 64 "next power of two 33 == 64"
        assert int equals (math gcd 48 18) 6 "gcd(48, 18) == 6"
        assert int equals (math gcd (0 - 48) 18) 6 "gcd(-48, 18) == 6"
        assert int equals (math lcm 12 18) 36 "lcm(12, 18) == 36"
        assert int equals (math lcm 0 18) 0 "lcm(0, 18) == 0"
        assert int equals (math mod pow 2 10 1000) 24 "2^10 mod 1000 == 24"
        assert int equals (math mod pow 3 200 97) 62 "3^200 mod 97 == 62"
        assert int equals (math mod inv 3 11) 4 "3 * 4 == 12 == 1 mod 11"
        assert int equals (math mod inv 6 12) (0 - 1) "mod inv non-coprime -> -1"
        assert false (math is prime 1) "1 not prime"
        assert true (math is prime 2) "2 prime"
        assert true (math is prime 97) "97 prime"
        assert false (math is prime 99) "99 not prime"
        assert int equals (math factorial 5) 120 "5! == 120"
        assert int equals (math factorial 0) 1 "0! == 1"
        assert int equals (math ncr 10 3) 120 "C(10, 3) == 120"
        assert int equals (math fibonacci 10) 55 "fib(10) == 55"
        ()

10.3.5. Example 5: Integer List Descriptive Statistics (sum, product, min list, max list, mean floor, median floor, variance floor)

In this hands-on walkthrough we thoroughly exercise how math behaves across this functional area, covering standard inputs, parameter combinations, and corner cases:

fn :: test math list statistics => ()
      test math list statistics =
        xs = [30, 10, 50, 20, 40]
        assert int equals (math sum xs) 150 "sum"
        assert int equals (math product [2, 3, 4]) 24 "product"
        assert int equals (math mean xs) 30 "mean"
        assert int equals (math median xs) 30 "median odd"
        assert int equals (math median [10, 20, 30, 40]) 25 "median even"
        assert int equals (math min list xs) 10 "min list"
        assert int equals (math max list xs) 50 "max list"
        assert int equals (math sum []) 0 "sum []"
        assert int equals (math mean []) 0 "mean []"
        assert int equals (math median []) 0 "median []"
        ()

---

10.4. Under the Hood: How math Is Built in Pure Ridgun (src/main/ridgun/lib/math.rg)

One of the biggest advantages of ridgun-libs is that there are no C black boxes. You can open src/main/ridgun/lib/math.rg and read exactly how every operation is implemented using pattern matching, | / |. guard trees, and tail-call optimization (TCO). Let's inspect the key building blocks of its real implementation:

10.4.1. Internal Implementation: Bounds, Sign & Parity

Observe how math.rg declares explicit fn :: ... => ... contracts first and resolves each case through aligned equations and tail calls:

module :: math

fn :: math abs Int => Int
      math abs x   =
        | x < 0     = 0 - x
        | otherwise = x

fn :: math sign Int => Int
      math sign x   =
        | x < 0     = 0 - 1
        | x > 0     = 1
        | otherwise = 0

fn :: math min Int Int => Int
      math min a   b   =
        | a <= b    = a
        | otherwise = b

fn :: math max Int Int => Int
      math max a   b   =
        | a >= b    = a
        | otherwise = b

fn :: math clamp Int Int Int => Int
      math clamp x   lo  hi  =
        | x < lo    = lo
        | x > hi    = hi
        | otherwise = x

op :: clamp Int between Int and Int => Int
      clamp x   between lo  and hi  =  math clamp x lo hi

fn :: math is even Int => Bool
      math is even x   =  (x % 2) == 0

fn :: math is odd Int => Bool
      math is odd x   =  (x % 2) != 0

10.4.2. Internal Implementation: Powers, Integer Roots & Logarithms

Observe how math.rg declares explicit fn :: ... => ... contracts first and resolves each case through aligned equations and tail calls:

fn :: m pow loop Int Int Int => Int
      m pow loop base exp acc =
        | exp <= 0       = acc
        | (exp % 2) == 1 = m pow loop (base * base) (exp / 2) (acc * base)
        | otherwise      = m pow loop (base * base) (exp / 2) acc

fn :: math pow Int  Int => Int
      math pow base exp =
        | exp < 0   = 0
        | exp == 0  = 1
        | otherwise = m pow loop base exp 1

fn :: m isqrt step Int Int Int => Int
      m isqrt step n x nx =
        | nx >= x   = x
        | otherwise = m isqrt loop n nx

fn :: m isqrt loop Int Int => Int
      m isqrt loop n   x   =  m isqrt step n x ((x + (n / x)) / 2)

fn :: math isqrt Int => Int
      math isqrt n   =
        | n < 0     = 0 - 1
        | n == 0    = 0
        | n < 4     = 1
        | otherwise = m isqrt loop n (n / 2)

fn :: m ilog2 loop Int Int => Int
      m ilog2 loop n   acc =
        | n <= 1    = acc
        | otherwise = m ilog2 loop (n / 2) (acc + 1)

fn :: math ilog2 Int => Int
      math ilog2 n   =
        | n <= 0    = 0 - 1
        | otherwise = m ilog2 loop n 0

fn :: m ilog10 loop Int Int => Int
      m ilog10 loop n   acc =
        | n < 10    = acc
        | otherwise = m ilog10 loop (n / 10) (acc + 1)

fn :: math ilog10 Int => Int
      math ilog10 n   =
        | n <= 0    = 0 - 1
        | otherwise = m ilog10 loop n 0

fn :: m next pow2 loop Int Int => Int
      m next pow2 loop target cur =
        | cur >= target = cur
        | otherwise     = m next pow2 loop target (cur * 2)

fn :: math next power of two Int => Int
      math next power of two n =
        | n <= 1    = 1
        | otherwise = m next pow2 loop n 1

fn :: math is power of two Int => Bool
      math is power of two n =
        | n <= 0    = False
        | otherwise = (math next power of two n) == n

10.4.3. Internal Implementation: Combinatorics & Sequences

Observe how math.rg declares explicit fn :: ... => ... contracts first and resolves each case through aligned equations and tail calls:

fn :: m fact loop Int Int => Int
      m fact loop n   acc =
        | n <= 1    = acc
        | otherwise = m fact loop (n - 1) (acc * n)

fn :: math factorial Int => Int
      math factorial n   =
        | n < 0     = 0
        | otherwise = m fact loop n 1

fn :: m ncr loop Int Int Int Int => Int
      m ncr loop n k idx acc =
        | idx > k   = acc
        | otherwise = m ncr loop n k (idx + 1) ((acc * ((n - k) + idx)) / idx)

fn :: math ncr Int Int => Int
      math ncr n   k   =
        | k < 0 or n < 0 or k > n = 0
        | k == 0 or k == n        = 1
        | otherwise =
          eff_k = math min k (n - k)
          m ncr loop n eff_k 1 1

fn :: m fib loop Int Int Int => Int
      m fib loop rem a b =
        | rem <= 0  = a
        | otherwise = m fib loop (rem - 1) b (a + b)

fn :: math fibonacci Int => Int
      math fibonacci n   =
        | n <= 0    = 0
        | otherwise = m fib loop n 0 1

10.4.4. Internal Implementation: Integer List Statistics

Observe how math.rg declares explicit fn :: ... => ... contracts first and resolves each case through aligned equations and tail calls:

fn :: m list len [Int]    => Int
      m list len []       =  0
      m list len (_:rest) =  1 + (m list len rest)

fn :: m nth int [Int]    Int => Int
      m nth int []       _   =  0
      m nth int (x:rest) idx =
        | idx <= 0  = x
        | otherwise = m nth int rest (idx - 1)

fn :: math sum [Int]    => Int
      math sum []       =  0
      math sum (x:rest) =  x + (math sum rest)

fn :: math product [Int]    => Int
      math product []       =  1
      math product (x:rest) =  x * (math product rest)

fn :: m mean len [Int] Int => Int
      m mean len xs    n   =
        | n == 0    = 0
        | otherwise = (math sum xs) / n

fn :: math mean [Int] => Int
      math mean xs    =  m mean len xs (m list len xs)

fn :: m min loop [Int]    Int => Int
      m min loop []       cur =  cur
      m min loop (x:rest) cur =  m min loop rest (math min cur x)

fn :: math min list [Int]    => Int
      math min list []       =  0
      math min list (x:rest) =  m min loop rest x

fn :: m max loop [Int]    Int => Int
      m max loop []       cur =  cur
      m max loop (x:rest) cur =  m max loop rest (math max cur x)

fn :: math max list [Int]    => Int
      math max list []       =  0
      math max list (x:rest) =  m max loop rest x

fn :: m insert sorted Int [Int]    => [Int]
      m insert sorted v   []       =  [v]
      m insert sorted v   (x:rest) =
        | v <= x    = [v, x] :: rest
        | otherwise = [x] :: (m insert sorted v rest)

fn :: m sort ints [Int]    => [Int]
      m sort ints []       =  []
      m sort ints (x:rest) =  m insert sorted x (m sort ints rest)

fn :: m median sorted [Int] Int Int => Int
      m median sorted sorted n mid =
        | n == 0       = 0
        | (n % 2) == 1 = m nth int sorted mid
        | otherwise    = ((m nth int sorted (mid - 1)) + (m nth int sorted mid)) / 2

fn :: math median [Int] => Int
      math median xs    =
        n = m list len xs
        m median sorted (m sort ints xs) n (n / 2)

---

10.5. Algorithmic Guarantees, RMM1/RMM2 Memory, and the 5 Golden Rules of math

• Algorithmic & Safety Guarantee: Total arithmetic functions (returning 0 on <= 0 divisors instead of raising SIGFPE), free of floating-point rounding drift.
• $O(1)$ Stack Complexity via TCO: Every recursive loop in src/main/ridgun/lib/math.rg is in tail position, so ridgunc compiles them into native jumps with zero stack growth.
• Deterministic Memory (RMM1/RMM2): Zero garbage-collector pauses; all intermediate allocations are reclaimed deterministically on scope exit.
• Continuous Verification: Statically checked via stable check and tested by the automated suite in src/test/ridgun/test math.rg.

The 5 Golden Rules When Programming with math

1. Declare import math at the top of your file and take advantage of space/underscore equivalence so your code reads like natural prose.
2. Align your data pipelines with =: chain math calls into named intermediate steps and let stable format align the columns.
3. Leverage math's total functions inside | guards: inspect return values or unwrap ADTs via pattern matching rather than assuming external input is valid.
4. Avoid cloning large structures when only reading: remember that under RMM2, function input arguments incur zero reference-count overhead (+0 / -0).
5. Pair math with test (import test): always lock in your domain invariants with assert equals or assert true.

---

In Chapter 11, we will explore the list lib in full depth (The list Lib — Slicing, $O(N \log N)$ Mergesort, and Associative KV Maps).