The standard library

The standard library is a set of packages owned by std: std/core, std/text, std/collections and the rest. They come with the toolchain and have its version, so none of them needs an entry in dependencies.

The prelude (std/prelude) is a package of re-exports whose public names are in scope in every file. It holds the pure part of the library - values, text, numbers, collections, pipelines, encoding, quotations, tasks, printing, mathematics, JSON and the time values. What a program can touch is deliberately not in it: std/fs, std/io, std/process, std/os, std/http, std/sandbox and Clock stay explicit imports, so that use File from "std/fs" at the top of a file is the statement "this file touches files".

What belongs here#

One page per package: what it is for, how it is imported, and every public declaration with its doc comment. The signature blocks of each page's ## Declarations section are generated from the sources by torb docs declarations, and the prose around them is written by hand; the reference with every doc comment of a package is what torb doc std writes. One reference page stands beside them, for the three closure aliases every package's signatures use.

What does not belong here: the language rules that a type participates in, which are in the language reference, and the argument for a design decision, which is in explanation. A page here says what a package contains.

Core values#

• std/core - The bottom of the standard library: Option, Result, Error, the operator and conversion traits, and the control structures that are functions.
• Predicate, Action and Transform - Three aliases in the prelude for the closure shapes signatures take most - a question about one value, an effect on one value, and a conversion of one value into another.
• std/text - Char, a Unicode scalar value, and String, always-valid UTF-8 text with no length() and no indexing by character.
• std/number - Every numeric type of the language, the traits their arithmetic and bit operations go through, Real, and ByteSize.
• std/collections - The collection traits every signature talks about, and the implementations that only show up where one is built.
• std/iteration - Iterate and Iterator, the lazy stages between them, and the collectors a pipeline ends in.
• std/console - print and printError, the two functions that write to the standard streams.
• std/ecs - The data layer of the entity-component system - Entity and its allocator, dense Column storage, the Store trait that lets a system name a component without knowing the world, queries of one to four components, the parent hierarchy, Events.
• std/prelude - The package of re-exports that is in scope in every file of a project, unless project.trb names another one.

Data formats#

• std/encoding - Encode, Decode and Describe, the traits a format implements, EncodedValue and Structure, Format for streaming, and RFC 4648's Base64, Base32 and hexadecimal for bytes as text (hexEncoded(), hexDecoded(), base64Decoded() methods).
• std/json - Json, a value with the options of the format, for encoding and decoding any Encode/Decode type, and JsonValue for the rare document whose shape is not known ahead of time.
• std/yaml - Yaml reads and writes any Encode/Decode type as YAML 1.2 or 1.1, with the target type resolving every scalar, and YamlNode is the tree of a document with its anchors, tags, styles and comments.
• std/regex - Regex, a compiled pattern with the syntax and the linear-time semantics of RE2, with whole and partial matches, named groups that decode into a type, replace and split.
• std/markdown - Markdown reads CommonMark with GitHub's tables and front matter into a document tree that is a value, with the lines of every block and link; HTML and Markdown are written from the tree.
• std/toml - Toml reads and writes any Encode/Decode type as TOML 1.0 or 1.1, and TomlValue is the tree of a document, with date and time values that keep their nanoseconds and their offset.
• std/xml - Xml reads XML 1.0 with namespaces into a tree of XmlNode values and writes it back; it expands the entities and applies the attribute defaults of an internal subset, never fetches an external one, and an XmlError has a line and a column.
• std/html - Html and Markup write HTML with every text and attribute value escaped where it is written, and HtmlTokenizer reads HTML as the WHATWG standard tokenizes it into HtmlToken values; reading never fails.
• std/json-schema - JsonSchema reads a JSON Schema of draft 2020-12 and validates a JsonValue against its in-place keywords, with one ValidationError per failed keyword and its place as a JSON Pointer; what it cannot check yet is refused by name.
• std/binary - ByteReader, ByteWriter, BitReader and BitWriter - numbers of every width in either byte order, IEEE 754 floats, LEB128, runs of bytes and text, read with a ReadError instead of a panic and written into a growable buffer.
• std/compression - DEFLATE, gzip, Snappy and LZ4 blocks in TorbScript, as methods of Bytes - inflated() and gunzipped() read every stream, deflated() and gzipped() write deterministic output, snappyCompressed() and lz4BlockCompressed() write the fast formats.
• std/archive - tar archives, as methods of lists - bytes.untarred() reads what GNU tar, bsdtar and pax write, with modes and links; entries.tarred() writes ustar and pax; entries.extract() of std/archive/extract unpacks safely.

Time, randomness and maths#

