NumLib — Plan9Basic Documentation

NumLib — Numeric & Math Library

Essential mathematical functions for Plan9Basic programs. Covers rounding, basic math, trigonometry (standard, inverse, and hyperbolic), angle conversion, comparisons, and random number generation. All functions return Extended precision floating-point values.

Category	Count	Description
Rounding & Truncation	5	cint, fix, int, round, frac
Basic Math	7	abs, sgn, sqr, exp, ln, log2, log10
Trigonometric	3	sin, cos, tan (radians)
Inverse Trigonometric	4	asin, acos, atan, atan2
Hyperbolic	3	sinh, cosh, tanh
Inverse Hyperbolic	3	asinh, acosh, atanh
Angle Conversion	2	degtorad, radtodeg
Comparison	3	max, min, cmpval
Random Numbers	2	randomize, rnd

ⓘ Note: Trigonometric functions use radians, not degrees. Use degtorad() and radtodeg() to convert. Plan9Basic has no built-in π constant — use acos(-1) or atan(1) * 4.

Rounding & Truncation

Function	Signature	Description
`cint(n)`	`cint@n`	Truncate toward zero (remove fraction)
`fix(n)`	`fix@n`	Same as cint — truncate toward zero
`int(n)`	`int@n`	Floor — largest integer ≤ n
`round(n)`	`round@n`	Round to nearest integer (banker’s rounding)
`frac(n)`	`frac@n`	Fractional part only

╯ plan9basic─◻✕
println cint(3.7)     ' 3
println cint(-3.7)    ' -3  (toward zero)
println int(3.7)      ' 3
println int(-3.7)     ' -4  (floor, toward -infinity)
println round(3.4)    ' 3
println round(3.5)    ' 4
println frac(3.75)    ' 0.75
println frac(-3.75)   ' -0.75

⚠ Warning: cint()/fix() truncate toward zero, but int() is the floor function. For negative numbers: cint(-3.7) = -3, int(-3.7) = -4.

Basic Math

Function	Signature	Description
`abs(n)`	`abs@n`	Absolute value (always non-negative)
`sgn(n)`	`sgn@n`	Sign: 1 (positive), 0 (zero), -1 (negative)
`sqr(n)`	`sqr@n`	Square root (n must be ≥ 0)
`exp(n)`	`exp@n`	e raised to power n
`ln(n)`	`ln@n`	Natural logarithm (base e, n > 0)
`log2(n)`	`log2@n`	Base-2 logarithm (n > 0)
`log10(n)`	`log10@n`	Base-10 logarithm (n > 0)

╯ plan9basic─◻✕
println abs(-5)        ' 5
println sgn(-17)       ' -1
println sgn(0)         ' 0
println sgn(42)        ' 1
println sqr(16)        ' 4
println sqr(2)         ' 1.41421356...

println exp(0)         ' 1
println exp(1)         ' 2.71828... (e)
println ln(1)          ' 0
println ln(10)         ' 2.302585...
println log2(1024)     ' 10
println log10(100)     ' 2

ⓘ Note: sqr() with a negative number returns NaN. ln(), log2(), and log10() require positive arguments.

Trigonometric Functions

Function	Signature	Description
`sin(r)`	`sin@n`	Sine of angle in radians (range: -1 to 1)
`cos(r)`	`cos@n`	Cosine of angle in radians (range: -1 to 1)
`tan(r)`	`tan@n`	Tangent of angle in radians

╯ plan9basic─◻✕
pi = acos(-1)
println sin(0)            ' 0
println sin(pi / 2)       ' 1
println cos(0)            ' 1
println cos(pi)           ' -1
println tan(0)            ' 0
println tan(pi / 4)       ' 1

' Using degrees (convert first!)
println sin(degtorad(30)) ' 0.5
println cos(degtorad(60)) ' 0.5

⚠ Warning: All trigonometric functions expect radians. Always wrap degree values with degtorad().

Inverse Trigonometric

Function	Signature	Description
`asin(n)`	`asin@n`	Arc sine — returns radians (n in -1..1)
`acos(n)`	`acos@n`	Arc cosine — returns radians (n in -1..1)
`atan(n)`	`atan@n`	Arc tangent — returns radians
`atan2(y, x)`	`atan2@nn`	Arc tangent of y/x (full 4-quadrant)

╯ plan9basic─◻✕
pi = acos(-1)
println radtodeg(asin(0.5))   ' 30
println radtodeg(acos(0.5))   ' 60
println radtodeg(atan(1))     ' 45

' atan2 handles all quadrants
println radtodeg(atan2(1, 1))    ' 45
println radtodeg(atan2(-1, -1))  ' -135

