SUB

Standard Library

The SUB standard library ships as nine modules written in SUB itself. Import any module with import and call its functions by name. Every function is verified through every backend in CI.

import "math"
import "arrays"
import "strings"
import "io"
import "path"
import "format"
import "testing"
import "encoding"
import "collections"

math

Arithmetic and floating-point helpers. Int and float variants are kept apart because the static backends infer one signature per function.

math.PI

The constant pi (3.141592653589793).

math.E

Euler's number (2.718281828459045).

math.TAU

2 * pi.

math.sign(x)

Return -1, 0 or 1 according to the sign of integer x.

math.sign_float(x)

Float variant of sign.

math.clamp(x, lo, hi)

Confine integer x to [lo, hi].

math.clamp_float(x, lo, hi)

Float variant of clamp.

math.is_even(n)

Return true if integer n is even.

math.is_odd(n)

Return true if integer n is odd.

math.gcd(a, b)

Greatest common divisor (Euclid).

math.lcm(a, b)

Least common multiple.

math.factorial(n)

n! for n >= 0.

math.fib(n)

The nth Fibonacci number.

math.is_prime(n)

Trial-division primality test.

math.ipow(base, exp)

Integer power via repeated squaring.

math.hypot(a, b)

Hypotenuse of a and b.

math.deg_to_rad(d)

Degrees to radians.

math.rad_to_deg(r)

Radians to degrees.

math.close_to(a, b, tol)

True if floats a and b differ by at most tol.

math.round_to(x, places)

Round x to the given number of decimal places.

math.modulo(a, b)

Named modulo; the operator form a % b is preferred.

math.cbrt(x)

Cube root via Newton's method; works for negative inputs.

arrays

Array manipulation utilities for integer arrays.

arrays.sum_int(a)

Sum of an integer array.

arrays.sum_float(a)

Sum of a float array.

arrays.product_int(a)

Product of an integer array.

arrays.mean_float(a)

Arithmetic mean of a float array (0.0 for empty).

arrays.min_int(a)

Smallest integer.

arrays.max_int(a)

Largest integer.

arrays.min_float(a)

Smallest float.

arrays.max_float(a)

Largest float.

arrays.index_of_int(a, want)

Index of the first equal element, or -1.

arrays.has_int(a, want)

True if the array contains the value.

arrays.count_int(a, want)

Number of occurrences of the value.

arrays.reverse_int(a)

New array with the elements reversed.

arrays.slice_int(a, start, stop)

Sub-array over the half-open range [start, stop), clipped.

arrays.concat_int(a, b)

Concatenate two integer arrays.

arrays.repeat_int(value, times)

New array containing value repeated times.

arrays.sorted_int(a)

New ascending sorted copy (insertion sort).

arrays.unique_int(a)

New array with duplicates removed, first-appearance order.

arrays.is_sorted_int(a)

True if the array is ascending.

strings

String manipulation and inspection utilities.

strings.is_empty(s)

True if s has zero length.

strings.is_blank(s)

True if s is empty or all whitespace.

strings.repeat(s, times)

s written times times.

strings.eq_ignore_case(a, b)

Case-insensitive equality.

strings.pad_left(s, width, pad)

Pad on the left to width (never truncates).

strings.pad_right(s, width, pad)

Pad on the right to width (never truncates).

strings.center(s, width, pad)

Center s in width using pad.

strings.line(s, n)

n copies of s; what a report separator wants.

strings.find(s, needle)

Index of the first occurrence of needle, or -1.

strings.starts_with(s, prefix)

True if s starts with prefix.

strings.ends_with(s, suffix)

True if s ends with suffix.

strings.count_of(s, needle)

Number of non-overlapping occurrences.

strings.strip_prefix(s, prefix)

Remove a leading prefix if present.

strings.strip_suffix(s, suffix)

Remove a trailing suffix if present.

strings.truncate(s, width, ellipsis)

Cut s to width, ending with ellipsis if truncated.

strings.reverse(s)

The string backwards.

