std/i32
std/i32
Section titled “std/i32”std/i32 — integer (i32) receiver methods. Methods are migrated here gradually from the auto-injected magic prelude per docs/PRELUDE-TO-MODULES.md. Files declare import "std/i32"; to bring the methods into scope. During the transition the prelude itself does the same import so existing single-file programs keep working unchanged.
pub function (n: i32) abs(): i32(n: i32) abs() — absolute value. Edge case: i32::MIN
(-2147483648) has no positive counterpart in i32; the
magnitude is carried through i64 so the result wraps to
i32::MIN itself (matches Rust i32::wrapping_abs / Go’s
behaviour). Callers needing exact handling should widen
to i64 first.
is_digit
Section titled “is_digit”pub function (b: i32) is_digit(): booleanis_alpha
Section titled “is_alpha”pub function (b: i32) is_alpha(): booleanis_alnum
Section titled “is_alnum”pub function (b: i32) is_alnum(): booleanis_ascii_white_space
Section titled “is_ascii_white_space”pub function (b: i32) is_ascii_white_space(): booleanis_newline
Section titled “is_newline”pub function (b: i32) is_newline(): boolean(b: i32) is_newline() — true for LF (10) or CR (13). Use
when tokenising line-oriented input that should treat the
CRLF pair like a single boundary; pair with the trailing-CR
strip in lines().
is_vowel
Section titled “is_vowel”pub function (b: i32) is_vowel(): boolean(b: i32) is_vowel() — true for ASCII a/e/i/o/u in either
case. Y is not counted (it’s contextual; matches the
English-class default). Useful for text analysis,
Pig Latin / spelling-rule kinds of routines.
is_printable
Section titled “is_printable”pub function (b: i32) is_printable(): boolean(b: i32) is_printable() — printable ASCII (32..126).
Excludes control characters (0..31, 127) and the high-
byte range (128..255). Useful for log sanitisation /
diagnostic dumps.
is_control
Section titled “is_control”pub function (b: i32) is_control(): boolean(b: i32) is_control() — ASCII control character: 0..31
or 127. Inverse of is_printable in the ASCII range; the
high-byte range (128..255) is neither printable nor
control under this definition.
matches_any
Section titled “matches_any”pub function (b: i32) matches_any(bytes: string): boolean(b: i32) matches_any(bytes) — true if b appears anywhere
in the bytes string. Linear scan over bytes. Useful for
custom classifier predicates without writing a chain of
b == x || b == y || ... comparisons.
is_letter
Section titled “is_letter”pub function (b: i32) is_letter(): boolean(b: i32) is_letter() — alias for is_alpha. The name
matches the Unicode-aware convention seen in Roc / MoonBit;
is_alpha is the Python / Go convention. Both stay.
is_hex_digit
Section titled “is_hex_digit”pub function (b: i32) is_hex_digit(): booleanis_ascii
Section titled “is_ascii”pub function (b: i32) is_ascii(): booleanis_punct
Section titled “is_punct”pub function (b: i32) is_punct(): boolean(b: i32) is_punct() — true for an ASCII punctuation byte.
Set matches Python’s string.punctuation: 32 chars in the
four ranges 33-47, 58-64, 91-96, 123-126. Useful for
tokenisers that slice on !"#$%&'()*+,-./:;<=>?@[\]^_\``{|}~.
hex_digit
Section titled “hex_digit”pub function (b: i32) hex_digit(): string(b: i32) hex_digit() — single-byte string with the byte’s
lowercase hex representation, or "" if b isn’t a valid
digit (0..15). Inverse of is_hex_digit which classifies
the string byte → numeric value direction.
digit_value
Section titled “digit_value”pub function (b: i32) digit_value(): i32(b: i32) digit_value() — ‘0’..‘9’ → 0..9, -1 otherwise.
Useful for hand-rolled numeric parsers without the
__radix_digit detour.
hex_value
Section titled “hex_value”pub function (b: i32) hex_value(): i32(b: i32) hex_value() — ‘0’..‘9’ / ‘a’..‘f’ / ‘A’..’F’
→ 0..15, -1 otherwise. Same semantics as the internal
__hex_value but on the public byte-receiver surface.
to_ascii_string
Section titled “to_ascii_string”pub function (b: i32) to_ascii_string(): string(b: i32) to_ascii_string() — single-byte string from a
byte value. Out-of-range (< 0 or > 255) returns "". The
inverse of s[0] for single-char strings. Useful when
composing tokeniser output where you’ve got the byte and
want a string at the call site.
signum
Section titled “signum”pub function (n: i32) signum(): i32=== i32 sign helpers ===
(n: i32) signum() — -1 / 0 / 1 indicating the sign.
is_positive / is_negative / is_zero — boolean
companions. signum is the function name used by Rust /
Java / Haskell; matches Rust i32::signum exactly.
is_positive
Section titled “is_positive”pub function (n: i32) is_positive(): booleanis_negative
Section titled “is_negative”pub function (n: i32) is_negative(): booleanis_zero
Section titled “is_zero”pub function (n: i32) is_zero(): booleanis_in_range
Section titled “is_in_range”pub function (n: i32) is_in_range(lo: i32, hi: i32): boolean(n: i32) is_in_range(lo, hi) — true iff lo <= n < hi
(half-open). Empty / inverted ranges return false. The
standard “bucket” / “valid array index” check shape.
is_between
Section titled “is_between”pub function (n: i32) is_between(lo: i32, hi: i32): boolean(n: i32) is_between(lo, hi) — inclusive range check
(lo <= n <= hi). Companion to is_in_range which is half-
open. The closed form is the more natural shape for
human-facing bounds (“number must be between 1 and 100”).
reverse_digits
Section titled “reverse_digits”pub function (n: i32) reverse_digits(): i32(n: i32) reverse_digits() — flip the decimal digit
order. 1234 → 4321. Sign preserved. Leading zeros after
reverse drop (1000 → 1). Overflow on the reverse is
possible for large values; wraps silently.
is_palindrome
Section titled “is_palindrome”pub function (n: i32) is_palindrome(): boolean(n: i32) is_palindrome() — true iff the decimal
representation reads the same backwards. Negative
numbers return false (the minus sign doesn’t reverse
to itself). 0 is a palindrome.
sum_of_digits
Section titled “sum_of_digits”pub function (n: i32) sum_of_digits(): i32(n: i32) sum_of_digits() — total of the decimal digits.
123 → 6. Negative numbers use their magnitude. Useful for
digital-root puzzles, checksum precomputation.
has_digit
Section titled “has_digit”pub function (n: i32) has_digit(d: i32): boolean(n: i32) has_digit(d) — true if d (0..9) appears in
the decimal representation. Negative numbers use their
magnitude.
percent_of
Section titled “percent_of”pub function (n: i32) percent_of(total: i32): i32(n: i32) percent_of(total) — what percentage of total
is n? Returns (n * 100) / total, integer-truncated.
total <= 0 returns 0 (sentinel for “undefined”; a
caller wanting None should check first). Beware
overflow: n * 100 should fit in i32, so n must be
in roughly ±21M for the multiplication not to wrap.
is_multiple_of
Section titled “is_multiple_of”pub function (n: i32) is_multiple_of(d: i32): boolean(n: i32) is_multiple_of(d) — true if d divides n
evenly. d == 0 returns false (no value is a multiple
of zero; avoids the divide-by-zero trap). Negative
divisors are normalised via the modulo — (-6) % 3 == 0
holds.
min_zero
Section titled “min_zero”pub function (n: i32) min_zero(): i32(n: i32) min_zero() — saturate to non-negative: return
0 when n < 0, otherwise n. Cheaper / clearer than
n.max(0) for the common “negative-as-error” pattern.
sign_str
Section titled “sign_str”pub function (n: i32) sign_str(): string(n: i32) sign_str() — string form of the sign:
”+” for positive, ”-” for negative, "" for zero.
Useful for human-readable signed-magnitude formatting.
is_perfect_square
Section titled “is_perfect_square”pub function (n: i32) is_perfect_square(): boolean(n: i32) is_perfect_square() — true if n is k*k for some
non-negative k. Negative n returns false. Uses
sqrt_floor, so the check is O(log n) via that helper’s
binary search; faster than a linear k-walk.
factorial
Section titled “factorial”pub function (n: i32) factorial(): i32(n: i32) factorial() — n! for n in 0..12. Returns 1 for
0!. Caps at 12! = 479001600 (the largest factorial that
fits in i32); n >= 13 or n < 0 returns 0 as the
out-of-range sentinel. Callers needing 13!+ should widen
to i64 / bigint when those land.
is_prime
Section titled “is_prime”pub function (n: i32) is_prime(): boolean(n: i32) is_prime() — primality check via 6k±1 trial
division. n < 2 returns false. O(sqrt n). Adequate for
the small-n use cases (input validation, puzzle code);
callers running heavy number theory should bring a
sieve.
is_lower
Section titled “is_lower”pub function (b: i32) is_lower(): booleanis_upper
Section titled “is_upper”pub function (b: i32) is_upper(): booleanto_lower
Section titled “to_lower”pub function (b: i32) to_lower(): i32to_upper
Section titled “to_upper”pub function (b: i32) to_upper(): i32pub function (n: i32) min(other: i32): i32=== i32 numeric methods ===
(n: i32) abs() migrated to std/i32 — see the
import "std/i32"; at the top of this file. The
auto-prelude path in internal/checker/checker.go
follows stdlib imports declared here, so existing
programs keep working unchanged.
(n: i32) min(other) i32 / max / clamp(lo, hi) —
scalar reductions. Standard shape; matches Rust /
Gleam / Go (stdlib min/max which landed in Go 1.21).
pub function (n: i32) max(other: i32): i32pub function (n: i32) clamp(lo: i32, hi: i32): i32saturating_add
Section titled “saturating_add”pub function (n: i32) saturating_add(other: i32): i32saturating_sub
Section titled “saturating_sub”pub function (n: i32) saturating_sub(other: i32): i32checked_add
Section titled “checked_add”pub function (n: i32) checked_add(other: i32): Option[i32]checked_sub
Section titled “checked_sub”pub function (n: i32) checked_sub(other: i32): Option[i32]checked_div
Section titled “checked_div”pub function (n: i32) checked_div(other: i32): Option[i32](n: i32) checked_div(other) — None on divide-by-zero
OR on i32::MIN / -1 (the one i32 division that overflows).
is_even
Section titled “is_even”pub function (n: i32) is_even(): booleanis_odd
Section titled “is_odd”pub function (n: i32) is_odd(): booleanpub function (n: i32) pow(exp: i32): i32(n: i32) pow(exp) — integer exponentiation by squaring.
Negative exponents return 0 (lang has no fractional i32).
Overflow wraps silently (matches Rust wrapping_pow); use
i64 power for ranges beyond ~2^31.
pub function (n: i32) gcd(other: i32): i32(n: i32) gcd(other) — greatest common divisor via the
Euclidean algorithm. Sign-agnostic — both operands are
abs()‘d up front. gcd(0, n) == gcd(n, 0) == abs(n); gcd(0,
0) == 0 per the standard convention.
pub function (n: i32) lcm(other: i32): i32(n: i32) lcm(other) — least common multiple. Computed as
abs(a*b) / gcd(a, b) with the gcd-first ordering so an
overflow-prone multiply gets divided down before the
result lands. lcm(0, ) == lcm(, 0) == 0.
is_power_of_2
Section titled “is_power_of_2”pub function (n: i32) is_power_of_2(): boolean(n: i32) is_power_of_2() — true iff n is a positive
power of 2 (1, 2, 4, 8, …). Uses the (n & (n-1)) == 0
trick. Zero and negative numbers return false (zero is
debatable; we follow Rust’s convention where 0 isn’t a
power of 2).
next_power_of_2
Section titled “next_power_of_2”pub function (n: i32) next_power_of_2(): i32(n: i32) next_power_of_2() — smallest power of 2 that
is >= n. Returns 1 for n <= 1 (consistent with Rust’s
next_power_of_two). For n > 2^30 wraps to 0 — overflow
equivalent to “no representable power”.
log2_floor
Section titled “log2_floor”pub function (n: i32) log2_floor(): i32(n: i32) log2_floor() — floor(log2(n)) for n >= 1; -1
for n <= 0 (no real log; sentinel chosen so callers can
test >= 0 to mean “valid”). Equivalent to 31 -
leading_zeros(n) for positives.
sqrt_floor
Section titled “sqrt_floor”pub function (n: i32) sqrt_floor(): i32(n: i32) sqrt_floor() — integer square root. floor(sqrt(n))
for n >= 0; 0 for n <= 0 (degenerate fallback). Newton’s
method from a half-of-n starting point — converges in
O(log n) iterations regardless of starting guess.
ceil_div
Section titled “ceil_div”pub function (n: i32) ceil_div(d: i32): i32(n: i32) ceil_div(d) — n divided by d, rounded up.
Matches the standard (n + d - 1) / d formula for positive
d; for negative or zero d the result is undefined and
returns 0 (no panic — caller validates).
round_up_to
Section titled “round_up_to”pub function (n: i32) round_up_to(m: i32): i32(n: i32) round_up_to(m) — round n up to the nearest
multiple of m (m > 0). For n already a multiple, returns
n unchanged. m <= 0 returns n.
round_down_to
Section titled “round_down_to”pub function (n: i32) round_down_to(m: i32): i32(n: i32) round_down_to(m) — round n down to the nearest
multiple of m. Mirror of round_up_to.
divmod
Section titled “divmod”pub function (n: i32) divmod(d: i32): (i32, i32)(n: i32) divmod(d) — (quotient, remainder) pair from a
single division. Saves the two-call boilerplate (n/d, n%d)
and signals intent at the call site (the pair is the unit
of work). d == 0 returns (0, 0) — caller validates.
count_ones
Section titled “count_ones”pub function (n: i32) count_ones(): i32leading_zeros
Section titled “leading_zeros”pub function (n: i32) leading_zeros(): i32trailing_zeros
Section titled “trailing_zeros”pub function (n: i32) trailing_zeros(): i32pub function (n: i32) bit(i: i32): boolean(n: i32) bit(i) — read bit at position i (0 = LSB).
Out-of-range returns false. Useful for unpacking bit-
packed flags / nibbles.
set_bit
Section titled “set_bit”pub function (n: i32) set_bit(i: i32): i32(n: i32) set_bit(i) / clear_bit(i) / toggle_bit(i)
— return a fresh i32 with bit i set / cleared / flipped.
Out-of-range i is a no-op (returns n unchanged).
clear_bit
Section titled “clear_bit”pub function (n: i32) clear_bit(i: i32): i32toggle_bit
Section titled “toggle_bit”pub function (n: i32) toggle_bit(i: i32): i32byte_swap
Section titled “byte_swap”pub function (n: i32) byte_swap(): i32(n: i32) byte_swap() — reverse the four bytes of n.
Useful for endian conversion when reading / writing on-
disk formats. Reverses bytewise: ABCD → DCBA.
rotate_left
Section titled “rotate_left”pub function (n: i32) rotate_left(bits: i32): i32(n: i32) rotate_left(bits) / rotate_right(bits) —
circular shift by bits positions. Bits shifted out one
end re-enter the other. The bit count is masked to 0..31
(modulo 32) so out-of-range values still produce a valid
rotation. Useful for hash mixing, bit-permutation cipher
stages, and other bit-rotation primitives.
rotate_right
Section titled “rotate_right”pub function (n: i32) rotate_right(bits: i32): i32to_binary
Section titled “to_binary”pub function (n: i32) to_binary(): string(n: i32) to_binary() / to_oct() — sugar for
int_to_string_radix(n, 2) / (n, 8). Signed (negatives
emit a leading -).
to_oct
Section titled “to_oct”pub function (n: i32) to_oct(): stringdigits
Section titled “digits”pub function (n: i32) digits(): i32(n: i32) digits() — number of decimal digits in n. The
minus sign isn’t counted. Zero has 1 digit. Useful for
table-column-width math and progress bars.
pluralize
Section titled “pluralize”pub function (n: i32) pluralize(singular: string, plural: string): string(n: i32) pluralize(singular, plural) — pick singular
when |n| == 1, otherwise plural. Standard English-plural
helper. Doesn’t compose the count into the result — caller
formats "$n widget$s" themselves via concat or format().
to_string
Section titled “to_string”pub function (n: i32) to_string(): string(i32).to_string() / (u32).to_string() /
(i64).to_string() / (u64).to_string() — method-syntax
wrappers around the formatter. The receiver-method
dispatch in the checker maps n.to_string() to the
appropriate __method_<type>_to_string mangled name.
Routes through the pure-i32 int_to_string so handler-shaped
programs (whose codegen pulls in the f-string .to_string()
desugar via int_to_string) compile for arm64, where the
backend hasn’t lowered i64 ops yet. INT_MIN
(-2147483648) is special-cased before the negate-to-magnitude
step in int_to_string would overflow i32.
to_string_padded
Section titled “to_string_padded”pub function (n: i32) to_string_padded(width: i32): string(n: i32) to_string_padded(width) — decimal with zero-pad
to a minimum byte width. Negative numbers get their ’-’ in
the slot AFTER the leading zeros (i.e. “-0042”, not
“0-042”). Already-wide values pass through.
to_string_with_sep
Section titled “to_string_with_sep”pub function (n: i32) to_string_with_sep(sep: string): string(n: i32) to_string_with_sep(sep) — decimal with sep
inserted every three digits from the right. “1,234,567”
shape; sep is typically ”,” or ”_” or ” ”. Negative
numbers keep the ”-” prefix outside the grouping.
to_hex
Section titled “to_hex”pub function (n: i32) to_hex(): string(n: i32) to_hex() — lowercase hex without prefix.
Sugar for int_to_string_radix(n, 16) — emits a leading
’-’ for negative numbers. Callers that want the two’s-
complement bit pattern should widen to u32 first and use
int_to_string_radix on that; the i32 form here keeps
the signed semantics consistent with to_string.
to_rgb_hex
Section titled “to_rgb_hex”pub function (n: i32) to_rgb_hex(): string(n: i32) to_rgb_hex() — render the low 24 bits as a
“#RRGGBB” colour string (lowercase hex, leading ”#”,
zero-padded). Useful for CSS / SVG / terminal-ANSI
emission. Bits above bit 23 are ignored.
is_one
Section titled “is_one”pub function (n: i32) is_one(): boolean(n: i32) is_one() / is_minus_one() — sentinel-value
shortcuts for the two most-checked small-integer constants.
Mirror is_zero / is_positive / is_negative already in
this module.
is_minus_one
Section titled “is_minus_one”pub function (n: i32) is_minus_one(): boolean