• std/linear - Vectors, matrices, quaternions and angles over one generic scalar, plus Fixed, the fixed-point scalar whose answers are the same bits everywhere.
• std/geometry - The shapes of the plane and of space, with the half-open rule that makes a row of rectangles a tiling and the ray tests that answer a distance.
• std/time - Instant, Duration and Timestamp, Date, Weekday, TimeOfDay, DateTime, UtcOffset and OffsetDateTime for the wall clock, RFC 3339, HTTP date and compact ISO 8601 text, plus Clock and sleep, which read the two clocks.
• std/random - Random, a seedable and splittable SplitMix64 generator that is a value - the same seed makes the same numbers on every machine, with integers of a range, floats, shuffling, choice, sampling and independent splits.

Concurrency#

• std/task - Task and Channel, the two shared types that connect concurrent work, spawn, cancellation with Cancelled and TimedOut, pause, Permits, a semaphore for tasks, and Pool, a pool of resources over it.
• std/parallel - parallel() on anything that can be iterated, Parallel, a fused pipeline on the workers of the pool with the results in input order, Cut, the collections that cut themselves, and windows, which writes one list in place on every worker.
• std/stream - Source and Sink, the asynchronous ends of a stream, plus Bytes, Utf8Error, the stages between bytes and text, and Reader, which reads a protocol's runs of bytes, lines and frames off a byte stream.

Files and the OS#

• std/path - Path, a root and a list of components, never a string, plus Root and PathError - the type behind Path.resolved.
• std/fs - File and IoError - whole files as text or bytes, a File as both ends of a byte stream, and the tree around them - remove, rename, move, copy, metadata, links, temporary files and atomic replacement.
• std/resource - Resource, EmbeddedBytes, EmbeddedText and ResourceError - a file of the package named by a string literal, resolved by the compiler where it is written; a Resource is read from beside the program, an EmbeddedText from the binary.
• std/storage - Storage, a capability over a Uri whose scheme chooses the driver - FileStorage for files, MemoryStorage for tests - and Storage.registry, one storage over the drivers a program names.
• std/io - Standard input and the streams every process is started with - readLine for the short form, Source and Sink for the rest.
• std/process - Process for arguments, exiting and running a program to its end as a task, Child for a running program's pipes, and ProcessOutput for what it left behind.
• std/cli - A program with several commands, flags, options and positional arguments, declared once as a builder - the help text and the errors are generated from it, and parsing runs over a list of strings, so a test needs no process.
• std/os (draft) - Environment, System, Memory, Processor, Volume, CurrentProcess, Directories, User, Entropy, MacAddress and NetworkInterface - the machine the program runs on - and OsError.
• std/sandbox - Sandbox and Script, which load a .trb file as a type-checked, capability-limited receiver closure.

Network#

• std/uri - Uri and UriReference after RFC 3986, normalized at construction, with IRIs, Urn, DataUri, UriTemplate, the file bridge to Path and the form codec of HTML - values that open nothing.
• std/identifier - Uuid (RFC 9562, versions 4 and 7), Ulid and the trait Identifier - made from a Random and a Timestamp that are arguments, so the package has no capability, read back with one IdentifierError and bridged to urn:uuid of std/uri.
• std/ip - IPv4, IPv6, socket addresses and subnets as values, read from text and shown as text, with no natives and no capability - std/network and std/uri both use them.
• std/dns - Domain names with IDNA and the comparison of RFC 4343, DNS records as typed cases, and the RFC 1035 wire format with compression and EDNS0 - values with no natives and no capability, for the transports of std/network and std/http.
• std/network - Name resolution and DNS lookups, TCP - a listener, and a stream whose two directions are a Source and a Sink of Bytes - UDP datagrams and Unix domain sockets, over the address values of std/ip, which it re-exports.
• std/tls - TLS 1.2 and 1.3 over a TcpStream - a client that checks the server's certificate the way the platform does, a server with an identity, a stream like the TCP one, and DNS over TLS.
• std/http - HTTP/1.1 and HTTPS, client and server, over std/network and std/tls - get, post and send answer a Task, a handler answers a Task of a Response, and every body is a stream.

Crypto#

• std/digest - Sha256, Sha512, Sha1 and Md5 and the Digest they answer, Hmac (RFC 2104) and PBKDF2 (RFC 8018) over any of them - fed at once or in pieces, shown as lowercase hexadecimal, compared in constant time.
• std/signature - Ed25519 of RFC 8032 and ECDSA verification over P-256 (ES256) in TorbScript - an Ed25519 private key from a 32-byte seed signs, public keys verify, and keys and signatures read and write themselves as bytes and hexadecimal.
• std/cipher - ChaCha20-Poly1305 of RFC 8439 in TorbScript - an authenticated cipher with a 32-byte key that seals a message with a 12-byte nonce and associated data, and opens it only if nothing was changed.

Toolchain-facing#

• std/expression - Expression and ExpressionNode, the typed tree a quoted parameter hands over, plus assert and nameOf.
• std/test - test and group, the two functions a .test.trb file calls, with assert doing all of the checking.
• std/project - The receiver type of project.trb - Project, Dependencies, Program, ScriptFamily, Profile, Test, Tasks, Workspace, Registry and Source.