The standard library

Thirty-six modules, all written in Wolang over a floor of about sixty C calls. This is what each one is for, what it gives you, and what it does not.

Last updated Invalid DateVersion 1.0.0

Thirty-six modules, all written in Wolang over a floor of about sixty C calls. This is what each one is for, what it gives you, and what it does not. Every example here compiles.

A length, an index and a hash are int, which is s64 (D238): .len on a text, slice or list is an int, and a collection is not capped at 2^31.

How to read a signature: uses unsafe on a standard library function means it takes the responsibility, not you — std.math.Sqrt-style wrappers over a C call. std.text.Bytes hands out a []u8 view of text that may be a literal, which cannot be written through (D251), so it needs no promise from the caller.

ModuleWhat it is for
std.textStrings: searching, slicing, splitting, building
std.fmtNumbers as text, in bases, columns and units
std.utf8Characters rather than bytes
std.regexPatterns, with groups and replacement
std.mathThe usual functions, and the wrapping ones
std.listA growing sequence, and what to do to one
std.map, std.setHashed lookups
std.deque, std.heapA queue at both ends, and a priority queue
std.sortSorting and binary search
std.docWhat a document is, whatever it was written in
std.json, std.toml, std.yaml, std.ini, std.csvFive formats, one tree
std.ioStandard input, output and error
std.fsFiles, directories and trees
std.pathJoining and taking paths apart
std.netSockets, and names
std.processRunning another program
std.envThe environment and the command line
std.timeMoments, calendars, zones and durations
std.cryptoHashes, signatures, randomness, identifiers
std.compressDeflate, gzip and CRC-32
std.encodingBase64, hex and URL escaping
std.hashFast hashing for tables
std.randomA generator you can repeat
std.logLevelled logging
std.thread, std.tasksThreads, locks, and a frame's worth of parallel work
std.mem, std.ownStorage, views and ownership
std.arenaA bump allocator freed as one
std.opsOperators as abilities: Add, Eq, Ord and the rest
std.iterWhat being walked means: Iterator and Iterable

| std.save | Save games: the @Save fields of an object graph, written and read back |

And first-party packages beside it: http, db, gfx, image, math, plus tls and game.


std.text

Searching, slicing, splitting, joining, padding, parsing.

wolang
need std.io.{Print}
need std.text.{BuilderNew, Contains, Join, PadStart, Pieces, Replace,
               Split, Substring, Trim, Upper}

fun main() uses io, unsafe {
  const line = "  wolang,fast,typed  "
  const held = Trim(line)
  Print(Upper(Substring(held, 0, 6)))        // WOLANG
  Print("{Contains(held, "fast")}")          // true
  Print(Replace(held, ",", " / "))           // wolang / fast / typed
  Print(PadStart("7", 3, "0"))               // 007

  // Splitting walks rather than allocating a list.
  for piece in Pieces(held, ",") {
    Print("piece: {piece}")
  }

  // Building a string is a builder, which grows once rather than
  // copying per `+`.
  var builder = BuilderNew()
  var i = 0
  while i < 3 {
    builder.Append("{i} ")
    i = i + 1
  }
  Print(builder.Release())                   // 0 1 2
}

builder.Text() is a view of the builder's own bytes, valid only until the next Append, Reserve or Clear and until the builder dies; returning it from the function that owns the builder dangles. Release() is the owning form: use it for any string that outlives the builder (D227).

Length, IsEmpty, StartsWith, EndsWith, IndexOf, LastIndexOf, After, Before, TrimStart, TrimEnd, CountPieces, PieceAt, Repeat, PadEnd, Lower, ParseInt, ParseFloat, Bytes, TextFromRaw.

A text is bytes and a length. There is no copy on a substring and no terminator; Bytes (a read-only []u8) hands you the bytes and TextFromRaw takes them back.

std.fmt

wolang
need std.fmt.{Binary, Bytes, Duration, Float, Hex, Left, Percent,
              Right}
need std.io.{Print}

fun main() uses io, unsafe {
  Print(Hex(48879))             // beef
  Print(Binary(10))             // 1010
  Print(Float(3.14159, 2))      // 3.14
  Print(Bytes(1536))            // 1.5 KB
  Print(Duration(90000))        // 1m 30s
  Print(Percent(0.42, 1))       // 42.0%
  Print(Left("name", 12) + Right("42", 6))
}

std.utf8

Bytes are not characters. This module is where that distinction lives.

wolang
need std.io.{Print}
need std.utf8.{CharAt, Count, Encode, IsValid, Walk}

fun main() uses io, unsafe {
  const held = "привет"
  Print("{Count(held)} characters, {held.len} bytes")   // 6, 12
  Print("{IsValid(held)}")
  // `Walk` yields code points; `CharAt` gives the whole thing -- the
  // point, where it starts and how wide it is.
  for code in Walk(held) {
    Print("{code}")
  }
  const first = CharAt(held, 0)
  Print("the first is {first.code}, {first.width} bytes wide")
  Print(Encode(0x1F600))         // 😀
}

std.regex

A backtracking matcher with a budget: the famous exponential patterns answer "no" rather than never answering. Compile answers BadPattern for what would blow up: groups nested more than 32 deep, a repeat count over 1000, or a program over 20000 steps (D227).

wolang
need std.io.{Print}
need std.regex.{Compile, Find, FindAll, Group, Matches, ReplaceAll,
                Split, Whole}

fun main() uses io, unsafe {
  match Compile("(\\w+)@(\\w+)\\.com", "i") {
    Ok(pattern) => {
      const line = "write to [email protected] today"
      const found = Find(&pattern, line)
      Print(Whole(line, &found))          // [email protected]
      Print(Group(line, &found, 1))       // Someone
      Print(ReplaceAll(&pattern, line, "<$1>"))
      Print("{Matches(&pattern, "nothing here")}")   // false
    },
    BadPattern => { Print("not a pattern") },
  }
}

Supported: literals, ., classes with ranges and negation, \d \w \s and their capitals, ^ $ \b \B, groups and non-capturing groups, alternation, * + ? {n} {n,} {n,m} and their reluctant forms, the flags i and s. Not supported: look-around and back-references.

std.math

wolang
need std.io.{Print}
need std.math.{Clamp, Lerp, Max, Near, Pi, Sqrt, WrappingAdd}

