AlphaGitHub
explanationView source

The standard library#

The standard library is the foundation-standard package under packages/foundation/standard/src. It is ordinary Alpha source, checked like everything else, and it has three namespaces:

NamespaceModulesHolds
Std.*34, six of them under Std.Numeric.*The core data types, naturals, lists, maps, bytes, words, floats, text, effects and testing
Data.*47Byte strings and codecs: UTF-8, JSON, SHA-256, LEB128, Protobuf, Parquet, Snappy, tokenizers, bfloat16
Model.*5Machine words: Model.Config, Model.Parameter, Model.Word32, Model.Word32Logic, Model.Word64

Beyond the language's built-in families (such as Nat and Bytes) there is no prelude. A module imports what it uses, and it must import directly the module that owns every family named in its signatures; a family reached only through another import is not in scope. The source browser shows every module with resolved links.

The core types: Std.Foundation#

FamilyConstructors and use
StdBoolBooleans as data
StdOptionStdNone / StdSome; stdOptionValueOr supplies a default
StdResultSuccess or failure with a reason; stdResultBind sequences results
StdPairTwo values
StdOrderThe result of a comparison

Alpha has no primitive if. Decisions are made by eliminating data: a StdBool, a StdOption, or a natural number. Families and branches shows the pattern.

Naturals: Std.Natural#

Natural numbers are the language's built-in Nat, and Std.Natural gives the arithmetic: naturalAdd, naturalLess, naturalDivide (returning a NaturalDivideResult), and naturalSelect, which chooses between two values by a natural (zero selects the second, the false branch). In the alpha-2027 edition, literals such as 21 and the compile-time forms nat-add, nat-subtract, nat-multiply, nat-divide and nat-modulo are part of the language itself; see Language forms.

Collections: Std.List, Std.Map#

  • StdList with StdListEmpty and StdListCons; stdListMap, stdListFold and stdListAppend.
  • StdMap and StdSet; stdMapInsert and stdMapLookup.

Bytes, words and floats#

ModuleHolds
Std.ByteByte arithmetic and bit operations: byteAdd, byteXor, byteShiftRight
Std.WordFixed-width integers (U8, U32, U64 and signed StdI8 … StdI64) with explicit overflow: stdU64AddWrapping wraps and stdU64AddChecked fails
Std.FloatIEEE-754 binary32 (F32) and binary64 (F64): stdF32IsNaN, stdI32ToF32
Data.Float32BitsThe binary32 bit pattern (InferenceFloat32): inferenceFloat32Finite, dataFloat32EncodeLE
Model.Word6464-bit machine words: modelWord64Add, modelWord64AddChecked
Std.Numeric.*Exponential, logarithm, trigonometric and other numeric functions

Floating-point values are exact bit patterns, so a numerical claim can be checked to the bit: proof roots compare F32 results as natural-number bit patterns.

Byte strings and codecs: Data.*#

Data.Bytes holds slices and builders (DataBytesSlice, DataBytesBuilder), fixed-width reads such as dataBytesReadWord32LE, and dataBytesRenderHex. The rest of Data.* are codecs written in Alpha: Data.UTF8, Data.JSON*, Data.SHA256*, Data.LEB128, Data.Protobuf, Data.Parquet*, Data.Snappy, Data.SentencePiece*, Data.ByteBPE* and Data.BFloat16. Systems decode their inputs with them, in Alpha and with no foreign library: Coppelius builds its token cache through them, and Vathek reads a SentencePiece model.

Text, effects and the system#

  • Std.Text: validated UTF-8 (StdText, stdTextDecodeUtf8). The alpha-2027 edition adds text and byte literals, "…" and b"…".
  • Std.Effect: explicit effect interfaces. An effect is in the type: a computation that reads a file has File in its effect row, sequencing keeps it there, and the do form of alpha-2027 sequences steps explicitly.
  • Std.System: descriptions of system calls (number, arguments, answer, and the effect a program needs to make one).
  • Std.Path: a path is a list of segments, not a string with separators hidden inside it, so joining is total and unambiguous.
  • Std.Region: regions, arenas and the lifetimes of linear buffers.
  • Std.Physical: refined values for the roles that are routinely confused at safety and ABI boundaries.

Testing: Std.Testing, Std.TestProtocol#

Suites written in Alpha use stdTestPass, assertions such as stdAssertNaturalEqual, and properties (StdProperty). The declared suite runs them; see Tests, gates and CI.

Beyond the standard library#

Other foundation and domain packages sit beside it: foundation-language (the error and exact-numeric vocabulary), representations (hardware-free parameter, schema and storage types), components (hardware-free mechanisms such as random-number generation and matrix multiplication), learning (objectives and learner mechanisms) and execution-persistence (Checkpoint.*). Workspace and packages describes how packages are declared and pinned.

  • Language guide: the syntax and semantics the library is written in.
  • Language forms: every surface form and its contract.
  • Source: every module, with resolved links.