ⓘ Note: atan2(y, x) returns the angle in radians considering the signs of both arguments, giving the correct quadrant. Preferred over atan(y/x) for directional calculations.

Hyperbolic Functions

Function	Signature	Description
`sinh(n)`	`sinh@n`	Hyperbolic sine
`cosh(n)`	`cosh@n`	Hyperbolic cosine (always ≥ 1)
`tanh(n)`	`tanh@n`	Hyperbolic tangent (range: -1 to 1)

╯ plan9basic─◻✕
println sinh(0)    ' 0
println sinh(1)    ' 1.17520...
println cosh(0)    ' 1
println cosh(1)    ' 1.54308...
println tanh(0)    ' 0
println tanh(1)    ' 0.76159...

Inverse Hyperbolic

Function	Signature	Description
`asinh(n)`	`asinh@n`	Inverse hyperbolic sine (any n)
`acosh(n)`	`acosh@n`	Inverse hyperbolic cosine (n ≥ 1)
`atanh(n)`	`atanh@n`	Inverse hyperbolic tangent (-1 < n < 1)

╯ plan9basic─◻✕
println asinh(0)       ' 0
println asinh(1)       ' 0.88137...
println acosh(1)       ' 0
println acosh(2)       ' 1.31695...
println atanh(0)       ' 0
println atanh(0.5)     ' 0.54930...

ⓘ Note: acosh() requires n ≥ 1. atanh() requires -1 < n < 1. Values outside these domains produce errors.

Angle Conversion

Function	Signature	Description
`degtorad(d)`	`degtorad@n`	Convert degrees to radians
`radtodeg(r)`	`radtodeg@n`	Convert radians to degrees

╯ plan9basic─◻✕
println degtorad(180)      ' 3.14159... (pi)
println degtorad(90)       ' 1.57079...
println degtorad(45)       ' 0.78539...

pi = acos(-1)
println radtodeg(pi)       ' 180
println radtodeg(pi / 2)   ' 90
println radtodeg(1)        ' 57.2957...

Comparison Functions

Function	Signature	Description
`max(a, b)`	`max@nn`	Returns the larger of two values
`min(a, b)`	`min@nn`	Returns the smaller of two values
`cmpval(a, b)`	`cmpval@nn`	Compare: -1 (a<b), 0 (equal), 1 (a>b)
`cmpval(a, b, eps)`	`cmpval@nnn`	Compare with epsilon tolerance

╯ plan9basic─◻✕
println max(10, 20)           ' 20
println min(10, 20)           ' 10
println max(-5, -3)           ' -3
println min(-5, -3)           ' -5

println cmpval(5, 10)         ' -1
println cmpval(10, 10)        ' 0
println cmpval(15, 10)        ' 1

' Floating-point tolerance
a = 0.1 + 0.2
b = 0.3
println cmpval(a, b, 0.0001)  ' 0 (considered equal)

ⓘ Note: cmpval() with epsilon is essential for floating-point comparison. Direct equality tests like 0.1 + 0.2 = 0.3 may fail due to floating-point precision.

Random Number Generation

Function	Signature	Description
`randomize()`	`randomize@`	Initialize seed from current time
`rnd()`	`rnd@`	Random float in [0, 1)
`rnd(n)`	`rnd@n`	Random integer in [0, n-1]

╯ plan9basic─◻✕
randomize()              ' Call once at program start

println rnd()             ' e.g. 0.73291...
println rnd()             ' e.g. 0.15847...

' Simulate a die roll (1 to 6)
die = rnd(6) + 1
println "Die: "; die

' Random number from 1 to 10
println rnd(10) + 1

' Random number from 0 to 99
println rnd(100)

ⓘ Note: Call randomize() once at the start of your program. Without it, the random sequence will be the same every run.

Complete Examples

Calculating π

╯ calc_pi.bas─◻✕
' Different ways to calculate pi
println "=== Calculating Pi ==="

' Method 1: Using acos
pi1 = acos(-1)
println "acos(-1) = "; pi1

' Method 2: Using atan
pi2 = atan(1) * 4
println "atan(1) * 4 = "; pi2

' Method 3: Using asin
pi3 = asin(1) * 2
println "asin(1) * 2 = "; pi3

Right Triangle Solver

╯ triangle.bas─◻✕
' Given two legs, find hypotenuse and angles
println "=== Right Triangle Solver ==="
println "Given: a = 3, b = 4"

a = 3
b = 4
c = sqr(a * a + b * b)
println "Hypotenuse c = "; c