fun main() uses io, unsafe {
  Print("{Sqrt(2.0)}")
  Print("{Clamp(17, 0, 10)}")          // 10
  Print("{Lerp(0.0, 10.0, 0.25)}")     // 2.5
  Print("{Near(0.1 + 0.2, 0.3, 1e-9)}")
  // Every operator traps on overflow; these are how you ask for the
  // other behaviour on purpose.
  Print("{WrappingAdd(18446744073709551615, 1)}")   // 0
}

std.iter

What being walked means, as two abilities: Iterator hands out values (type Item, Next, Value) and Iterable hands out an iterator (type Walker: Iterator, Iterate). List, Deque, Map, Split and Chars implement both, so generic code over C: Iterable walks any of them. Count(items) and Collect(items) are written that way.

std.list

wolang
need std.io.{Print}
need std.list.{Any, Count, Fold, Keep, ListNew, MapInPlace}

fun main() uses io, unsafe {
  var list = ListNew<int>()
  var i = 1
  while i <= 6 {
    list.Push(i)
    i = i + 1
  }
  const items = list.Items()      // a view, not a copy
  const limit = 3
  Print("{Any(items, |x| x > limit)}")              // true
  Print("{Count(items, |x| x % 2 == 0)}")           // 3
  Print("{Fold(items, 0, |total, x| total + x)}")   // 21
  MapInPlace(items, |x| x * 10)
  const kept = Keep(items, |x| x > 30)              // moves them to the front
  Print("{kept} left")
}

A closure captures by copy, so limit travels with it.

Items() is a view into the list's storage, valid only until the list next grows (Push, Reserve) or dies. Read it after the last mutation; a view kept across a Push reads freed memory (D227).

std.map

A map needs to know how to hash a key and how to compare two:

wolang
need std.hash.{TextEquals, TextHash}
need std.io.{Print}
need std.map.{MapNew}

fun main() uses io, unsafe {
  var counts = MapNew<text, int>(TextHash, TextEquals)
  counts.Put("wolf", 1)
  // `Get` takes what to answer when the key is not there, so a lookup
  // is one call rather than a lookup and a test.
  counts.Put("wolf", counts.Get("wolf", 0) + 1)
  Print("{counts.Get("wolf", 0)}")      // 2
  Print("{counts.Has("other")}")        // false
  Print("{counts.Len()} keys")
}

std.map.IntHash/IntEquals are there for integer keys. IntMapNew<V>() and TextMapNew<V>() build a map with the hashing already chosen.

std.text.Builder also has AppendLine(value): the text and a newline.

std.set

The same, holding keys only: SetNew<T>(hash, equals), then Add, Has, Remove, Len on it.

std.deque

Pushing and popping at both ends, which is what a queue and a stack both want: DequeNew<T>(), then PushBack, PushFront, PopBack, PopFront, At, Len.

std.heap

A binary heap, for "what is the smallest thing left": HeapNew<T>(before), then Push, Pop, Peek, Len.

std.sort

wolang
need std.io.{Print}
need std.list.{ListNew}
need std.sort.{Contains, LowerBound, Sort}

fun main() uses io, unsafe {
  var list = ListNew<int>()
  list.Push(5)
  list.Push(1)
  list.Push(4)
  const items = list.Items()
  // The order is a closure, so the same sort works for anything.
  Sort(items, |a, b| a < b)
  Print("{items[0]} {items[1]} {items[2]}")        // 1 4 5
  Print("{LowerBound(items, 4, |a, b| a < b)}")    // 1
  Print("{Contains(items, 9, |a, b| a < b)}")      // false
}

std.doc

One value type for every format: a nothing, a truth, a number, some text, a list and a table.

wolang
need std.doc.{AsInt, AsText, Get, Null, Object, OfInt, OfText, Put}
need std.io.{Print}

fun main() uses io, unsafe {
  var server = Object()
  server = Put(server, "host", OfText("example.com"))
  server = Put(server, "port", OfInt(443))
  var root = Object()
  root = Put(root, "server", server)

  // One path syntax for every format: names walk into tables, numbers
  // walk into lists.
  Print(AsText(Get(root, "server.host") ?? Null(), ""))
  Print("{AsInt(Get(root, "server.port") ?? Null(), 0)}")
}

Kind, Member, At, Len, NameAt, ValueAt, AsNumber, AsBool, IsNull, Array, Push, Number, OfBool.

std.json

wolang
need std.doc.{AsText, Member, Null}
need std.io.{Print}
need std.json.{Parse, Write}

fun main() uses io, unsafe {
  match Parse("\{\"name\": \"wolang\", \"stars\": 42\}") {
    Ok(value) => {
      Print(AsText(Member(value, "name") ?? Null(), ""))
      Print(Write(value))
    },
    Malformed => { Print("not json") },
  }
}

Arrays and objects nested more than 128 deep answer Malformed rather than exhausting the stack (D227).

std.toml

TOML 1.0 as it is used: strings in four styles, numbers in four bases, booleans, dates as text, arrays, inline tables, dotted keys, [table] and [[array of tables]]. Arrays and inline tables nested deeper than 64 answer Malformed instead of exhausting the stack (D227). Malformed carries the line and column the document went wrong at, counted from one, in json, toml and yaml (D235): Malformed(line, column) => ...

wolang
need std.doc.{AsText, Get, Null}
need std.io.{Print}
need std.toml.{Parse}

fun main() uses io, unsafe {
  const source = "name = \"wolang\"\n\n[package]\nsource = \"src\"\n"
  match Parse(source) {
    Ok(value) => {
      Print(AsText(Get(value, "package.source") ?? Null(), ""))
    },
    Malformed => { Print("not toml") },
  }
}

std.yaml

YAML 1.2: block and flow collections, every scalar style, block scalars with chomping, anchors and aliases, merge keys, the standard tags, and documents in a stream (ParseAll). Block or flow nesting deeper than 64 answers Malformed instead of exhausting the stack (D227).

wolang
need std.doc.{AsInt, Get, Null}
need std.io.{Print}
need std.yaml.{Parse}

fun main() uses io, unsafe {
  const source = "base: &base\n  port: 80\nlive:\n  <<: *base\n" +
                 "  port: 443\n"
  match Parse(source) {
    Ok(value) => {
      Print("{AsInt(Get(value, "live.port") ?? Null(), 0)}")   // 443
    },
    Malformed => { Print("not yaml") },
  }
}

