Topazdocs
Standard Library & Runtime

Standard Library Overview

Select the standard library capability suited for a given task and its failure model.

Start with the task rather than the API inventory. The standard library provides programs with a minimal checked surface covering values, collections, files, and host boundaries. Unrecognized names and members trigger checking errors rather than falling through to host-language methods.

Choose a capability

What you need to doStart hereFailure shape
Print text, convert a value, inspect Unicode, or transform valuesCore LibraryA value, Option, or the helper's declared Result
Store ordered items, look up a key, or keep unique valuesCollection OperationsUsually a value, bool, or Option
Read or write one whole fileFS.readText, FS.writeText, FS.readBytes, or FS.writeBytesResult
Hold a file open across several operationsopen with using or deferResult, followed by lexical cleanup
Understand printing, numbers, order, or a runtime stopRuntime BehaviorA documented value or a loud fault

Choose Array for ordered elements, Map for key-value lookups, and Set for unique values.

Use Option when absence is an expected outcome, such as a missing map key. Use Result when external input or host effects can fail with a descriptive reason. A fault indicates that the running program violated a contract, whereas an invalid call or type is rejected statically.

An everyday recipe

This program parses text and transforms an array. toInt uses Option because input text might not contain an integer. map returns a new array preserving the input order.

TOPAZ
let parsed: Option<int> = toInt("42")
let values: Array<int> = Array.of(1, 2, 3)
let doubled = map(values, value => value * 2)

print("{parsed}:{doubled}")
Output
Some(42):[2, 4, 6]

Some(42) keeps the successful parse explicit. If the text does not represent an integer, the first part evaluates to None. The library does not substitute default values like 0 or raise catchable exceptions.

How the surface is organized

Prelude functions and constructors including print, toInt, Some, None, Ok, Err, map, filter, and reduce require no imports. Built-in namespaces encompass focused module families such as Math, Bytes, Hash, FS, and Path. Package code may also reference the fixed std.* modules documented by the active toolchain. These represent checked exports rather than dynamic host namespaces.

The broader API surface covers encodings, hashes, paths, command-line parsing, regular expressions, CSV, TOML, JSON, URLs, dates, large integers, decimals, generators, parsers, and bounded host capabilities. Open the focused page for exact signatures and target boundaries rather than assuming a similarly named host API exists.

Common correction: Importing a standard module does not grant filesystem, network, process, environment, clock, or database authority. Host effects function only in profiles and environments that provide the corresponding capability.

Exact boundaries

  • String indexing uses Unicode scalar values unless an API explicitly specifies bytes.
  • Collection iteration and snapshots preserve their documented order.
  • Parsing and decoding preserve their declared Option or Result failure.
  • Invalid arithmetic operations and contract violations remain loud.
  • Test.*, free assert, and std.test are restricted to the test profile.
  • Unknown direct names, virtual modules, and members produce static diagnostics.

Continue by task