angleA = radtodeg(atan(a / b))
angleB = radtodeg(atan(b / a))
println ""
println "Angle A: "; angleA; " degrees"
println "Angle B: "; angleB; " degrees"
println "Angle C: 90 degrees"
println "Sum: "; angleA + angleB + 90

Quadratic Equation Solver

╯ quadratic.bas─◻✕
' Solve ax^2 + bx + c = 0
function solveQuadratic(a, b, c) local discriminant, sqrtD, x1, x2
    println "Equation: "; a; "x^2 + "; b; "x + "; c; " = 0"
    discriminant = b * b - 4 * a * c
    
    if discriminant < 0 then
        println "No real solutions"
        return 0
    endif
    
    if discriminant = 0 then
        x1 = -b / (2 * a)
        println "One solution: x = "; x1
        return 1
    endif
    
    sqrtD = sqr(discriminant)
    x1 = (-b + sqrtD) / (2 * a)
    x2 = (-b - sqrtD) / (2 * a)
    println "Solutions: x1 = "; x1; ", x2 = "; x2
    return 2
endfunction

solveQuadratic(1, -5, 6)    ' x=2, x=3
println ""
solveQuadratic(1, -4, 4)    ' x=2
println ""
solveQuadratic(1, 1, 1)     ' No real solutions

Circle Calculator

╯ circle.bas─◻✕
' Circle calculations and points on circumference
pi = acos(-1)
radius = 5

println "Radius: "; radius
println "Area: "; pi * radius * radius
println "Circumference: "; 2 * pi * radius
println "Diameter: "; 2 * radius
println ""

println "Points on the circle (every 45 degrees):"
for angle = 0 to 315 step 45
    rad = degtorad(angle)
    x = radius * cos(rad)
    y = radius * sin(rad)
    println "  "; angle; "deg: ("; round(x * 100) / 100; ", "; round(y * 100) / 100; ")"
next

Monte Carlo π Estimation

╯ monte_carlo.bas─◻✕
' Estimate pi using random points
randomize()

iterations = 1000
insideCircle = 0

for i = 1 to iterations
    x = rnd() * 2 - 1
    y = rnd() * 2 - 1
    distance = sqr(x * x + y * y)
    if distance <= 1 then
        insideCircle = insideCircle + 1
    endif
next

estimatedPi = 4 * insideCircle / iterations
println "Estimated pi: "; estimatedPi
println "Actual pi:    "; acos(-1)
println "Error:        "; abs(estimatedPi - acos(-1))

Dice Roller

╯ dice.bas─◻✕
' Roll multiple dice
randomize()

numDice = 5
println "Rolling "; numDice; " dice:"

total = 0
for i = 1 to numDice
    roll = rnd(6) + 1
    println "  Die "; i; ": "; roll
    total = total + roll
next

println ""
println "Total: "; total
println "Average: "; total / numDice

Quick Reference

Function	Signature	Description
`cint(n) / fix(n)`	`*@n`	Truncate toward zero
`int(n)`	`int@n`	Floor (largest integer ≤ n)
`round(n)`	`round@n`	Round to nearest (banker’s rounding)
`frac(n)`	`frac@n`	Fractional part
`abs(n)`	`abs@n`	Absolute value
`sgn(n)`	`sgn@n`	Sign: -1, 0, or 1
`sqr(n)`	`sqr@n`	Square root
`exp(n)`	`exp@n`	eⁿ
`ln(n) / log2(n) / log10(n)`	`*@n`	Logarithms (base e, 2, 10)
`sin(r) / cos(r) / tan(r)`	`*@n`	Trig functions (radians)
`asin(n) / acos(n) / atan(n)`	`a*@n`	Inverse trig (returns radians)
`atan2(y, x)`	`atan2@nn`	Full 4-quadrant arc tangent
`sinh(n) / cosh(n) / tanh(n)`	`*@n`	Hyperbolic functions
`asinh(n) / acosh(n) / atanh(n)`	`a*@n`	Inverse hyperbolic
`degtorad(d)`	`degtorad@n`	Degrees → radians
`radtodeg(r)`	`radtodeg@n`	Radians → degrees
`max(a, b) / min(a, b)`	`*@nn`	Larger / smaller value
`cmpval(a, b[, eps])`	`cmpval@nn[n]`	Compare: -1, 0, 1
`randomize()`	`randomize@`	Initialize random seed
`rnd() / rnd(n)`	`rnd@[n]`	Random float [0,1) or int [0,n-1]

Useful Constants

╯ constants.bas─◻✕
pi = acos(-1)         ' 3.14159265...
e = exp(1)            ' 2.71828182...

32 functions (34 registered signatures with overloads) across 9 categories.