std.ini

[section], name = value, ; and # comments. Every value is text, because INI has no types and a reader that guessed would turn version = 1.10 into 1.1.

std.csv

RFC 4180: quoted fields, doubled quotes, line breaks inside quotes, and a separator you choose.

wolang
need std.csv.{Named, Read, Write}
need std.doc.{AsText, Member, Null}
need std.io.{Print}

fun main() uses io, unsafe {
  const rows = Read("name,price\nbread,2\n")
  Print(rows.At(1).At(0))                     // bread
  const tables = Named("name,price\nbread,2\n", 44)
  Print(AsText(Member(tables.At(0), "price") ?? Null(), ""))
}

std.io

wolang
need std.io.{OutNew, Print, ReadLine, Warn}

fun main() uses io, unsafe {
  Print("to standard output")
  Warn("to standard error")
  if const line = ReadLine() {
    Print("you said {line}")
  }
  // Buffered, for a program that writes a great deal.
  var out = OutNew()
  var i = 0
  while i < 1000 {
    out.Write("line {i}\n")
    i = i + 1
  }
  out.Flush()
}

std.fs

wolang
need std.fs.{Append, Copy, Exists, MakeDirectory, ReadText, RemoveTree,
             TempName, Walk, WriteText}
need std.io.{Print}

fun main() uses io, unsafe {
  const root = TempName("demo")
  const _made = MakeDirectory(root + "/inner", true)
  const _wrote = WriteText(root + "/inner/one.txt", "hello")
  const _added = Append(root + "/inner/one.txt", " again")
  Print(ReadText(root + "/inner/one.txt", 4096))   // hello again
  const _copied = Copy(root + "/inner/one.txt", root + "/two.txt", true)
  Print(Walk(root))                                 // every path under it
  const _gone = RemoveTree(root)
  Print("{Exists(root)}")                           // false
}

Also Open/Create for a kept-open file, KindOf, SizeOf, ChangedAt, Rename, List, Current, SetCurrent, Home, TempDirectory, Absolute.

std.path

Join, Parent, Name, Stem, Extension, WithExtension, IsAbsolute, Normalize, IsInside — string work, no filesystem. Normalize answers "" for a path with more than 64 parts left after . and .. are worked out; IsInside is false for such a path.

std.net

wolang
need std.io.{Print}
need std.net.{Accept, Connect, Listen, Resolve}

fun main() uses io, net, unsafe {
  if const address = Resolve("example.com") {
    Print("resolved to {address}")
  }
  var socket = Connect("example.com", 80)
  if socket.IsOpen() {
    const _sent = socket.Send("GET / HTTP/1.0\r\n\r\n")
    Print(socket.Receive(256))
    socket.Close()
  }
}

UDP, for game networking (D244). A datagram is one message: it arrives whole or not at all, and a buffer that is too small cuts it and sets truncated.

wolang
need std.io.{Print}
need std.mem.{ArrayNew, Free}
need std.net.{BindUdpOn, ParseAddress}

fun main() uses io, net, unsafe {
  const lo = ParseAddress("127.0.0.1") ?? 0
  var server = BindUdpOn(lo, 0)          // port 0: the system picks
  var client = BindUdpOn(lo, 0)
  const _sent = client.SendTextTo(lo, server.LocalPort(), "ping")
  var buffer = ArrayNew<u8>(512)
  if const got = server.ReceiveFrom(buffer) {
    Print("{got.count} bytes from port {got.port}, cut: {got.truncated}")
  }
  Free(buffer)
  server.SetNonBlocking(true)            // ReceiveFrom now answers null
  client.Close()                         // when nothing is waiting
  server.Close()
}

BindUdp(port) binds every interface; SetBroadcast(true) allows sending to the broadcast address. SendTo takes []u8, answers the bytes sent or -1 (closed, empty, or over 65507 bytes). UdpSocket.fd can be watched by a poller like a TCP descriptor.

std.process

wolang
need std.io.{Print}
need std.process.{CommandNew, Start, StartCommand, StartWith,
                  WithDirectory, WithVariable}

fun main() uses io, unsafe {
  const said = Start("git rev-parse HEAD")
  Print("{said.code}: {said.out}")

  // Something written to its input.
  Print(StartWith("wc -l", "a\nb\nc\n").out)

  // Somewhere to run, and something in its environment.
  var run = CommandNew("sh -c 'pwd; echo $MARK'")
  run = WithDirectory(run, "/tmp")
  run = WithVariable(run, "MARK", "seen")
  Print(StartCommand(run).out)
}

No shell: the command is split on blanks with quoted runs kept whole, and the program is started directly.

std.env

wolang
need std.env.{ArgAt, ArgCount, Get, Lookup, Set}
need std.io.{Print}

fun main() uses io, unsafe {
  Print("{ArgCount()} arguments; the first is {ArgAt(0)}")
  Print(Get("HOME", "nowhere"))
  if const held = Lookup("EDITOR") {
    Print("editor is {held}")
  }
  Set("WOLANG_RAN", "1")
}

std.time

wolang
need std.io.{Print}
need std.time.{Ago, Civil, CivilIn, Elapsed, Iso, IsoInstant, Now,
               ParseIso, WallClock, ZoneOffset}

fun main() uses io, time, unsafe {
  const started = Now()
  const moment = WallClock().seconds
  Print(IsoInstant(moment))                     // 2026-10-15T18:09:23Z
  Print(Iso(CivilIn(moment, "Europe/Kyiv")))    // the same moment, there
  Print("{ZoneOffset(moment, "Europe/Kyiv") / 3600} hours ahead")
  if const parsed = ParseIso("2026-10-15T18:09:23+02:00") {
    Print(Ago(parsed, moment))                  // "3 hours ago"
  }
  Print("{Elapsed(started, Now())} nanoseconds in this program")
}

std.crypto

wolang
need std.crypto.{Hex, Hmac, SameDigest, Sha256Of, Token, Uuid, UuidAt}
need std.io.{Print}
need std.text.{Bytes}

