Axle v0.22.0

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 example log::setLevel, which takes a LogLevel), add a second use for 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 no use.

    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 Console is not a duplicate — its class is the one its references mean. A name the library needs for itself is the exception: ProcessBuilder names Process, and a name an explicit use brought in (use std::collections::HashMap; beside class HashMap) cannot be declared again.

  • Handle-backed classes — a class wrapping a native resource behind a single handle : i64 field: file streams, Pattern, Process, the net sockets. Most are constructed directly with new 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 (Process comes from ProcessBuilder.start() and has no constructor of its own). Whichever way you obtain one, each satisfies the Closeable contract, so you pair the open with defer close() and the handle is released on every exit path (a Closeable type with no registered teardown, such as a user-defined resource class, is checked by E0511; stdlib handles such as Pattern are 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 ! IOException in its signature. A real program therefore either declares the set onward (fn main() : i32 ! IOException) or wraps the work in try { … } 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 functionbind the module, call through mod::
Class::method(args), nothing constructedfaçade (static-only class)call through ::; the prelude ones (Console, Random, …) need no use
new Class(args) then .method(…)instance classnew 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.

KindNames
ClassesConsole, Random, Async, ProcessBuilder, Process, Float, Char, String
Exception hierarchyException, RuntimeException, IOException, FileNotFoundException, ParseException, IllegalArgumentException, IllegalStateException, IndexOutOfBoundsException, and the rest of the family in std/lang
Free functionsexit, sleep, now, nanoTime (from std::sys); argc, hasEnv, pid, parentPid (from std::sys::process)
Built-in print functionsprint, 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:

ReceiverMethodsResult type
f64sqrt pow cbrt exp ln log2 log10 sin cos tan asin acos atan sinh cosh tanh floor ceil trunc abs sign min maxf64
f64roundi64 (half away from zero)
f64truncToInt floorToInt ceilToInti64
f64isNaN isFinite isInfinitebool
f32the whole f64 list above, at the narrower widthf32, or i64 / bool where f64 gives those
i32abs absChecked min maxi32
i32toHex toBin toOctstring
i64abs absChecked min maxi64
i64toHex toBinstring
u8 u16 u32 u64min max toHex toBinsame width, or string
every numeric and bool typetoStringstring

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.

ReceiverMethodsRaises
stringtoI32 toI64 toF64 toBoolParseException

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(), not 1.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) answers i32. 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.

ShortFull 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

ModulePurposeRecipe
std/coreTiny pure helpers: ascii, bits, bytes, checks, util (including Pair<A, B>, Optional<T> and OptionalCell<T>)—
std/langThe exception class hierarchy (Exception, RuntimeException, IOException, …), auto-imported. (Console is a separate prelude class from the runtime, not this module.)Error handling
std/collectionsArrayList<T>, HashSet<T>, HashMap<K,V> (any monomorphisable element type; f64 is refused as a HashSet element or HashMap key)Collections
std/numericmath constants and free functions, Random PRNG, ieee (IEEE-754 classification read from the bit encoding)Numeric and time
std/textString utilities, plus json, csv, url, regex, uuid, hashing, checksum, encoding, escape, version, boxingStrings and text
std/ioFile I/O (io) and path manipulation (path)Files and I/O
std/netTCP sockets (net), HTTP client (http), DNS resolution (dns), TLS (tls)—
std/timeTime (time) and calendar date-time (datetime)Numeric and time
std/sysClocks, exit and sleep, OS info, and the process, env, sysinfo and cli submodulesCLI tools and system
std/system/logLevelled logging (log::setLevel(LogLevel::INFO))CLI tools and system
std/concurrentThread, Async, locks (ReentrantLock, ReadWriteLock), channels, atomics (AtomicI32, AtomicI64, AtomicBoolean), CountDownLatch, SemaphoreConcurrency primitives
std/ffiC interop bindings: libc (mem, cstr, fs, proc), libm (sqrt and the other math functions), and runtimeFFI

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

FeatureStateDetail or workaround
Auto-import of collections, streams, Pattern, LocalDateTime, PathNot in the prelude.Add an explicit use for each.
Mixing a short spelling and the full path of the same moduleBoth name the same module, so either works in one file.Pick one spelling per file for readability.
The reference reflects the shipped stdlibIt carries the signatures of the binary you have, not of a newer release.Regenerate the documentation from the release you use.

See also

stdlibstandard-librarymodules