strings.capitalize(s)

First letter uppercased, rest lowercased.

strings.title(s)

Every space-separated word capitalized.

strings.words(s)

Words of s, empty fields dropped.

strings.lines(s)

Split s on newlines.

strings.replace_first(s, old, repl)

Replace only the first occurrence.

strings.is_alpha(s)

True if every character is a letter.

strings.is_digit(s)

True if every character is a digit.

strings.is_numeric(s)

True if s looks like a number (digits, dots, minus).

strings.snake_case(s)

Convert to snake_case.

strings.camel_case(s)

Convert to camelCase.

strings.slugify(s)

URL/file-safe slug: lowercase, spaces to hyphens.

strings.escape_html(s)

Escape &, <, > and quotes.

strings.indent(s, n)

Indent every line by n spaces.

strings.is_palindrome(s)

True if s reads the same forwards and backwards.

strings.common_prefix(a, b)

Longest common prefix.

strings.common_suffix(a, b)

Longest common suffix.

io

Terminal colour, labelled lines and tables. ANSI escapes render on a terminal; they are bytes in a file.

io.red(s)

Wrap s in red ANSI colour.

io.green(s)

Wrap s in green ANSI colour.

io.yellow(s)

Wrap s in yellow ANSI colour.

io.blue(s)

Wrap s in blue ANSI colour.

io.magenta(s)

Wrap s in magenta ANSI colour.

io.cyan(s)

Wrap s in cyan ANSI colour.

io.bold(s)

Wrap s in bold ANSI style.

io.dim(s)

Wrap s in dim ANSI style.

io.info(message)

Print an info-labelled line.

io.ok(message)

Print an ok-labelled line.

io.warn(message)

Print a warn-labelled line.

io.fail(message)

Print a fail-labelled line.

io.row(cells, width)

One row of a table; each cell padded to width.

io.rule(columns, width)

A rule the width of a table.

io.heading(title)

Print a bold title and a rule under it.

io.progress(current, total, width)

Text progress bar for current/total.

io.plain(s)

Strip ANSI escape sequences.

path

Path manipulation with pure string operations.

path.path_join(parts)

Join path segments with "/", skipping empty segments.

path.dirname(p)

Everything before the last "/" ("." if none).

path.basename(p)

Everything after the last "/".

path.extension(p)

The file extension including the dot.

path.stem(p)

The file name without its extension.

path.is_absolute(p)

True if p starts with "/".

path.normalize(p)

Collapse //, drop /./ and trailing slashes.

format

String formatting helpers.

format.fmt(template, values)

Replace {0}, {1}, ... in template with values.

format.pad_number(n, width)

Zero-pad an integer to width characters.

format.repeat_char(ch, n)

Character repeated n times.

format.table_row(cells, widths)

Format a single table row with column widths.

format.table_rule(widths)

A horizontal rule for table_row's columns.

testing

Self-checking programs; an assertion failure aborts through every backend.

testing.assert(condition, msg)

Abort if condition is false.

testing.assert_eq(a, b, msg)

Abort if a != b.

testing.assert_ne(a, b, msg)

Abort if a == b.

testing.assert_true(val, msg)

Abort if val is falsy.

testing.assert_false(val, msg)

Abort if val is truthy.

testing.test(name)

Print a test header.

testing.summary()

Print the pass/fail tally.

encoding

Encoding and decoding helpers.

encoding.hex_encode(bytes)

Array of byte values to a hex string.

encoding.hex_decode(s)

Hex string to an array of byte values.

encoding.url_encode(s)

Percent-encode a string for use in a URL.

collections

Set operations and object helpers.

collections.set_union(a, b)

Elements in either array, deduplicated.

collections.set_intersection(a, b)

Elements in both arrays.

collections.set_difference(a, b)

Elements in a but not in b.

collections.set_has(s, item)

True if item is in the set.

collections.peek(arr)

Last element without popping it (null if empty).

collections.peek_front(arr)

First element without removing it (null if empty).

Next Steps