fun main() uses io, rand, unsafe {
  Print(Hex(Sha256Of("abc")))        // ba7816bf...
  const signature = Hmac(Bytes("key"), Bytes("message"))
  Print("{SameDigest(signature, signature)}")
  Print(Uuid())                      // random, version 4
  Print(UuidAt(1792087763000))       // sortable, version 7
  Print(Token(16))                   // 32 hexadecimal characters
}

Randomness comes from the system, not from std.random: a token made from a sequence is a token someone can continue.

std.compress

wolang
need std.compress.{Crc32, Gunzip, Gzip}
need std.io.{Print}
need std.text.{Bytes}

fun main() uses io, unsafe {
  const packed = Gzip(Bytes("hello hello hello hello"))
  Print("{packed.len} bytes")
  match Gunzip(packed) {
    Ok(back) => { Print("{back.len} back") },
    Malformed => { Print("not a stream") },
  }
  Print("{Crc32(Bytes("123456789"))}")   // 3421780262
}

What it writes, the system's gzip reads, and the other way round.

Inflate and Gunzip put no cap on the output, so a hostile stream can expand about a thousandfold. For anything that arrived from outside use InflateLimited(bytes, most) / GunzipLimited(bytes, most): they answer Malformed once the output would pass most bytes (D227).

std.encoding

ToBase64, FromBase64, ToHex, FromHex, ToUrl, FromUrl.

std.hash

OfBytes, OfText, OfInt, Combine, Slot, TextHash, TextEquals — fast hashing for tables, not for signatures.

std.random

wolang
need std.io.{Print}
need std.random.{RandomFromClock, RandomNew}

fun main() uses io, time, unsafe {
  var rng = RandomNew(42)     // the same seed is the same sequence
  Print("{rng.Next() % 6 + 1}")
  Print("{rng.Between(1, 100)}")
  var other = RandomFromClock()
  Print("{other.Next()}")
}

std.log

wolang
need std.log.{Debug, Error, Info, Level, SetLevel, SetTimestamps,
              Trace, Warning}

fun main() uses io, time, unsafe {
  SetLevel(Level.Debug)
  SetTimestamps(true)
  Trace("the finest level, usually off")
  Debug("starting")
  Info("listening on 8080")
  Warning("slow request")
  Error("gave up")
}

std.thread

wolang
need std.io.{Print}
need std.thread.{AtomicAdd, Parallelism, Spawn}

var total: s64 = 0

fun Work() uses unsafe {
  var i = 0
  while i < 1000 {
    const _held = AtomicAdd(&mut total, 1)
    i = i + 1
  }
}

fun main() uses io, unsafe {
  Print("{Parallelism()} cores")
  var worker = Spawn(Work)
  Work()
  const _joined = worker.Join()
  Print("{total}")        // 2000
}

A body started on another thread (Spawn, ParallelFor: the parameters of functions marked @Thread) may not read or write a module-level var, directly or through the functions and methods it calls, in any module, unless the function making the call states uses unsafe (E0147); a function that states it stops the walk (D252), and Spawn takes no capturing closure at all (E0148); ParallelFor's closure may capture, each thread getting a copy (D232). A function the caller holds in a variable cannot be followed, so handing one to a @Thread function is E0163: pass the function by name or as a closure, state uses unsafe, or be a @Thread function that passes on what it was given (D275).

std.tasks

std.thread.ParallelFor(count, body) is a range split across the cores, which is what a frame's worth of work wants. std.tasks is the cooperative side: Run, Done, Pending and Join for spawned tasks.

It is also how code waits on a clock the caller owns (D267). Tick(dt) hands the scheduler dt seconds and gives every task that was ready one step; Wait(seconds) is a task that finishes when that many seconds of ticks have gone by, and Yield finishes on the next tick. Pausing is not ticking and slow motion is a smaller step, so a game needs no hook for its own time.

wolang
need std.io.{Print}
need std.tasks.{Done, Now, Tick, Wait}

class Door {
  var open: bool = false
}

task fun OpenLater(door: Door) {
  wait Wait(2.0)
  door.open = true
}

fun main() uses io, unsafe {
  const door = Door()
  const handle = spawn OpenLater(door)
  var frames = 0
  while !Done(handle) {
    const _steps = Tick(1.0)
    frames = frames + 1
  }
  Print("open after {frames} frames, {Now()} seconds: {door.open}")
}

It prints open after 3 frames, 3 seconds: true: the task begins in the first frame, so its two seconds end with the third. An event is a flag the task looks at, while !event.raised { wait Yield() }, which keeps the waiting in the module that knows what the event means; Event is that flag, with Raise and Clear. A host ticks a vm with wolang_vm_tick.

std.mem

ArrayNew, Free, Prefix, PrefixMut, Suffix, BytesFromRaw, ViewFromRaw, SizeOf, SoaNew, Copy. Storage and views; the language's arrays and lists are built on these. What allocates or views raw storage answers []mut T; Prefix and Suffix take and answer a read-only []T, and PrefixMut the writable one (D251). Copy(to, at, from, count) is one call that moves count bytes into to from offset at, where a loop would make one call per byte (D284); Builder appends with it.

std.arena

Arena and ArenaNew(chunk_size): runs of bytes handed out in order from big chunks, freed together (D285). The language's arena { } block does that for one block; this is for a phase that spans many calls, such as the syntax tree of a compiler.

  • pool.Take(count) answers a []mut u8 of count bytes, aligned to eight from the last run. A run bigger than a chunk gets a chunk of its own.
  • pool.Reset() hands the same storage out again from the start. Every view taken before is dead, and the bytes are not cleared.
  • pool.Capacity() is how many bytes the arena holds, used or not.

A run never moves, so a view of it stays valid until Reset or until the arena itself goes. Dropping the arena gives every chunk back.

wolang
need std.arena.{ArenaNew}
need std.io.{Print}

fun main() uses io, unsafe {
  var pool = ArenaNew(4096)
  var name = pool.Take(16)
  name[0] = 87
  var scratch = pool.Take(64)
  scratch[0] = 1
  Print("{pool.Capacity()} bytes held")
  pool.Reset()
}

std.own

Owned<T> and Shared<T>: a value that frees what it holds, and one that counts how many hold it.


std.ops

Add, Sub, Mul, Div, Neg, Eq, Ord, Hash, Max and Min. Each of the first seven is an @Operator ability whose one method is what an operator calls (D239): Plus for +, Minus, Times, Divide, Negate for unary -, Equals for == and !=, and Compare for < <= > >=. Self is the type that has the ability.

