Standard library overview
Every public symbol in Axle’s standard library is reachable
from user code via use:
use std::collections::ArrayList; // import one symbol (a type)
use std::text; // or bind the module: text::parseI32("42")
use std::numeric::random; // bind, then call random::nextI64() How the library is shaped
Three recurring shapes cover almost every module. Recognising them tells you how to call a symbol before you open its reference page.
Free functions — a module exposes plain functions you call module-qualified:
text::parseI32("42"),encoding::base64Encode(s),datetime::formatIso8601(ms). Bind the module once (use std::text;) and reach every function through it —text::parseI32(…), never a one-function-per-line import list. When a function’s signature mentions a module-local enum (for examplelog::setLevel, which takes aLogLevel), add a secondusefor the enum type only —use std::system::log; use std::system::log::LogLevel;— and keep calling through the module:log::setLevel(LogLevel::INFO). The type is imported; the functions never are.Façade classes — a class with only static methods and no instance state, reached through
:::Random::seed(42),Float::parse("1.0"). A façade is just a namespace for related operations — there is nothing to construct. The prelude classes (Console,Random,Async,ProcessBuilder,Process,Float,Char) need nouse.A façade earns its place by holding state between calls, or by wrapping a receiver the method surface cannot reach. Operations over a plain value are methods on the value itself rather than a façade — see Methods on primitives below.
A prelude class name is a fallback: the prelude is injected ahead of your declarations, so it does not offer one you declare yourself, and a file writing its own
class Consoleis not a duplicate — its class is the one its references mean. A name the library needs for itself is the exception:ProcessBuildernamesProcess, and a name an explicitusebrought in (use std::collections::HashMap;besideclass HashMap) cannot be declared again.Handle-backed classes — a class wrapping a native resource behind a single
handle : i64field: file streams,Pattern,Process, thenetsockets. Most are constructed directly withnew Foo(...); a few are only ever handed to you, either by a static factory (BufferedReader::open(path),FileInputStream::fromFile(f),ByteArrayInputStream::fromString(s),Path::from(s)) or by another object (Processcomes fromProcessBuilder.start()and has no constructor of its own). Whichever way you obtain one, each satisfies theCloseablecontract, so you pair the open withdefer close()and the handle is released on every exit path (aCloseabletype with no registered teardown, such as a user-defined resource class, is checked byE0511; stdlib handles such asPatternare released by the compiler at scope exit):let f : File = new File("data.txt"); defer f.close();Releasing a handle can itself fail, so
close()carries! IOExceptionin its signature. A real program therefore either declares the set onward (fn main() : i32 ! IOException) or wraps the work intry { … } catch e : IOException { … }— the same no-silent-escape rule every fallible call obeys, see Error handling.
Ordinary data classes (ArrayList<T>, HashMap<K,V>, StringBuilder, LocalDateTime) are also built with new, but hold no OS handle, so
they need no close(). A string handed to a collection is copied into it — see Collections for the ownership rules.
Recognising the shape at the call site
The spelling of a name tells you which shape you are dealing with before you open its reference page:
| You see… | It is a… | Reach it with |
|---|---|---|
mod::fn(args) after use std::mod; | free function | bind the module, call through mod:: |
Class::method(args), nothing constructed | façade (static-only class) | call through ::; the prelude ones (Console, Random, …) need no use |
new Class(args) then .method(…) | instance class | new to build; if it holds a handle, pair with defer close() |
The rule of thumb: capitalised name + :: = façade or constructor (a type), lowercase name + :: = module (a namespace of free
functions). A façade groups related operations behind a type with no
state to construct; a module groups free functions behind an import.
Both read as Name::thing, and the case of Name is what tells them
apart.
The prelude
Some names resolve with no use at all. The prelude holds the
language’s own vocabulary and the few facades that carry state. Its
contents are defined in one file, and the rest of the library needs an
explicit use.
| Kind | Names |
|---|---|
| Classes | Console, Random, Async, ProcessBuilder, Process, Float, Char, String |
| Exception hierarchy | Exception, RuntimeException, IOException, FileNotFoundException, ParseException, IllegalArgumentException, IllegalStateException, IndexOutOfBoundsException, and the rest of the family in std/lang |
| Free functions | exit, sleep, now, nanoTime (from std::sys); argc, hasEnv, pid, parentPid (from std::sys::process) |
| Built-in print functions | print, println, eprint, eprintln |
Math, System, I32, I64, F64 and Bool are not in the prelude.
Their operations are methods on the values, or free functions of a module.
Methods on primitives
Numeric and string operations are methods on the value, not statics on a utility class. There is nothing to import — the receiver’s type selects the method:
use std::numeric::math;
use std::lang::ParseException;
fn main() : i32 {
let x : f64 = 2.5;
println(x.sqrt()); // 1.5811388300841898
println(x.floor()); // 2
println((-x).abs().max(1.0)); // 2.5
println(x.floorToInt()); // 2
println(x.isFinite()); // true
println((255).toHex()); // ff
println((-7).abs()); // 7
println((3).min(9)); // 3
println(math::pi()); // 3.141592653589793
println(math::hypot(3.0, 4.0)); // 5
try {
println("42".toI32() + 1); // 43
} catch e : ParseException {
eprintln("not a number");
}
return 0;
} The numeric surface, by receiver type. Every row is a method and resolves to a top-level function of its module:
| Receiver | Methods | Result type |
|---|---|---|
f64 | sqrt pow cbrt exp ln log2 log10 sin cos tan asin acos atan sinh cosh tanh floor ceil trunc abs sign min max | f64 |
f64 | round | i64 (half away from zero) |
f64 | truncToInt floorToInt ceilToInt | i64 |
f64 | isNaN isFinite isInfinite | bool |
f32 | the whole f64 list above, at the narrower width | f32, or i64 / bool where f64 gives those |
i32 | abs absChecked min max | i32 |
i32 | toHex toBin toOct | string |
i64 | abs absChecked min max | i64 |
i64 | toHex toBin | string |
u8 u16 u32 u64 | min max toHex toBin | same width, or string |
every numeric and bool type | toString | string |
absChecked throws ArithmeticException on the minimum value of its type,
because -x would overflow there. round and the three *ToInt methods
narrow through a saturating conversion, so an out-of-range magnitude clamps
and NaN maps to 0. The result is total.
min and max on f64 return the second argument when either operand is NaN, because the comparison used for the choice is false in that case. The
two argument orders are therefore not interchangeable.
The string receiver has the four numeric conversions below. Each raises ParseException on text that is not a number. The full string surface
(about thirty methods such as charAt, substring, trim, replace and padStart) is on the std/text page.
| Receiver | Methods | Raises |
|---|---|---|
string | toI32 toI64 toF64 toBool | ParseException |
What is not a method lives in std::numeric::math as a free function,
because it takes no natural receiver: the constants math::pi(), math::e(), math::tau(); the two-argument math::atan2(y, x) and math::hypot(x, y); and the type bounds math::i32Min(), math::i32Max(), math::i64Min(), math::i64Max(), math::f64PositiveInfinity(), math::f64NegativeInfinity(), math::f64NotANumber().
Two traps with a literal receiver.
A numeric literal needs parentheses before a method —
(1.0).sqrt(), not1.0.sqrt(), which lexes as a malformed number.The receiver’s type chooses the row of the method table, and so the width of the result. An untyped integer literal receiver is
i32, so(1).max(x)answersi32. Type the receiver when you mean 64 bits —(1 as i64).max(bigI64).
Short module paths
A nested module also answers to a flat short spelling. The compiler does
not keep a table of these pairs: a written std::<stem> resolves to the one
module under std/ whose last segment is <stem>. When two modules share
a stem, the short spelling resolves to nothing and the compiler reports it
as an unresolved name, so you write the full path instead.
| Short | Full path |
|---|---|
use std::math; | use std::numeric::math; |
use std::random; | use std::numeric::random; |
use std::process; | use std::sys::process; |
use std::env; | use std::sys::env; |
use std::sysinfo; | use std::sys::sysinfo; |
use std::cli; | use std::sys::cli; |
use std::log; | use std::system::log; |
use std::regex; | use std::text::regex; |
use std::boxing; | use std::text::boxing; |
use std::util; | use std::core::util; |
use std::path; | use std::io::path; |
The short name never changes a symbol’s linked name, because the linked name is keyed on the module’s own file name.
Module map
| Module | Purpose | Recipe |
|---|---|---|
std/core | Tiny pure helpers: ascii, bits, bytes, checks, util (including Pair<A, B>, Optional<T> and OptionalCell<T>) | — |
std/lang | The exception class hierarchy (Exception, RuntimeException, IOException, …), auto-imported. (Console is a separate prelude class from the runtime, not this module.) | Error handling |
std/collections | ArrayList<T>, HashSet<T>, HashMap<K,V> (any monomorphisable element type; f64 is refused as a HashSet element or HashMap key) | Collections |
std/numeric | math constants and free functions, Random PRNG, ieee (IEEE-754 classification read from the bit encoding) | Numeric and time |
std/text | String utilities, plus json, csv, url, regex, uuid, hashing, checksum, encoding, escape, version, boxing | Strings and text |
std/io | File I/O (io) and path manipulation (path) | Files and I/O |
std/net | TCP sockets (net), HTTP client (http), DNS resolution (dns), TLS (tls) | — |
std/time | Time (time) and calendar date-time (datetime) | Numeric and time |
std/sys | Clocks, exit and sleep, OS info, and the process, env, sysinfo and cli submodules | CLI tools and system |
std/system/log | Levelled logging (log::setLevel(LogLevel::INFO)) | CLI tools and system |
std/concurrent | Thread, Async, locks (ReentrantLock, ReadWriteLock), channels, atomics (AtomicI32, AtomicI64, AtomicBoolean), CountDownLatch, Semaphore | Concurrency primitives |
std/ffi | C interop bindings: libc (mem, cstr, fs, proc), libm (sqrt and the other math functions), and runtime | FFI |
API reference
The auto-generated API reference lists
every public class, trait, and free function in the stdlib
with the exact signature lifted from the source. Each entry
carries the parsed @param / @return / @throws tags exactly
as written above the declaration.
The reference is regenerated on every documentation build, so it
always matches the stdlib that shipped with your axle binary.
Limits / Uncabled
| Feature | State | Detail or workaround |
|---|---|---|
Auto-import of collections, streams, Pattern, LocalDateTime, Path | Not in the prelude. | Add an explicit use for each. |
| Mixing a short spelling and the full path of the same module | Both name the same module, so either works in one file. | Pick one spelling per file for readability. |
| The reference reflects the shipped stdlib | It carries the signatures of the binary you have, not of a newer release. | Regenerate the documentation from the release you use. |
See also
- Language tour → Modules and imports —
usesyntax. - Conventions → Modules and use — one-symbol-per-line style.
- Recipes — every module above has at least one recipe showing its idiomatic usage pattern.
- Concept index — every stdlib topic cross-linked to its recipe and reference page.