wolang
need std.io.{Print}
need std.ops.{Eq, Max, Ord}

struct Level {
  var n: int
}

extend Level as Eq {
  fun Equals(other: &Self) -> bool => n == other.n
}

extend Level as Ord {
  fun Compare(other: &Self) -> int => n - other.n
}

fun main() uses io {
  const top = Max(Level(3), Level(8))
  Print("{top.n} {Level(1) == Level(1)} {Level(1) < Level(2)} {Max(3, 9)}")
}

Numbers, bool, char and text have the operators they were always given, so Max(3, 9) is a compare and not a call. Hash is not an operator: it is the number std.map files a key under.

std.save

Save(object) writes the fields marked @Save of an object and of every object they reach; Load<T>(bytes) builds them again, or answers Corrupt. A field is written by name with a code for its type, so a program that gained or lost a field since the save still reads it: a field the bytes have and the class lacks is dropped, and one the class has and the bytes lack stays zero. An object is written once however many fields point at it, so a shared reference stays shared and a cycle comes back as a cycle (D266).

wolang
need std.io.{Print}
need std.mem.{Free}
need std.save.{Corrupt, Load, Save}

class Hero {
  @Save
  var level: int = 1
  @Save
  var name: text = ""
  var scratch: int = 0
}

fun main() uses io, unsafe {
  const hero = Hero()
  hero.level = 7
  hero.name = "Ada"
  hero.scratch = 99
  const bytes = Save(hero)
  const back = match Load<Hero>(bytes) {
    Ok(found) => found,
    Corrupt => Hero(),
  }
  Free(bytes)
  Print("{back.name} {back.level} {back.scratch}")
}

It prints Ada 7 0: scratch was not marked. What a marked field may hold is numbers, bool, char, text, enums that carry nothing, structs, classes without a virtual method, and an optional of any of those; a struct is saved whole unless it marks fields of its own. Anything else is E0176. An object is written as its declared class. Save gives back storage for Free.

The http package

A server and a client. See the cookbook for longer examples.

wolang
need http.{AppNew, Fetch, Ok, Request, Response, ServeWithDefaults}

fun Health(_request: Request) -> Response => Ok("ok\n")

fun main() uses io, net, time, unsafe {
  var app = AppNew()
  app.Get("/health", Health)
  const _code = ServeWithDefaults(app, 8080, 512)
}

Routing with path parameters and nested routers, middleware, typed extractors, static files with the traversal checks, and a client with TLS, redirects, chunked bodies and timeouts.

The db package

A key-value store on a disk that survives the power going out.

wolang
need db.{Close, Open}
need std.io.{Print}

fun main() uses io, unsafe {
  match Open("state.db") {
    Ok(store) => {
      var held = store
      const _put = held.Put("user:1", "a value")
      Print(held.Get("user:1") ?? "nothing")
      const keys = held.Range("user:", "user;")
      var i = 0
      while i < keys.Len() {
        Print(keys.At(i))
        i = i + 1
      }
      Close(&mut held)
    },
    Unreadable => { Print("could not open") },
  }
}

The gfx package

A window, input, pixels, OpenGL and sound, over this project's own backend for each system.

wolang
need gfx.{Available, CanvasNew, Open, Rgb, kClosed, kResizable}

fun main() uses io, unsafe {
  if !Available() {
    return
  }
  var window = Open("demo", 640, 480, kResizable)
  var canvas = CanvasNew(640, 480)
  var running = true
  while running {
    loop {
      const event = window.Poll()
      if event.kind == 0 {
        break
      }
      if event.kind == kClosed {
        running = false
      }
    }
    canvas.Clear(Rgb(16, 16, 24))
    canvas.Rect(100, 100, 80, 80, Rgb(255, 200, 60))
    window.Present(&canvas)
  }
}

Beyond the window itself (D247), all of it answers "no" cleanly on a build with no backend, so a headless run needs no guards:

AreaAPINotes
CursorShowCursor(bool), SetCursor(kCursorArrow/Hand/Text/Crosshair/ResizeH/ResizeV/ResizeAll), LockCursor(bool) -> boollocked: kMouseMoved carries the movement in scroll_x/scroll_y (unlocked it does too). X11 grabs and warps, Win32 clips and reads raw input, Cocoa detaches the cursor
WindowSetFullscreen, IsFullscreen, SetSize, SetMinSize, SetPosition, X(), Y()content sizes in pixels. Cocoa uses the system full screen (its own Space)
EventskDropped (key = count, DropPath(i)), kScaleChanged (scroll_x = new scale)X11 reads Xft.dpi; drops use XDND with text/uri-list
GamepadsGamepadConnected(i), GamepadName, GamepadButton(i, kPadA..), GamepadAxis(i, kAxisLeftX..), events kGamepadConnected / kGamepadDisconnectedup to 4, one layout: sticks -1..1 with up and left negative, triggers 0..1, no deadzone applied. Deadzone(v, dead) and AxisNormalize(raw, low, high) are helpers. Linux reads /dev/input/event* (needs the input group, scanned once a second), Windows XInput, macOS GameController
DialogsMessageBox(title, body, kDialogInfo/Warning/Error, kButtonsOk/OkCancel/YesNo) -> kAnswer*, OpenFileDialog, SaveFileDialog (both text?), DialogsAvailable()Linux runs zenity or kdialog and otherwise answers kAnswerUnavailable / null

Pad events arrive through Window.Poll after the window's own.


The image package

PNG, QOI and BMP, read and written in Wolang (D245). Everything decodes to an Image: width, height and RGBA8 pixels, which it frees when it goes out of scope. Get(x, y) answers 0xAARRGGBB, the format a gfx canvas holds, so putting an image on screen is a loop over canvas.pixels and this package does not depend on gfx.

wolang
need image.{Image, ImageNew, PngDecode, PngEncode, QoiEncode}
need std.io.{Print}

fun main() uses io, unsafe {
  match ImageNew(2, 2) {
    Ok(picture) => {
      picture.Set(0, 0, 0xffff0000)
      const file = PngEncode(&picture)
      match PngDecode(file) {
        Ok(back) => { Print("{back.width}x{back.height} {back.Get(0, 0)}") },
        _ => { Print("unreadable") },
      }
      Print("{QoiEncode(&picture).len} bytes of QOI")
    },
    _ => { Print("too large") },
  }
}
FunctionWhat
PngDecode(bytes)every colour type, depths 1 to 16 (16 is cut to 8), all filters, Adam7, PLTE, tRNS; checks CRCs, zlib header and Adler-32
PngEncode(&image)RGBA8, best of the five filters per row, std deflate
QoiDecode / QoiEncodethe whole format
BmpDecode24 and 32 bit, uncompressed, bottom-up or top-down
BmpEncode32 bit, bottom-up
ImageNew(w, h)a transparent picture

Decoders answer Malformed (bad signature, checksum, length, or data that stops early), Unsupported (a real feature not done: compressed or palette BMP, an unknown critical PNG chunk) or TooLarge (over kMaxSide = 16384 on a side or kMaxPixels = 64 Mi pixels); sizes are checked before any allocation and the PNG inflater is limited to what the header implies (D227), so a hostile file cannot trap or balloon. Encoders return storage the caller owns.


The math package

Vectors, matrices and quaternions for gameplay and rendering code, written in Wolang (D263). Vec2, Vec3 and Vec4 are structs of float (f32, like std.math), and the arithmetic is std.ops abilities (D239): a + b, a - b, -a, a * b, a / b and a == b work on all of them, component by component. Mat3, Mat4 and Quat meet Mul (a matrix or Hamilton product, the right side applied first) and Eq. Equality is exact; use NearTo for a tolerance. Anything that takes a square root states uses unsafe, as std.math.Sqrt does.

wolang
need math.{Vec3, Mat4Translation, QuatAxisAngle}
need std.io.{Print}

fun main() uses io, unsafe {
  const turn = QuatAxisAngle(Vec3(0.0, 0.0, 1.0), 1.5707963)
  const move = Mat4Translation(Vec3(10.0, 0.0, 0.0))
  const point = move.TransformPoint(turn.Rotate(Vec3(1.0, 0.0, 0.0)))
  Print("{point.x} {point.y} {point.z}")
  const sum = Vec3(1.0, 2.0, 3.0) + Vec3(1.0, 1.0, 1.0)
  const length = sum.Length()
  Print("{length}")
}
FunctionWhat
Dot(other), LengthSquared(), Length(), Distance(other)on Vec2, Vec3, Vec4 (Distance not on Vec4); Quat has Dot and Length
Cross(other)Vec3 only
Normalized()unit length; the zero vector stays zero (a zero Quat gives the identity)
Scaled(k), Divided(k)by a number; * and / between vectors are per component
Lerped(other, t), Clamped(low, high), NearTo(other, tolerance)per component (Clamped on Vec2, Vec3)
Mat3Identity(), Mat4Identity()
Mat4Translation(by), Mat4Scale(by), Mat4FromMat3(m)
Transform(v)Mat3 times a Vec3
TransformPoint(p), TransformDirection(d), TransformVec4(v)Mat4; a point gets the translation, a direction does not
Transposed(), Determinant(), Upper()Determinant is Mat3, Upper takes the Mat3 out of a Mat4
QuatIdentity(), QuatAxisAngle(axis, radians)the axis need not be a unit vector
Rotate(v), Conjugate(), Slerp(other, t), ToMat3(), ToMat4()Quat; Slerp takes the short way round

There is no general matrix inverse and no projection matrix yet.

The font package

TrueType fonts, read and drawn in Wolang (D276). FontLoad(bytes) parses a .ttf (or an OpenType file whose outlines are TrueType); Rasterize turns one glyph into an anti-aliased coverage bitmap; LayoutText places a string with advances, kerning and word wrapping; Atlas packs glyph bitmaps into one texture for a renderer. Everything is computation over bytes, so all of it runs and is tested with no window and no device.

The reader treats the file as hostile. Every table, offset and count is checked against the bytes that are there, a glyph is capped in points and components, and the way out of a bad file is an error, never a trap: Malformed for bytes that are not a font, Unsupported for an OpenType file with CFF outlines (OTTO), TooLarge for a file over kMaxFontBytes (64 MiB) or a glyph over kMaxBitmapSide pixels, and BadSize for a text size that is not positive. Glyph positions come from the hmtx and cmap tables (formats 4 and 12) and pairs from the kern table; GPOS kerning and hinting are not read.

SampleFont() is a small built-in font (letters in one case, digits, and the usual punctuation, drawn on a 5 by 7 grid), so a program can put text on screen with no font file. FontLoadFile(path) reads one from disk, and SystemFontFile(name) looks for name.ttf in the places each system keeps fonts and answers null when there is none; Available() says whether it found a common system font at all.

wolang
need font.{LayoutText, Measure, SampleFont}
need std.io.{Print}

fun main() uses io, unsafe {
  match SampleFont() {
    Ok(font) => {
      const width = Measure(font, "HELLO", 16.0)
      Print("{width}")
      const layout = LayoutText(font, "HELLO WORLD", 16.0, 60.0)
      Print("{layout.lines}")
    },
    _ => Print("no font"),
  }
}
FunctionWhat
FontLoad(bytes), FontLoadFile(path), SampleFont()a Font, or Malformed, TooLarge, Unsupported (and Missing for a path)
UnitsPerEm(), Ascent(), Descent(), LineGap(), GlyphCount()on Font, in font units
GlyphIndex(code)the glyph for a code point; 0 (the missing glyph) when there is none
Advance(glyph), LeftBearing(glyph), Kerning(left, right)in font units; Scale(size) is pixels per unit
GlyphOutline(glyph)the contours as points, composites resolved
Rasterize(font, glyph, size)a Glyph: coverage bytes, width, height, left, top, advance
Glyph.At(x, y), Glyph.Total(), Glyph.ToImage(r, g, b)one coverage byte; the sum; an image.Image with the coverage as alpha
LayoutText(font, text, size, wrap)a Layout of Placements; wrap of 0 or less does not wrap
Measure(font, text, size), LineHeight(font, size)the width of the widest line; the distance between baselines
DrawText(image, font, text, size, x, y, colour), DrawGlyphblend text into an image.Image in software
AtlasNew(width, height), Atlas.Get(font, glyph, size)a shelf-packed coverage bitmap; a Slot per glyph and size, null when full

The audio package

Sound in memory, mixed in Wolang, played through gfx when there is a device (D279). A Clip is interleaved f32 samples with a rate and a channel count. WavDecode reads 8, 16, 24 and 32-bit PCM and 32-bit float, mono or any channel count up to eight, and WavEncode writes 8, 16 or 24-bit PCM. A file whose data chunk is cut short keeps the frames that are there; a length that runs past the end, an unknown format or a size over kMaxSamples is an error, never a trap. Resample converts a clip to another rate by linear interpolation and Remix turns it into mono or stereo.

A Mixer has a rate, one or two output channels, voices and buses. Play starts a clip with a volume, a pan from -1 (left) to 1 (right) and a loop flag and answers an id; SetVolume, SetPan, SetPitch, SetBus and Stop take that id and ignore one that is gone. A mono clip is panned with equal power, a stereo clip by balance. A bus is a gain shared by the voices on it, and bus 0 exists from the start; the master gain applies to everything. Render fills a buffer with the sum of all voices, clamped to -1 to 1, and drops the voices that ended. It touches no device, so a test compares its output buffer.

OutputOpen pairs a mixer with the default device. Pump renders as many frames as the device has room for and queues them; call it once per frame. With no device IsOpen is false and Pump does nothing, so one program runs on a server and on a desktop. DeviceAvailable says which it is.

OggVorbisInfo reads an Ogg Vorbis file's headers: channels, sample rate, nominal bitrate, length in frames and the comments (Comment("title") ignores case). It checks every page's checksum. It does not decode the audio: a decoder needs a reference stream to be trusted, and none could be checked here, so decoding Vorbis waits for one (D279).

wolang
need audio.{ClipNew, MixerNew, WavDecode, WavEncode}
need std.io.{Print}
need std.mem.{ArrayNew}

fun Demo() -> int! uses io, unsafe {
  var tone = ClipNew(100, 1, 100)?
  var i = 0
  while i < 100 {
    tone.Set(i, 0, 0.5)
    i = i + 1
  }

  var mixer = MixerNew(100, 2)?
  const voice = mixer.Play(tone, 1.0, -1.0, false)
  var out = ArrayNew<f32>(4)
  mixer.Render(out)
  Print("{out[0]} {out[1]} {mixer.IsPlaying(voice)}")

  const wav = WavEncode(tone, 16)?
  const back = WavDecode(wav)?
  Print("{back.Frames()} frames at {back.rate} Hz")

  return 0
}

fun main() uses io, unsafe {
  match Demo() {
    Ok(_) => {},
    _ => {
      Print("failed")
    },
  }
}
FunctionWhat
ClipNew(frames, channels, rate)a silent clip; Get(frame, channel), Set(...), Frames(), Seconds()
WavDecode(bytes), WavEncode(clip, bits)Malformed, Unsupported, TooLarge
Resample(clip, rate), Remix(clip, channels)a new clip
MixerNew(rate, channels)Play, Stop, StopAll, IsPlaying, SetVolume, SetPan, SetPitch, SetBus, BusNew, SetBusGain, BusGain, SetMaster, Voices, Render
OutputOpen(rate, channels), DeviceAvailable()IsOpen, Pump, Close
OggVorbisInfo(bytes)channels, rate, bitrate, frames, vendor, Comment(key), Seconds()

The ui package

An immediate-mode toolkit (D277): the program describes the interface again on every frame, and each widget call answers what happened to it. There is no widget tree to keep in step with the program's state and no callbacks; a button is if ui.Button("Play") { ... }. What a frame produces is a draw list, a list of DrawCommands (a filled rectangle or a run of text, each with a position and a colour). The list is data, so layout and hit testing are tested with no window, and any renderer can draw it. Render(image, ui) draws it in software into an image.Image, which is how the tests check a frame against a stored picture, and how a program with no GPU gets its interface.

A frame runs Begin, the widgets, then End. Place(x, y, width) or Panel(x, y, width, height) says where the next widgets go; each takes one row below the last. Input comes from ui.input: input.Feed(event) takes a gfx event as it is, and MoveTo, Press, Release, Type and Key set the same state by hand. A widget's identity is the order it is called in, so call the same widgets in the same order each frame; Panel, Label and Spacer take no part in it.

wolang
need font.{SampleFont}
need image.{ImageNew}
need std.io.{Print}
need ui.{Render, StyleDefault, UiNew}

fun main() uses io, unsafe {
  match SampleFont() {
    Ok(font) => {
      const ui = UiNew(font, StyleDefault())
      ui.Begin()
      ui.Place(4, 4, 80)
      ui.Label("SCORE 7")
      const pressed = ui.Button("RESET")
      ui.End()
      Print("{ui.commands.Len()} {pressed}")
      match ImageNew(96, 80) {
        Ok(picture) => {
          Render(picture, ui)
          Print("{picture.width}")
        },
        _ => Print("no image"),
      }
    },
    _ => Print("no font"),
  }
}
FunctionWhat
UiNew(font, style), StyleDefault()a context, and the default colours, sizes and spacing
Begin(), End()start a frame (clears the draw list), and finish it (clears the one-frame input)
Place(x, y, width), Panel(x, y, w, h), Spacer(pixels)where the next row goes; a background plus a Place inside it
Label(text)a line of text
Button(text)true on the frame the mouse is released over a button it was pressed on
Checkbox(text, value)the value after this frame: it flips when clicked
Slider(value, low, high)the value after this frame: it follows the mouse while held, clamped to the range
TextField(edit)true when the text changed; TextEdit keeps the text and the cursor (TextEditNew, Value, Insert, Backspace, Delete, Left, Right)
ListBox(items, selected)the selected row after this frame
Render(image, ui), FillRect(...)draw the list into an image, blending colours with alpha

Text is measured and drawn with a font (D276). The labels of a frame are kept in one builder that the context owns, and each command points into it, so a label can be built on the spot ("score {n}").

The gpu package

A thin, typed layer over the GPU, with the backend left open (D280). Buffers, vertex layouts, programs, textures, render targets, state and draw calls are methods of a Device, which holds a Backend. There are two backends in the box: OpenGlStart(window) is OpenGL 3.3 core over the context a gfx window opened with kGl (or null, when there is none), and NullNew() runs everywhere. The null backend draws nothing; it records every call as a line of text, hands out ids, counts misuse (a draw with no program, a deleted buffer used again, a texture with no size) and compiles a shader as far as checking it has a main. That is what the tests of this package and of programs written on it run against, on a machine with no display. A second backend, Metal or Vulkan, is another extend T as Backend; callers do not change.

Handles are small structs (Buffer, Layout, Program, Texture, Target), and nothing frees itself: delete what you made. Vertex data is f32, indices are u32, and a layout is built from attributes of floats (stride and offset count floats, not bytes). ProgramNew returns Program!(CompileFailed) and the error carries the compiler's log (D235). A source with no #version line gets #version 330 core put in front; kSpriteVertex, kSpriteFragment and kSolidFragment are ready-made 2D shaders (position, uv, colour, one u_view matrix and one u_texture). Set uniforms after ProgramUse.

wolang
need gpu.{CompileFailed, DeviceNew, NullNew, kSolidFragment, kSpriteVertex, kTriangles}
need std.io.{Print}
need std.mem.{ArrayNew, Free}

fun main() uses io, unsafe {
  var backend = NullNew()
  var device = DeviceNew(backend)
  var corners = ArrayNew<f32>(6)
  corners[0] = 0.0
  corners[1] = 0.0
  corners[2] = 1.0
  corners[3] = 0.0
  corners[4] = 0.0
  corners[5] = 1.0

  const buffer = device.VertexBuffer(corners, false)
  const layout = device.LayoutNew()
  device.LayoutAttribute(layout, buffer, 0, 2, 2, 0)
  match device.ProgramNew(kSpriteVertex, kSolidFragment) {
    Ok(program) => {
      device.ProgramUse(program)
      device.Draw(layout, kTriangles, 0, 3)
      Print("{backend.log.Len()} calls, {device.Error()} errors")
    },
    CompileFailed(log) => {
      Print(log)
    },
    _ => {},
  }
  Free(corners)
}
FunctionWhat
DeviceNew(backend)Name, Error
VertexBuffer(data, dynamic), IndexBuffer(data, dynamic), BufferDelete(b)Buffer
LayoutNew(), LayoutAttribute(layout, buffer, index, count, stride, offset), LayoutIndices(layout, buffer), LayoutDelete(l)what feeds a draw
ProgramNew(vertex, fragment), ProgramUse(p), Uniform(p, name), ProgramDelete(p)CompileFailed(log) on failure; Uniform is -1 for a name the shader lacks
SetFloat, SetVec2, SetVec3, SetVec4, SetInt, SetMatrix(location, 16 floats)uniforms of the program in use
TextureNew(width, height, rgba, linear, repeat), TextureUpdate(...), TextureBind(unit, t), TextureDelete(t)RGBA8
TargetNew(texture), Begin(target, width, height, r, g, b, a, clear_depth), End(), TargetDelete(t)null for the window; Begin sets the viewport and clears
Blend, Depth, Cull, Scissorstate
Draw(layout, mode, first, count), DrawIndexed(layout, mode, count, first), Read(x, y, w, h)kTriangles, kLines, kPoints, kTriangleStrip, kTriangleFan, kLineStrip

The OpenGL backend is checked by tests only as far as "answers null with no window": the project's CI has no GL context on every platform, so a drawing program is run by hand with examples/ before release.

The app package

The loop that ties a window, a GPU device, sound and a clock together (D281). ConfigNew(title, width, height) makes a Config; ConfigParse(text, base) overlays an ini file on it ([window] title, width, height, resizable, vsync, gl; [loop] step, max_frame; [audio] rate, enabled), clamping what is absurd and keeping the default for what is missing or unreadable. ConfigDirectory(name) and ConfigPath(name) give the per-user place a program keeps its settings: %APPDATA% on Windows, Library/Application Support on macOS and $XDG_CONFIG_HOME or ~/.config elsewhere.

A game says what it does by having the Game ability: Update(dt) runs at a fixed step, Draw(alpha) once per frame with the fraction of a step left over, and OnEvent(event) answers whether to go on. The Clock turns frame times into steps: it clamps a long frame to max_frame, never owes more than eight steps in one frame (a stall does not turn into a spiral) and, with a step of zero, runs one variable step per frame. AppNew(config) opens the window (with a GL context when asked), picks the OpenGL backend when it is there and the null one when it is not, opens sound with a mixer that works whether or not a device does, and returns the App. Run(game) is the interactive loop; RunFrames(game, count, frame_time) runs the same update/draw/sound sequence with a time you give it and no window, which is how a server, a replay or a test runs a game.

wolang
need app.{AppNew, ConfigNew, Game}
need gfx.{Event}
need std.io.{Print}

class Spinner {
  var turns: int = 0
  var drawn: int = 0
}

extend Spinner as Game {
  fun Update(dt: float) uses unsafe {
    turns = turns + 1
  }

  fun Draw(alpha: float) uses unsafe {
    drawn = drawn + 1
  }

  fun OnEvent(event: Event) -> bool uses unsafe {
    return true
  }
}

fun main() uses io, unsafe {
  var config = ConfigNew("demo", 320, 200)
  config.gl = false
  config.sound = false
  config.hidden = true
  match AppNew(config) {
    Ok(app) => {
      var spinner = Spinner()
      const frames = app.RunFrames(spinner, 60, 0.016666667)
      Print("{frames} frames, {spinner.drawn} drawn")
      app.Close()
    },
    _ => {
      Print("no app")
    },
  }
}

How this compares

Go's standard library is bigger — net/http with HTTP/2, crypto/tls, database/sql, encoding/xml, reflection, a race detector. Rust's is smaller than this on purpose and leans on crates. Zig's is close to this in size and shape.

What is here that most of those have: strings, collections, sorting, files, paths, processes, sockets, time with zones, JSON, hashing, randomness, threads, logging. What is here that several of them leave to a package manager: TOML, YAML, INI, CSV, regular expressions, deflate and gzip, an HTTP server and client, a key-value store, a window with a GPU context and sound.

What is not here: a TLS implementation (bound, not written — lib/tls), HTTP/2 and HTTP/3, a SQL database, XML, reflection, a garbage collector that does anything, big integers, and a date library as thorough as java.time.

Page feedback

Was this page helpful?