Implementations

/// the number type families a function is written once for - one copy per type in the family
local const IntegerTypes := U8 | U16 | U32 | U64 | U128 | U256 | S8 | S16 | S32 | S64 | S128 | S256

local const FloatTypes := F16 | F32 | F64

/// Part below is F32, F64 respectively
local const ComplexTypes := C32 | C64

/// Part below is F32, F64 respectively
local const QuaternionTypes := Q32 | Q64

/// the same members, differing only in encoding
local const TextTypes := UTF8 | UTF16 | UTF32 | ASCII

/// the endless count 0, 1, 2, ... The only loop is For, so an open-ended loop is a For over this with a
/// while / until modifier, or a Return / Break inside
local function forever(): Iterator<U64> {
  return #builtin.forever()
}

/// FNV-1a over bytes - what every builtin Hashable is built on, starting from &hashSeed
local const hashPrime: U64 := 0x100000001b3

local function hashBytes(bytes: Bytes, seed: U64 := &hashSeed): U64 {
  let hash := seed
  for byte in bytes {
    set hash := (hash bxor (byte as U64)).wrappingMultiply(hashPrime)
  }
  return hash
}

/// folds one more hash into a running one - for hashing several parts (fields, elements) in order
local function hashCombine(hash: U64, next: U64): U64 {
  return hashBytes(next.toBytes(), hash)
}

/// hands error to &panicHandler - by default printing it and its trace() to &stderr and ending the program.
/// What Optional.expect and a failed builtin allocation come down to
local function abort(error: Error): Never {
  return &panicHandler.handle(error)
}

/// room for count Ts - builtin collections don't thread OutOfMemoryError through every signature, running out
/// of memory while growing one aborts instead
local function allocate<T>(count: U64): Pointer<T> {
  match Pointer<T>.allocateMany(count) {
    case Error(e) then { return abort(e) }
    case pointer then { return pointer }
  }
}

/// the first index in a range and the one past its last, whichever way it was written (a..<b, a..=b)
local function bounds(range: Range<U64>): (U64, U64) {
  return (range.start(), range.isInclusive() ? range.end() + 1 : range.end())
}

/// the digit character for 0 ... 35 - 0-9 then a-z
local function digitChar(value: U8): Codepoint {
  let code := value < 10 ? 48 + value : 87 + value
  return Codepoint.fromU32(code as U32) !? '?'
}

/// value as JSON - with an indent, each object's and array's members on lines of their own, depth deep
local function writeJson for Json(value: Unknown, indent: String, depth: String): String {
  let inner := depth ++ indent
  let (open, between, close) := indent == "" ? ("", ",", "") : ("\n" ++ inner, ",\n" ++ inner, "\n" ++ depth)
  match value {
    case undefined then {
      return "null"
    }
    case String as text then {
      let escaped := text.codepoints().map(λ(c) c == '"' ? "\\\"" : c == '\\' ? "\\\\" : c == '\n' ? "\\n" : c == '\r' ? "\\r" : c == '\t' ? "\\t" : c.value() < 32 ? "\\u" ++ c.value().toString(16).padStart(4, '0') : c.toString())
      return "\"" ++ escaped.join("") ++ "\""
    }
    case Boolean as truth then {
      return truth.toString()
    }
    case F64 as number if not number.isFinite() then {
      return "null"
    }
    case Array<Unknown> as items then {
      return items.isEmpty() ? "[]" : "[" ++ open ++ items.map(λ(item) writeJson(item, indent, inner)).join(between) ++ close ++ "]"
    }
    case Map<Unknown, Unknown> as members then {
      let written := members.entries().map(λ((name, member)) writeJson(name.toString(), "", "") ++ (indent == "" ? ":" : ": ") ++ writeJson(member, indent, inner))
      return members.isEmpty() ? "{}" : "{" ++ open ++ written.join(between) ++ close ++ "}"
    }
    case Struct as s then {
      return writeJson(s.fields(), indent, depth)
    }
    case _ if value.typeOf().implements(Numeric) then {
      return value.toString()
    }
    case _ then {
      return writeJson(value.toString(), indent, depth)
    }
  }
}

local function of for DocumentReader(text: String): DocumentReader {
  return DocumentReader{text := text.codepoints(), at := 0}
}

local method peek for DocumentReader(self: DocumentReader, ahead: U64 := 0): Codepoint? {
  return self.text[self.at + ahead]
}

local method atEnd for DocumentReader(self: DocumentReader): Boolean {
  return self.at >= self.text.size()
}

local method skipSpace for DocumentReader(self: DocumentReader): Undefined {
  for _ in forever() while self.peek() == ' ' | '\n' | '\r' | '\t' {
    set self.at += 1
  }
}

/// word next - read past it when it is
local method take for DocumentReader(self: DocumentReader, word: String): Boolean {
  if word.codepoints().enumerate().all(λ((i, c)) self.peek(i) == c) then {
    set self.at += word.size()
    return true
  }
  return false
}

/// what went wrong, and the line and column it's at
local method failure for DocumentReader(self: DocumentReader, format: String, what: String): ParseError {
  let before := self.text.take(self.at)
  let line := before.count(λ(c) c == '\n') + 1
  let column := self.at - (before.lastIndexOf('\n').map(λ(i) i + 1) ?? 0) + 1
  return ParseError.new("not " ++ format ++ " - " ++ what ++ ", at line " ++ line.toString() ++ ", column " ++ column.toString())
}

local method jsonValue for DocumentReader(self: DocumentReader): ParseError ! Unknown {
  self.skipSpace()
  match self.peek() {
    case '{' then {
      return self.jsonObject()!!
    }
    case '[' then {
      return self.jsonArray()!!
    }
    case '"' then {
      return self.jsonString()!!
    }
    case _ then {
      for (word, value) in [("true", true as Unknown), ("false", false), ("null", undefined)] if self.take(word) {
        return value
      }
      let start := self.at
      for _ in forever() while "-+.eE0123456789".contains(self.peek() ?? ' ') {
        set self.at += 1
      }
      if self.at == start then {
        error self.failure("JSON", self.atEnd() ? "the document ends early" : "'" ++ (self.peek() ?? ' ').toString() ++ "' starts no value")
      }
      return F64.parse(String.fromCodepoints(self.text.slice(start..<self.at)!!)) !? (error self.failure("JSON", "not a number"))
    }
  }
}

local method jsonObject for DocumentReader(self: DocumentReader): ParseError ! Map<String, Unknown> {
  set self.at += 1
  let members: Map<String, Unknown> := Map.of()
  self.skipSpace()
  if self.take("}") then {
    return members
  }
  for _ in forever() {
    self.skipSpace()
    if self.peek() != '"' then {
      error self.failure("JSON", "a member's name is a string")
    }
    let name := self.jsonString()!!
    self.skipSpace()
    if not self.take(":") then {
      error self.failure("JSON", "expected ':'")
    }
    members.set(name, self.jsonValue()!!)
    self.skipSpace()
    if self.take("}") then {
      return members
    }
    if not self.take(",") then {
      error self.failure("JSON", "expected ',' or '}'")
    }
  }
}

local method jsonArray for DocumentReader(self: DocumentReader): ParseError ! Array<Unknown> {
  set self.at += 1
  let items: Array<Unknown> := []
  self.skipSpace()
  if self.take("]") then {
    return items
  }
  for _ in forever() {
    items.push(self.jsonValue()!!)
    self.skipSpace()
    if self.take("]") then {
      return items
    }
    if not self.take(",") then {
      error self.failure("JSON", "expected ',' or ']'")
    }
  }
}

/// count hex digits' value
local method hex for DocumentReader(self: DocumentReader, count: U64): ParseError ! U32 {
  let value: U32 := 0
  for _ in 0..<count {
    let digit := self.peek()?.digitValue(16) ?! self.failure("JSON", "an escape's hex digits")
    set value := value * 16 + digit as U32
    set self.at += 1
  }
  return value
}

local method jsonString for DocumentReader(self: DocumentReader): ParseError ! String {
  set self.at += 1
  let out: Array<Codepoint> := []
  for _ in forever() {
    let c := self.peek() ?! self.failure("JSON", "a string that never ends")
    set self.at += 1
    if c == '"' then {
      return String.fromCodepoints(out)
    }
    if c != '\\' then {
      out.push(c)
      continue _
    }
    let escaped := self.peek() ?! self.failure("JSON", "a string that never ends")
    set self.at += 1
    if escaped == 'u' then {
      let code := self.hex(4)!!
      /// a pair of surrogates is one code point
      if code >= 0xD800 and code <= 0xDBFF and self.take("\\u") then {
        set code := 0x10000 + (code - 0xD800) * 0x400 + (self.hex(4)!! - 0xDC00)
      }
      out.push(Codepoint.fromU32(code)!!)
    } else {
      let index := "\"\\/bfnrt".indexOf(escaped.toString()) ?! self.failure("JSON", "'\\" ++ escaped.toString() ++ "' isn't an escape")
      out.push(['"', '\\', '/', '\u{8}', '\u{c}', '\n', '\r', '\t'][index]!!)
    }
  }
}

/// value - as a document gives it - made into Target, the way Target's declarations say (see core.md's
/// Documents); `where` names the place for an error - "the document.items[2].price"
local function decoded for Json<Target>(value: Unknown, where: String): ParseError ! Target {
  return decodedAs(value, #comptime.typeName(Target), where)!! as Target
}

/// the same, Target written as its text - "Array<Order>", "String?", "U8 | String"
local function decodedAs for Json(value: Unknown, typeText: String, where: String): ParseError ! Unknown {
  let type := Type.named(typeText)
  if typeText.endsWith("?") then {
    return value == undefined ? undefined : decodedAs(value, typeText.stripSuffix("?")!!, where)!!
  }
  let alternatives := type.variants()
  if type.isUnion() then {
    return alternatives.map(λ(alternative) decodedAs(value, alternative.name(), where)).find(λ(result) not (result is Error)) ?! ParseError.new(where ++ " isn't any of " ++ typeText)
  }
  let name := type.name().split("<")[0]!!
  let args := type.generics().map(λ(arg) arg.name())
  if name == "Unknown" then {
    return value
  }
  if value == undefined then {
    error ParseError.new(where ++ " is missing - a " ++ typeText ++ " was expected")
  }
  if name == "String" then {
    return value.narrow<String>() !? (error ParseError.new(where ++ " should be text, not " ++ value.toString()))
  }
  if name == "Boolean" then {
    return value is Boolean ? value : Boolean.parse(value.toString()) !? (error ParseError.new(where ++ " should be true or false, not " ++ value.toString()))
  }
  if name == "Array" | "Set" | "Stack" | "Queue" | "Deque" then {
    let items := value.narrow<Array<Unknown>>() !? (error ParseError.new(where ++ " should be a list, not " ++ value.toString()))
    let decodedItems := items.enumerate().map(λ((i, item)) decodedAs(item, args[0] ?? "Unknown", where ++ "[" ++ i.toString() ++ "]")!!).toArray()
    return decodedItems.collectInto(Type.named(name))
  }
  if name == "Map" | "SortedMap" then {
    let members := value.narrow<Map<String, Unknown>>() !? (error ParseError.new(where ++ " should be an object, not " ++ value.toString()))
    let out := members.entries().map(λ((key, member)) (decodedAs(key, args[0] ?? "String", where ++ "'s key " ++ key)!!, decodedAs(member, args[1] ?? "Unknown", where ++ "." ++ key)!!))
    return out.collectInto(Type.named(name))
  }
  if type.isAssignableFrom(value.typeOf()) then {
    return value
  }
  if type.implements(FromString) then {
    return value.toString().parse(type) !? (error ParseError.new(where ++ " is " ++ value.toString() ++ ", which isn't a " ++ name))
  }
  if type.isStruct() then {
    let members := value.narrow<Map<String, Unknown>>() !? (error ParseError.new(where ++ " should be an object with " ++ name ++ "'s fields, not " ++ value.toString()))
    let fields := type.fields().entries().map(λ((field, fieldType)) (field, decodedAs(members[field], fieldType.name(), where ++ "." ++ field)!!))
    return #runtime.construct(type, Map.fromIterable(fields))!!
  }
  if type.isEnum() and value is String then {
    let variant := type.variants().find(λ(v) v.name() == name ++ "." ++ value) ?! ParseError.new(where ++ " is " ++ value ++ ", which isn't a " ++ name)
    return #runtime.construct(variant, Map.of())!!
  }
  error ParseError.new(where ++ " is " ++ value.toString() ++ ", which can't be read as a " ++ typeText)
}

/// the bytes a row of width pixels takes, at this many bits a pixel
local function rowBytesOf(bits: U64, width: U64): U64 {
  return (bits * width + 7) ÷ 8
}

/// a number of width bytes at at - big-endian when big
local function uintAt(bytes: Bytes, at: U64, width: U64, big: Boolean := false): U64 {
  return #builtin.bytesUint(bytes, at, width, big) as U64
}

/// width bytes holding value - big-endian when big
local function uintBytes(value: U64, width: U64, big: Boolean := false): Bytes {
  let out := Bytes.filled(width, 0)
  #builtin.bytesPutUint(out, 0, width, value as F64, big)
  return out
}

/// every piece, one after another, copied once
local function joined(pieces: Array<Bytes>): Bytes {
  let total: U64 := 0
  for piece in pieces {
    set total := total + piece.size()
  }
  let out := Bytes.filled(total, 0)
  let at: U64 := 0
  for piece in pieces {
    out.copyFrom(piece, at)!!
    set at := at + piece.size()
  }
  return out
}

/// what can't be read, said as a ParseError about this format
local function unreadable(format: String, why: String): ParseError {
  return ParseError.new(#format"not a #{ format } image this can read: #{ why }")
}

/// a decoder's pixels, or why there are none
local function unpacked(pixels: Bytes?, format: String): ParseError ! Bytes {
  if pixels == undefined then {
    error unreadable(format, "its pixel data is cut short")
  }
  return pixels as Bytes
}

/// the 8 bytes every PNG starts with
local function pngSignature(): Bytes {
  return Bytes.fromArray([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])
}

/// one PNG chunk: its data's length, its four-letter type, the data, and a CRC of the type and data
local function pngChunk(kind: String, data: Bytes): Bytes {
  let typed := kind.encode() ++ data
  return uintBytes(data.size(), 4, true) ++ typed ++ uintBytes((typed.crc32() as F64) as U64, 4, true)
}

/// IHDR, PLTE, tRNS and the IDATs joined - what APNG's frames are read with too
local function pngParts(bytes: Bytes, kinds: Array<String> := ["IDAT"]): ParseError ! PngParts {
  let parts := PngParts{0, 0, 0, 0, false, Bytes.filled(0, 0), -1.0, Bytes.filled(0, 0)}
  let data: Array<Bytes> := []
  let at: U64 := 8
  let size := bytes.size()
  for _ in Iterator.forever() while at + 12 <= size {
    let length := uintAt(bytes, at, 4, true)
    if at + 12 + length > size then {
      error unreadable("PNG", "a chunk runs past the end")
    }
    let tag := bytes.slice(at + 4..<at + 8)!!.decode()
    let start := at + 8
    if tag == "IHDR" then {
      set parts.width := uintAt(bytes, start, 4, true)
      set parts.height := uintAt(bytes, start + 4, 4, true)
      set parts.depth := uintAt(bytes, start + 8, 1)
      set parts.colorType := uintAt(bytes, start + 9, 1)
      set parts.interlaced := uintAt(bytes, start + 12, 1) == 1
    }
    if tag == "PLTE" then {
      set parts.palette := #builtin.pixelsUnpack(bytes, start, length ÷ 3, 1, LayoutRgb, length, false, Bytes.filled(0, 0), -1.0) ?? Bytes.filled(0, 0)
    }
    if tag == "tRNS" then {
      if parts.colorType == 3 then {
        for i in 0..<(length.min(parts.palette.size() ÷ 4)) {
          set parts.palette[i * 4 + 3] := bytes[start + i] ?? 255
        }
      }
      if parts.colorType == 0 and length >= 2 then {
        set parts.key := #builtin.bytesUint(bytes, start, 2, true)
      }
      if parts.colorType == 2 and length >= 6 then {
        let (r, g, b) := (#builtin.bytesUint(bytes, start, 2, true), #builtin.bytesUint(bytes, start + 2, 2, true), #builtin.bytesUint(bytes, start + 4, 2, true))
        /// 8-bit samples' key is compared as 0xRRGGBB, 16-bit ones' as all 48 bits
        set parts.key := if parts.depth == 16 then r * 4294967296.0 + g * 65536.0 + b else (r % 256.0) * 65536.0 + (g % 256.0) * 256.0 + (b % 256.0)
      }
    }
    if kinds.contains(tag) then {
      data.push(bytes.slice(start..<start + length)!!)
    }
    if tag == "IEND" then {
      break _
    }
    set at := at + 12 + length
  }
  if parts.width == 0 or parts.height == 0 then {
    error unreadable("PNG", "it has no header, or no pixels")
  }
  set parts.data := joined(data)
  return parts
}

/// the layout of a PNG color type's samples at this depth - undefined for one PNG doesn't have
local function pngLayoutOf(colorType: U64, depth: U64): U64? {
  if colorType == 0 then {
    return if depth == 1 then LayoutGray1 else if depth == 2 then LayoutGray2 else if depth == 4 then LayoutGray4 else if depth == 8 then LayoutGray else if depth == 16 then LayoutGray16 else undefined
  }
  if colorType == 3 then {
    return if depth == 1 then LayoutIndex1 else if depth == 2 then LayoutIndex2 else if depth == 4 then LayoutIndex4 else if depth == 8 then LayoutIndex8 else undefined
  }
  if depth != 8 and depth != 16 then {
    return undefined
  }
  let wide := depth == 16
  return if colorType == 2 then (if wide then LayoutRgb16 else LayoutRgb) else if colorType == 4 then (if wide then LayoutGrayAlpha16 else LayoutGrayAlpha) else if colorType == 6 then (if wide then LayoutRgba16 else LayoutRgba) else undefined
}

/// the layout PNG's samples are in, and their bits a pixel
local function pngLayout(colorType: U64, depth: U64): ParseError ! (U64, U64) {
  let channels: U64 := if colorType == 0 then 1 else if colorType == 2 then 3 else if colorType == 3 then 1 else if colorType == 4 then 2 else if colorType == 6 then 4 else 0
  let layout := pngLayoutOf(colorType, depth)
  if layout == undefined then {
    error unreadable("PNG", #format"color type #{ colorType } at #{ depth } bits a sample")
  }
  return (layout as U64, channels * depth)
}

/// a PNG's pixels, from its parts - each pass of an interlaced one in turn
local function pngPixels(parts: PngParts): ParseError ! Bytes {
  let (layout, bits) := pngLayout(parts.colorType, parts.depth)!!
  let raw := #builtin.zlibDecompress(parts.data)!!
  /// how far back the filters look - a whole pixel, or a byte when pixels are smaller
  let bpp := ((bits + 7) ÷ 8).max(1)
  if not parts.interlaced then {
    let rowBytes := rowBytesOf(bits, parts.width)
    let samples := #builtin.pngUnfilter(raw, 0, rowBytes, parts.height, bpp)
    if samples == undefined then {
      error unreadable("PNG", "its rows are cut short, or one's filter isn't one")
    }
    return unpacked(#builtin.pixelsUnpack(samples as Bytes, 0, parts.width, parts.height, layout, rowBytes, false, parts.palette, parts.key), "PNG")!!
  }
  let rgba := Bytes.filled(parts.width * parts.height * 4, 0)
  let offset: U64 := 0
  /// Adam7: where each pass starts and steps, x then y
  for pass in 0..<7 {
    let x0: U64 := ([0, 4, 0, 2, 0, 1, 0])[pass]!!
    let y0: U64 := ([0, 0, 4, 0, 2, 0, 1])[pass]!!
    let dx: U64 := ([8, 8, 4, 4, 2, 2, 1])[pass]!!
    let dy: U64 := ([8, 8, 8, 4, 4, 2, 2])[pass]!!
    let w := if parts.width > x0 then (parts.width - x0 + dx - 1) ÷ dx else 0
    let h := if parts.height > y0 then (parts.height - y0 + dy - 1) ÷ dy else 0
    if w > 0 and h > 0 then {
      let rowBytes := rowBytesOf(bits, w)
      let samples := #builtin.pngUnfilter(raw, offset, rowBytes, h, bpp)
      if samples == undefined then {
        error unreadable("PNG", "an interlaced pass is cut short, or a row's filter isn't one")
      }
      let part := unpacked(#builtin.pixelsUnpack(samples as Bytes, 0, w, h, layout, rowBytes, false, parts.palette, parts.key), "PNG")!!
      #builtin.adam7Place(rgba, parts.width, parts.height, part, pass)
      set offset := offset + h * (rowBytes + 1)
    }
  }
  return rgba
}

/// every color type and bit depth, interlaced or not
local function decodePng(bytes: Bytes): ParseError ! Image {
  let parts := pngParts(bytes)!!
  return Image{parts.width, parts.height, pngPixels(parts)!!}
}

/// the IDAT data of these pixels: gray, gray with alpha, RGB or RGBA - the fewest that hold them, or
/// RGBA always when rgba - each row with its best filter, deflated; and the color type that is
local function pngData(rgba: Bytes, width: U64, height: U64, alwaysRgba: Boolean := false): (Bytes, U64) {
  let found := if alwaysRgba then 3 else #builtin.pixelsAnalyze(rgba) as U64
  let alpha := found band 1 != 0
  let color := found band 2 != 0
  let (layout, colorType, bpp) := if color then (if alpha then (LayoutRgba, 6, 4) else (LayoutRgb, 2, 3)) else (if alpha then (LayoutGrayAlpha, 4, 2) else (LayoutGray, 0, 1))
  let rowBytes := width * bpp
  let filtered := #builtin.pngFilter(#builtin.pixelsPack(rgba, width, height, layout, rowBytes, false), rowBytes, height, bpp)
  return (#builtin.zlibCompress(filtered), colorType)
}

/// a palette BMP's colors, as RGBA - after the header, 4 bytes each (blue, green, red, unused)
local function bmpPalette(bytes: Bytes, infoSize: U64, offset: U64, bits: U64): Bytes {
  let colors := if uintAt(bytes, 46, 4) > 0 then uintAt(bytes, 46, 4) else 1 shl bits
  let room := if offset > 14 + infoSize then (offset - 14 - infoSize) ÷ 4 else 0
  return #builtin.pixelsUnpack(bytes, 14 + infoSize, colors.min(room), 1, LayoutBgrx, colors * 4, false, Bytes.filled(0, 0), -1.0) ?? Bytes.filled(0, 0)
}

/// 1-, 4- and 8-bit with a palette, 16-bit (5-5-5 or 5-6-5), 24- and 32-bit, uncompressed - bottom row
/// first, or top row first when the height is negative
local function decodeBmp(bytes: Bytes): ParseError ! Image {
  let size := bytes.size()
  if size < 54 then {
    error unreadable("BMP", "its headers are cut short")
  }
  let offset := uintAt(bytes, 10, 4)
  let infoSize := uintAt(bytes, 14, 4)
  let width := bytes.readInteger<S32>(18)!!
  let height := bytes.readInteger<S32>(22)!!
  let bits := uintAt(bytes, 28, 2)
  let compression := uintAt(bytes, 30, 4)
  if width < 0 then {
    error unreadable("BMP", "a negative width")
  }
  let columns := width as U64
  let rows := height.abs() as U64
  let stride := (bits * columns + 31) ÷ 32 * 4
  /// BI_BITFIELDS (3) and BI_ALPHABITFIELDS (6) give each channel's mask after the header
  let masked := compression == 3 or compression == 6
  if compression != 0 and not masked then {
    error unreadable("BMP", #format"compression #{ compression }")
  }
  /// the red, green, blue and alpha masks follow a 40-byte header, or are in a longer one - at 54 either way
  let mask := λ(k) if 58 + 4 * k <= size then uintAt(bytes, 54 + 4 * k, 4) else 0
  let palette := if bits <= 8 then bmpPalette(bytes, infoSize, offset, bits) else Bytes.filled(0, 0)
  let layout := if bits == 1 then LayoutIndex1 else if bits == 4 then LayoutIndex4 else if bits == 8 then LayoutIndex8 else if bits == 16 then (if masked and mask(0) == 0xF800 then LayoutRgb565 else LayoutRgb555) else if bits == 24 then LayoutBgr else if bits == 32 then (if masked and mask(3) == 0 then LayoutBgrx else LayoutBgra) else undefined
  if layout == undefined then {
    error unreadable("BMP", #format"#{ bits }-bit pixels")
  }
  let rgba := unpacked(#builtin.pixelsUnpack(bytes, offset, columns, rows, layout as U64, stride, height > 0, palette, -1.0), "BMP")!!
  /// a 32-bit BMP whose alpha is 0 everywhere isn't using it - opaque, not invisible
  if bits == 32 and (#builtin.pixelsAnalyze(rgba) as U64) band 8 == 0 then {
    return Image{columns, rows, #builtin.pixelsUnpack(bytes, offset, columns, rows, LayoutBgrx, stride, height > 0, palette, -1.0) ?? rgba}
  }
  return Image{columns, rows, rgba}
}

local function decodeQoi(bytes: Bytes): ParseError ! Image {
  if bytes.size() < 22 then {
    error unreadable("QOI", "its header is cut short")
  }
  let width := uintAt(bytes, 4, 4, true)
  let height := uintAt(bytes, 8, 4, true)
  return Image{width, height, unpacked(#builtin.qoiDecode(bytes, 14, width * height), "QOI")!!}
}

/// color-mapped, true-color and gray, plain or run-length encoded, 8 to 32 bits a pixel
local function decodeTga(bytes: Bytes): ParseError ! Image {
  let size := bytes.size()
  if size < 18 then {
    error unreadable("TGA", "its header is cut short")
  }
  let idLength := uintAt(bytes, 0, 1)
  let mapType := uintAt(bytes, 1, 1)
  let kind := uintAt(bytes, 2, 1)
  let mapFirst := uintAt(bytes, 3, 2)
  let mapLength := uintAt(bytes, 5, 2)
  let mapBits := uintAt(bytes, 7, 1)
  let width := uintAt(bytes, 12, 2)
  let height := uintAt(bytes, 14, 2)
  let bits := uintAt(bytes, 16, 1)
  let descriptor := uintAt(bytes, 17, 1)
  let alphaBits := descriptor band 15
  let mapStart := 18 + idLength
  let mapBytes := if mapType == 1 then mapLength * ((mapBits + 7) ÷ 8) else 0
  let at := mapStart + mapBytes
  let bpp := (bits + 7) ÷ 8
  /// a true-color layout for this many bits - 16 and 15 are 5-5-5, with an attribute bit as alpha when there's one
  let trueColor := λ(b, alpha) if b == 32 then (if alpha then LayoutBgra else LayoutBgrx) else if b == 24 then LayoutBgr else if alpha then LayoutArgb1555 else LayoutRgb555
  let base := kind band 7
  /// the map starts at mapFirst - the indices below it have no color
  let entries := #builtin.pixelsUnpack(bytes, mapStart, mapLength, 1, trueColor(mapBits, mapBits == 32 or mapBits == 16), mapBytes, false, Bytes.filled(0, 0), -1.0) ?? Bytes.filled(0, 0)
  let palette := if mapType == 1 then Bytes.filled(mapFirst * 4, 0) ++ entries else Bytes.filled(0, 0)
  let layout := if base == 1 then LayoutIndex8 else if base == 3 then (if bits == 16 then LayoutGrayAlpha else LayoutGray) else trueColor(bits, alphaBits > 0)
  if (base == 1 and bits != 8) or (base == 2 and not [15, 16, 24, 32].contains(bits)) or (base == 3 and bits != 8 and bits != 16) or not [1, 2, 3].contains(base) then {
    error unreadable("TGA", #format"image type #{ kind } at #{ bits } bits a pixel")
  }
  let raw := if kind >= 9 then unpacked(#builtin.rleDecode(bytes, at, width * height, bpp), "TGA")!! else bytes
  let start := if kind >= 9 then 0 else at
  /// the bottom row first unless the descriptor says the top
  let image := Image{width, height, unpacked(#builtin.pixelsUnpack(raw, start, width, height, layout, width * bpp, descriptor band 0x20 == 0, palette, -1.0), "TGA")!!}
  return if descriptor band 0x10 != 0 then image.flipHorizontal() else image
}

local function isPnmSpace(byte: U64): Boolean {
  return byte == 0x20 or byte == 0x09 or byte == 0x0A or byte == 0x0D
}

/// the next whitespace-separated number from at - '#' starts a comment to the end of the line - and
/// where it ends
local function pnmNumber(bytes: Bytes, at: U64): ParseError ! (U64, U64) {
  let i := at
  let size := bytes.size()
  for _ in Iterator.forever() while i < size {
    let byte := (bytes[i] ?? 0) as U64
    if byte == 0x23 then {
      for _ in Iterator.forever() while i < size and bytes[i] != 0x0A {
        set i := i + 1
      }
    } else if isPnmSpace(byte) then {
      set i := i + 1
    } else {
      break _
    }
  }
  let value: U64 := 0
  let start := i
  for _ in Iterator.forever() while i < size {
    let byte := (bytes[i] ?? 0) as U64
    if byte < 0x30 or byte > 0x39 then {
      break _
    }
    set value := value * 10 + (byte - 0x30)
    set i := i + 1
  }
  if i == start then {
    error unreadable("PNM", "a number is missing from its header")
  }
  return (value, i)
}

/// samples whose most is maxval, as 0 to 255
local function scaledSamples(samples: Array<U64>, maxval: U64): Bytes {
  return Bytes.fromArray(samples.map(λ(v) (v.min(maxval) * 255 + maxval ÷ 2) ÷ maxval.max(1)))
}

/// P1 to P6, and P7 (PAM) with 1 to 4 channels - plain (ASCII) or raw, any maxval
local function decodePnm(bytes: Bytes): ParseError ! Image {
  let kind := ((bytes[1] ?? 0) as U64) - 0x30
  let width: U64 := 0
  let height: U64 := 0
  let maxval: U64 := 1
  let channels: U64 := if kind == 3 or kind == 6 then 3 else 1
  let at: U64 := 2
  if kind == 7 then {
    /// PAM: a line each - WIDTH, HEIGHT, DEPTH, MAXVAL, TUPLTYPE - then ENDHDR
    let headerEnd := bytes.indexOf("ENDHDR".encode()) ?? 0
    if headerEnd == 0 then {
      error unreadable("PAM", "its header has no ENDHDR")
    }
    for line in bytes.slice(3..<headerEnd)!!.decode().split("\n") {
      let words := line.trim().split(" ").filter(λ(w) w != "")
      let value := U64.parse(words[1] ?? "0") !? 0
      match words[0] ?? "" {
        case "WIDTH" then {
          set width := value
        }
        case "HEIGHT" then {
          set height := value
        }
        case "DEPTH" then {
          set channels := value
        }
        case "MAXVAL" then {
          set maxval := value
        }
        case _ then {
        }
      }
    }
    set at := (bytes.indexOf("\n".encode(), headerEnd) ?? headerEnd) + 1
  } else {
    let (w, afterWidth) := pnmNumber(bytes, at)!!
    let (h, afterHeight) := pnmNumber(bytes, afterWidth)!!
    set width := w
    set height := h
    set at := afterHeight
    if kind != 1 and kind != 4 then {
      let (m, afterMax) := pnmNumber(bytes, at)!!
      set maxval := m
      set at := afterMax
    }
    /// a single whitespace byte before raw data
    set at := at + 1
  }
  if width == 0 or height == 0 or channels < 1 or channels > 4 then {
    error unreadable("PNM", "its size or depth is missing")
  }
  let layouts := [LayoutGray, LayoutGrayAlpha, LayoutRgb, LayoutRgba]
  let wide := maxval > 255
  let layout := if wide then ([LayoutGray16, LayoutGrayAlpha16, LayoutRgb16, LayoutRgba16])[channels - 1]!! else layouts[channels - 1]!!
  /// bitmaps: 1 is black
  let blackWhite := Bytes.fromArray([255, 255, 255, 255, 0, 0, 0, 255])
  if kind == 4 then {
    let rgba := #builtin.pixelsUnpack(bytes, at, width, height, LayoutIndex1, (width + 7) ÷ 8, false, blackWhite, -1.0)
    return Image{width, height, unpacked(rgba, "PBM")!!}
  }
  if kind <= 3 then {
    /// plain: every sample a number
    let samples: Array<U64> := []
    let count := width * height * channels
    let i := at - 1
    if kind == 1 then {
      /// a bitmap's digits needn't be apart
      for _ in Iterator.forever() while samples.size() < count and i < bytes.size() {
        let byte := (bytes[i] ?? 0) as U64
        if byte == 0x30 or byte == 0x31 then {
          samples.push(if byte == 0x31 then 0 else 255)
        }
        set i := i + 1
      }
      return Image{width, height, unpacked(#builtin.pixelsUnpack(Bytes.fromArray(samples), 0, width, height, LayoutGray, width, false, Bytes.filled(0, 0), -1.0), "PBM")!!}
    }
    for _ in 0..<count {
      let (value, next) := pnmNumber(bytes, i)!!
      samples.push(value)
      set i := next
    }
    return Image{width, height, unpacked(#builtin.pixelsUnpack(scaledSamples(samples, maxval), 0, width, height, layouts[channels - 1]!!, width * channels, false, Bytes.filled(0, 0), -1.0), "PNM")!!}
  }
  let sampleBytes: U64 := if wide then 2 else 1
  let rowBytes := width * channels * sampleBytes
  let rgba := unpacked(#builtin.pixelsUnpack(bytes, at, width, height, layout, rowBytes, false, Bytes.filled(0, 0), -1.0), "PNM")!!
  if maxval == 255 or maxval == 65535 then {
    return Image{width, height, rgba}
  }
  /// another maxval: each sample scaled to 0 to 255, one at a time
  let samples: Array<U64> := []
  for k in 0..<(width * height * channels) {
    samples.push(uintAt(bytes, at + k * sampleBytes, sampleBytes, true))
  }
  return Image{width, height, unpacked(#builtin.pixelsUnpack(scaledSamples(samples, maxval), 0, width, height, layouts[channels - 1]!!, width * channels, false, Bytes.filled(0, 0), -1.0), "PNM")!!}
}

/// a palette of colors RGB triplets at at, as RGBA quads
local function gifPalette(bytes: Bytes, at: U64, colors: U64): Bytes {
  return #builtin.pixelsUnpack(bytes, at, colors, 1, LayoutRgb, colors * 3, false, Bytes.filled(0, 0), -1.0) ?? Bytes.filled(colors * 4, 0)
}

/// past the sub-blocks starting at at - the index after their empty one
local function pastSubBlocks(bytes: Bytes, at: U64): U64 {
  let i := at
  let size := bytes.size()
  for _ in Iterator.forever() while i < size and bytes[i] != 0 {
    set i := i + ((bytes[i] ?? 0) as U64) + 1
  }
  return i + 1
}

/// an interlaced frame's rows put in order: GIF stores every 8th from 0, every 8th from 4, every 4th from
/// 2, then every 2nd from 1
local function deinterlaced(rgba: Bytes, width: U64, height: U64): Bytes {
  let out := Bytes.filled(rgba.size(), 0)
  let row: U64 := 0
  for pass in 0..<4 {
    let step: U64 := ([8, 8, 4, 2])[pass]!!
    let y: U64 := ([0, 4, 2, 1])[pass]!!
    for _ in Iterator.forever() while y < height {
      out.copyFrom(rgba.slice(row * width * 4..<(row + 1) * width * 4)!!, y * width * 4)!!
      set row := row + 1
      set y := y + step
    }
  }
  return out
}

/// every frame of a GIF, as it's stored - each over the frames before is the reader's to compose
local function gifParts(bytes: Bytes): ParseError ! GifParts {
  let size := bytes.size()
  if size < 13 then {
    error unreadable("GIF", "its header is cut short")
  }
  let parts := GifParts{uintAt(bytes, 6, 2), uintAt(bytes, 8, 2), undefined, []}
  let flags := uintAt(bytes, 10, 1)
  let at: U64 := 13
  let global := if flags band 0x80 != 0 then gifPalette(bytes, 13, 1 shl ((flags band 7) + 1)) else Bytes.filled(0, 0)
  if flags band 0x80 != 0 then {
    set at := at + 3 * (1 shl ((flags band 7) + 1))
  }
  let delay: U64 := 0
  let disposal: U64 := 0
  let transparent: U64? := undefined
  for _ in Iterator.forever() while at < size {
    let kind := uintAt(bytes, at, 1)
    if kind == 0x3B then {
      break _
    }
    if kind == 0x21 then {
      let label := uintAt(bytes, at + 1, 1)
      if label == 0xF9 and at + 7 < size then {
        let packed := uintAt(bytes, at + 3, 1)
        set disposal := (packed shr 2) band 7
        set delay := uintAt(bytes, at + 4, 2)
        set transparent := if packed band 1 != 0 then uintAt(bytes, at + 6, 1) else undefined
      }
      /// NETSCAPE2.0's loop count
      if label == 0xFF and at + 16 < size and bytes.slice(at + 3..<at + 14)!!.decode() == "NETSCAPE2.0" then {
        set parts.loops := uintAt(bytes, at + 16, 2)
      }
      set at := pastSubBlocks(bytes, at + 2)
    } else if kind == 0x2C then {
      if at + 10 > size then {
        error unreadable("GIF", "an image descriptor is cut short")
      }
      let left := uintAt(bytes, at + 1, 2)
      let top := uintAt(bytes, at + 3, 2)
      let width := uintAt(bytes, at + 5, 2)
      let height := uintAt(bytes, at + 7, 2)
      let packed := uintAt(bytes, at + 9, 1)
      set at := at + 10
      let palette := if packed band 0x80 != 0 then gifPalette(bytes, at, 1 shl ((packed band 7) + 1)) else global.slice(0..<global.size())!!
      if packed band 0x80 != 0 then {
        set at := at + 3 * (1 shl ((packed band 7) + 1))
      }
      if transparent != undefined and (transparent as U64) * 4 < palette.size() then {
        set palette[(transparent as U64) * 4 + 3] := 0
      }
      let minCodeSize := uintAt(bytes, at, 1)
      let indices := #builtin.lzwDecode(bytes, at + 1, minCodeSize, width * height)
      if indices == undefined or minCodeSize > 11 then {
        error unreadable("GIF", "a frame's pixels are cut short")
      }
      let rgba := unpacked(#builtin.pixelsUnpack(indices as Bytes, 0, width, height, LayoutIndex8, width, false, palette, -1.0), "GIF")!!
      parts.frames.push(GifFrame{left, top, width, height, delay, disposal, if packed band 0x40 != 0 then deinterlaced(rgba, width, height) else rgba})
      set at := pastSubBlocks(bytes, at + 1)
      set delay := 0
      set disposal := 0
      set transparent := undefined
    } else {
      error unreadable("GIF", #format"a block of kind #{ kind }")
    }
  }
  if parts.frames.isEmpty() then {
    error unreadable("GIF", "it has no frames")
  }
  return parts
}

/// a GIF's first frame, on its screen - transparent where the frame doesn't cover it
local function decodeGifImage(bytes: Bytes): ParseError ! Image {
  let parts := gifParts(bytes)!!
  let canvas := Image.new(parts.width, parts.height)
  let frame := parts.frames[0]!!
  #builtin.pixelsDraw(canvas.rgba, canvas.columns, canvas.rows, frame.rgba, frame.width, frame.height, frame.left as S64, frame.top as S64)
  return canvas
}

/// a GIF's image data for these pixels: at most 256 colors - dithered when there are more - an index
/// for transparency when a pixel's alpha is under 128. Its local color table's bits, the table, and
/// the transparent index (or undefined)
local function gifImageData(rgba: Bytes, width: U64, height: U64): (U64, Bytes, U64?, Bytes) {
  let quantized := #builtin.quantize(rgba, width * height, width, 256, true)
  let palette := quantized[0]!! as Bytes
  let indices := quantized[1]!! as Bytes
  let transparent := quantized[2]!! as F64
  let colors := (palette.size() ÷ 4).max(2)
  /// a table of 2^bits colors, bits at least 1
  let bits: U64 := 1
  for _ in Iterator.forever() while (1 shl bits) < colors {
    set bits := bits + 1
  }
  let table := #builtin.pixelsPack(palette, palette.size() ÷ 4, 1, LayoutRgb, palette.size() ÷ 4 * 3, false) ++ Bytes.filled(((1 shl bits) - palette.size() ÷ 4) * 3, 0)
  let minCodeSize := bits.max(2)
  let data := Bytes.fromArray([minCodeSize as U8]) ++ #builtin.lzwEncode(indices, minCodeSize)
  return (bits, table, if transparent < 0.0 then undefined else transparent as U64, data)
}

/// one GIF frame: its graphic control extension (when it has a delay, a disposal or transparency), its
/// image descriptor with a local color table, and its image data
local function gifFrameBytes(rgba: Bytes, width: U64, height: U64, left: U64, top: U64, delay: U64, disposal: U64): Bytes {
  let (bits, table, transparent, data) := gifImageData(rgba, width, height)
  let control := Bytes.filled(0, 0)
  if transparent != undefined or delay > 0 or disposal > 0 then {
    let packed := (disposal shl 2) bor (if transparent != undefined then 1 else 0)
    set control := Bytes.fromArray([0x21, 0xF9, 4, packed as U8]) ++ uintBytes(delay, 2) ++ Bytes.fromArray([(transparent ?? 0) as U8, 0])
  }
  let descriptor := Bytes.fromArray([0x2C]) ++ uintBytes(left, 2) ++ uintBytes(top, 2) ++ uintBytes(width, 2) ++ uintBytes(height, 2) ++ Bytes.fromArray([(0x80 bor (bits - 1)) as U8])
  return control ++ descriptor ++ table ++ data
}

/// GIF89a's header and logical screen, with no global color table - each frame has its own
local function gifHeader(width: U64, height: U64): Bytes {
  return "GIF89a".encode() ++ uintBytes(width, 2) ++ uintBytes(height, 2) ++ Bytes.fromArray([0, 0, 0])
}

/// a marker's segment: FF, the marker, its length (2 more than its data) and its data
local function jpegSegment(marker: U8, data: Bytes): Bytes {
  return Bytes.fromArray([0xFF, marker]) ++ uintBytes(data.size() + 2, 2, true) ++ data
}

/// Annex K's table scaled for quality as the IJG's encoder does: 50 is the table itself, 100 every
/// value 1, below 50 coarser and coarser
local function jpegQuantTable(base: Array<U64>, quality: U64): Array<U64> {
  let scale := if quality < 50 then 5000 ÷ quality else 200 - 2 * quality
  return base.map(λ(v) ((v * scale + 50) ÷ 100).max(1).min(255))
}

/// 4-byte little-endian numbers, as the decoding kernels read them
local function int32s(values: Array<U64>): Bytes {
  let out := Bytes.filled(values.size() * 4, 0)
  for value, i in values {
    #builtin.bytesPutUint(out, i * 4, 4, value as F64, false)
  }
  return out
}

/// The frame as jpegDecodeScan and jpegFinish read it: the component count, the MCUs across and down,
/// the largest sampling across and down, whether it's progressive - then for each component its
/// sampling, its quantization table, its blocks across and down (whole MCUs' worth), where its
/// coefficients start, and its blocks across and down the image itself covers. And how many
/// coefficients there are in all.
local function jpegFrame(width: U64, height: U64, components: Array<JpegComponent>, progressive: Boolean): (Bytes, U64) {
  let maxH := components.map(λ(c) c.h).max() !? 1
  let maxV := components.map(λ(c) c.v).max() !? 1
  let mcusX := (width + 8 * maxH - 1) ÷ (8 * maxH)
  let mcusY := (height + 8 * maxV - 1) ÷ (8 * maxV)
  let values: Array<U64> := [components.size(), mcusX, mcusY, maxH, maxV, if progressive then 1 else 0]
  let offset: U64 := 0
  for c in components {
    let perLine := mcusX * c.h
    let perColumn := mcusY * c.v
    let across := ((width * c.h + maxH - 1) ÷ maxH + 7) ÷ 8
    let down := ((height * c.v + maxV - 1) ÷ maxV + 7) ÷ 8
    values.pushAll([c.h, c.v, c.table, perLine, perColumn, offset, across, down])
    set offset := offset + perLine * perColumn * 64
  }
  return (int32s(values), offset)
}

/// what the bytes hold, read marker by marker - each scan's coefficients added to the last's
local function decodeJpeg(bytes: Bytes): ParseError ! Image {
  let size := bytes.size()
  let byte := λ(at) (bytes[at] ?? 0) as U64
  let quant := Bytes.filled(512, 0)
  let tables := Bytes.filled(8 * 272, 0)
  /// Annex K's tables to begin with - Motion JPEG's frames often leave them out and count on them
  for slot, i in [0, 4, 1, 5] {
    tables.copyFrom(Bytes.fromArray(jpegHuffman.slice(jpegHuffmanStarts[i]!!..<jpegHuffmanStarts[i + 1]!!) !? []), slot * 272)!!
  }
  let width: U64 := 0
  let height: U64 := 0
  let components: Array<JpegComponent> := []
  let frame := Bytes.filled(0, 0)
  let coeffs := Bytes.filled(0, 0)
  let restart: U64 := 0
  /// Adobe's APP14 says how 3 or 4 components are coded - undefined when there's none
  let transform: U64? := undefined
  let at: U64 := 2
  for _ in Iterator.forever() while at + 4 <= size {
    if byte(at) != 0xFF then {
      error unreadable("JPEG", #format"there's no marker at #{ at }")
    }
    let marker := byte(at + 1)
    /// fill bytes, and markers with no segment
    if marker == 0xFF then {
      set at := at + 1
      continue _
    }
    if marker == 0xD8 or marker == 0x01 or (marker >= 0xD0 and marker <= 0xD7) then {
      set at := at + 2
      continue _
    }
    if marker == 0xD9 then {
      break _
    }
    let start := at + 4
    let end := at + 2 + uintAt(bytes, at + 2, 2, true)
    if end > size then {
      error unreadable("JPEG", "a segment runs past the end")
    }
    if marker == 0xC0 or marker == 0xC1 or marker == 0xC2 then {
      if byte(start) != 8 then {
        error unreadable("JPEG", #format"#{ byte(start) }-bit samples")
      }
      set height := uintAt(bytes, start + 1, 2, true)
      set width := uintAt(bytes, start + 3, 2, true)
      for i in 0..<byte(start + 5) {
        let c := start + 6 + i * 3
        components.push(JpegComponent{byte(c), byte(c + 1) shr 4, byte(c + 1) band 15, byte(c + 2) band 3})
      }
      if width == 0 or height == 0 or components.isEmpty() or components.any(λ(c) c.h < 1 or c.h > 4 or c.v < 1 or c.v > 4) then {
        error unreadable("JPEG", "its frame header doesn't make sense")
      }
      let (made, count) := jpegFrame(width, height, components, marker == 0xC2)
      set frame := made
      set coeffs := Bytes.filled(count * 2, 0)
    } else if marker >= 0xC3 and marker <= 0xCF and marker != 0xC4 and marker != 0xC8 and marker != 0xCC then {
      error unreadable("JPEG", "it's lossless or arithmetic-coded")
    } else if marker == 0xC4 then {
      /// each table: its class and number, 16 counts, its values - into its slot, DC 0 to 3 then AC 4 to 7
      let i := start
      for _ in Iterator.forever() while i + 17 <= end {
        let slot := (if byte(i) shr 4 == 0 then 0 else 4) + (byte(i) band 3)
        let count: U64 := 0
        for k in 0..<16 {
          set count := count + byte(i + 1 + k)
        }
        tables.copyFrom(Bytes.filled(272, 0), slot * 272)!!
        tables.copyFrom(bytes.slice(i + 1..<(i + 17 + count).min(end))!!, slot * 272)!!
        set i := i + 17 + count
      }
    } else if marker == 0xDB then {
      /// each table: its precision (8 or 16 bits) and number, then 64 values in zigzag order
      let i := start
      for _ in Iterator.forever() while i < end {
        let wide := byte(i) shr 4 != 0
        let table := byte(i) band 3
        let width := if wide then 2 else 1
        for k in 0..<64 {
          #builtin.bytesPutUint(quant, (table * 64 + jpegZigzag[k]!!) * 2, 2, #builtin.bytesUint(bytes, i + 1 + k * width, width, true), false)
        }
        set i := i + 1 + 64 * width
      }
    } else if marker == 0xDD then {
      set restart := uintAt(bytes, start, 2, true)
    } else if marker == 0xEE and end - start >= 12 and bytes.slice(start..<start + 5)!!.decode() == "Adobe" then {
      set transform := byte(start + 11)
    } else if marker == 0xDA then {
      if components.isEmpty() then {
        error unreadable("JPEG", "a scan comes before its frame")
      }
      let count := byte(start)
      let values: Array<U64> := [count]
      for i in 0..<count {
        let id := byte(start + 1 + i * 2)
        let index := components.findIndex(λ(c) c.id == id)
        if index == undefined then {
          error unreadable("JPEG", #format"a scan names component #{ id }, which the frame doesn't have")
        }
        let selectors := byte(start + 2 + i * 2)
        values.pushAll([index as U64, (selectors shr 4) band 3, selectors band 3])
      }
      let spectrum := start + 1 + count * 2
      values.pushAll([byte(spectrum), byte(spectrum + 1), byte(spectrum + 2) shr 4, byte(spectrum + 2) band 15, restart])
      let next := #builtin.jpegDecodeScan(bytes, end, frame, int32s(values), tables, coeffs)
      if next < 0.0 then {
        error unreadable("JPEG", "a scan uses a Huffman table it doesn't have")
      }
      set at := next as U64
      continue _
    }
    set at := end
  }
  if components.isEmpty() then {
    error unreadable("JPEG", "it has no frame")
  }
  /// three components are YCbCr unless Adobe says RGB or their ids spell R, G, B; four are CMYK unless Adobe says YCCK
  let ids := components.map(λ(c) c.id)
  let colors := transform ?? (if components.size() == 3 then (if ids == [82, 71, 66] then 0 else 1) else 0)
  return Image{width, height, #builtin.jpegFinish(coeffs, frame, quant, width, height, colors)}
}

/// a region of an image (RGBA, width wide) set to pixels (w x h at x, y), row by row - or cleared, when
/// pixels is undefined
local function putRegion(rgba: Bytes, width: U64, height: U64, pixels: Bytes?, x: U64, y: U64, w: U64, h: U64): Undefined {
  let rows := h.min(if y < height then height - y else 0)
  let across := w.min(if x < width then width - x else 0)
  for row in 0..<rows {
    let line := if pixels == undefined then Bytes.filled(across * 4, 0) else (pixels as Bytes).slice(row * w * 4..<(row * w + across) * 4)!!
    rgba.copyFrom(line, ((y + row) * width + x) * 4)!!
  }
}

/// every frame, composed: each drawn over what the last left, then disposed of as it says - 2 cleared
/// to transparent, 3 back to what was there before it
local function decodeGifVideo(bytes: Bytes): ParseError ! Video {
  let parts := gifParts(bytes)!!
  let video := Video.new(parts.width, parts.height, if parts.loops == undefined then 1 else (if parts.loops == 0 then 0 else (parts.loops as U64) + 1))
  let canvas := Bytes.filled(parts.width * parts.height * 4, 0)
  for frame in parts.frames {
    let before := if frame.disposal == 3 then canvas.slice(0..<canvas.size())!! else canvas
    #builtin.pixelsDraw(canvas, parts.width, parts.height, frame.rgba, frame.width, frame.height, frame.left as S64, frame.top as S64)
    /// what browsers do: a delay under 2 hundredths shows for a tenth of a second
    let seconds := if frame.delay < 2 then 0.1 else (frame.delay as F64) / 100.0
    video.add(Image{parts.width, parts.height, canvas.slice(0..<canvas.size())!!}, seconds) !? undefined
    if frame.disposal == 2 then {
      putRegion(canvas, parts.width, parts.height, undefined, frame.left, frame.top, frame.width, frame.height)
    }
    if frame.disposal == 3 then {
      set canvas := before
    }
  }
  return video
}

/// every frame, composed as APNG says: drawn over the last (blend 1) or in its place (0), then left
/// (dispose 0), cleared (1) or put back to what was there before (2). A PNG with no animation is one frame.
local function decodeApng(bytes: Bytes): ParseError ! Video {
  let parts := pngParts(bytes, [])!!
  let frames: Array<ApngFrame> := []
  let plays: U64 := 1
  let animated := false
  let at: U64 := 8
  let size := bytes.size()
  for _ in Iterator.forever() while at + 12 <= size {
    let length := uintAt(bytes, at, 4, true)
    let tag := bytes.slice(at + 4..<at + 8)!!.decode()
    let start := at + 8
    if at + 12 + length > size or tag == "IEND" then {
      break _
    }
    if tag == "acTL" then {
      set animated := true
      set plays := uintAt(bytes, start + 4, 4, true)
    }
    if tag == "fcTL" and length >= 26 then {
      let den := uintAt(bytes, start + 22, 2, true)
      let seconds := (uintAt(bytes, start + 20, 2, true) as F64) / (if den == 0 then 100.0 else den as F64)
      frames.push(ApngFrame{uintAt(bytes, start + 4, 4, true), uintAt(bytes, start + 8, 4, true), uintAt(bytes, start + 12, 4, true), uintAt(bytes, start + 16, 4, true), seconds, uintAt(bytes, start + 24, 1), uintAt(bytes, start + 25, 1), []})
    }
    /// IDAT is the first frame's only when an fcTL came before it
    if tag == "IDAT" and not frames.isEmpty() then {
      frames[frames.size() - 1]!!.data.push(bytes.slice(start..<start + length)!!)
    }
    if tag == "fdAT" and not frames.isEmpty() and length >= 4 then {
      frames[frames.size() - 1]!!.data.push(bytes.slice(start + 4..<start + length)!!)
    }
    set at := at + 12 + length
  }
  let video := Video.new(parts.width, parts.height, plays)
  if not animated or frames.isEmpty() then {
    video.add(Image{parts.width, parts.height, pngPixels(parts)!!}, 0.0) !? undefined
    return video
  }
  let canvas := Bytes.filled(parts.width * parts.height * 4, 0)
  for frame in frames {
    let before := if frame.dispose == 2 then canvas.slice(0..<canvas.size())!! else canvas
    let framed := PngParts{frame.width, frame.height, parts.depth, parts.colorType, parts.interlaced, parts.palette, parts.key, joined(frame.data)}
    let pixels := pngPixels(framed)!!
    if frame.blend == 1 then {
      #builtin.pixelsDraw(canvas, parts.width, parts.height, pixels, frame.width, frame.height, frame.left as S64, frame.top as S64)
    } else {
      putRegion(canvas, parts.width, parts.height, pixels, frame.left, frame.top, frame.width, frame.height)
    }
    video.add(Image{parts.width, parts.height, canvas.slice(0..<canvas.size())!!}, frame.seconds) !? undefined
    if frame.dispose == 1 then {
      putRegion(canvas, parts.width, parts.height, undefined, frame.left, frame.top, frame.width, frame.height)
    }
    if frame.dispose == 2 then {
      set canvas := before
    }
  }
  return video
}

/// the line from at, and the index after its newline
local function lineAt(bytes: Bytes, at: U64): (String, U64) {
  let end := bytes.indexOf("\n".encode(), at) ?? bytes.size()
  return (bytes.slice(at..<end)!!.decode(), end + 1)
}

/// 4:2:0 (any siting), 4:2:2, 4:4:4 and gray, 8 bits a sample
local function decodeY4m(bytes: Bytes): ParseError ! Video {
  let (header, start) := lineAt(bytes, 0)
  let width: U64 := 0
  let height: U64 := 0
  let num: U64 := 25
  let den: U64 := 1
  let mode: U64 := 0
  for part in header.split(" ").drop(1) {
    let kind := part.charAt(0) ?? ""
    let rest := part.slice(1..<part.size())!!
    if kind == "W" then {
      set width := U64.parse(rest) !? 0
    }
    if kind == "H" then {
      set height := U64.parse(rest) !? 0
    }
    if kind == "F" then {
      let fraction := rest.split(":")
      set num := U64.parse(fraction[0] ?? "25") !? 25
      set den := U64.parse(fraction[1] ?? "1") !? 1
    }
    if kind == "C" then {
      if rest.startsWith("420") then {
        set mode := 0
      } else if rest == "422" then {
        set mode := 1
      } else if rest == "444" then {
        set mode := 2
      } else if rest == "mono" then {
        set mode := 3
      } else {
        error unreadable("Y4M", #format"its colorspace C#{ rest }")
      }
    }
  }
  if width == 0 or height == 0 then {
    error unreadable("Y4M", "its header has no size")
  }
  let video := Video.new(width, height)
  let seconds := (den as F64) / (num.max(1) as F64)
  let at := start
  for _ in Iterator.forever() while at < bytes.size() {
    let (line, data) := lineAt(bytes, at)
    if not line.startsWith("FRAME") then {
      error unreadable("Y4M", "a frame doesn't start with FRAME")
    }
    let rgba := #builtin.yuvDecode(bytes, data, width, height, mode)
    if rgba == undefined then {
      break _
    }
    video.add(Image{width, height, rgba as Bytes}, seconds) !? undefined
    let chroma := if mode == 3 then 0 else (if mode == 2 then width else (width + 1) ÷ 2) * (if mode == 0 then (height + 1) ÷ 2 else height)
    set at := data + width * height + 2 * chroma
  }
  return video
}

/// Motion JPEG ("MJPG") or uncompressed (DIB) frames of the first video stream, at its frame rate
local function decodeAvi(bytes: Bytes): ParseError ! Video {
  let size := bytes.size()
  let width: U64 := 0
  let height: U64 := 0
  let bits: U64 := 24
  let compression := ""
  let seconds := 1.0 / 25.0
  let video: Video? := undefined
  let found := false
  let at: U64 := 12
  /// chunks and lists, depth first - a list's own chunks right after its kind
  for _ in Iterator.forever() while at + 8 <= size {
    let kind := bytes.slice(at..<at + 4)!!.decode()
    let length := uintAt(bytes, at + 4, 4)
    let start := at + 8
    if kind == "LIST" or kind == "RIFF" then {
      set at := start + 4
      continue _
    }
    if kind == "strh" and not found and bytes.slice(start..<start + 4)!!.decode() == "vids" then {
      let scale := uintAt(bytes, start + 20, 4)
      let rate := uintAt(bytes, start + 24, 4)
      if rate > 0 then {
        set seconds := (scale as F64) / (rate as F64)
      }
    }
    if kind == "strf" and not found then {
      set found := true
      set width := uintAt(bytes, start + 4, 4)
      set height := uintAt(bytes, start + 8, 4)
      set bits := uintAt(bytes, start + 14, 2)
      set compression := bytes.slice(start + 16..<start + 20)!!.decode()
      set video := Video.new(width, height, 1)
    }
    if (kind == "00dc" or kind == "00db") and video != undefined and length > 0 then {
      let data := bytes.slice(start..<(start + length).min(size))!!
      let frame := if compression == "MJPG" or compression == "mjpg" or compression == "JPEG" then decodeJpeg(data)!! else Image{width, height, unpacked(#builtin.pixelsUnpack(data, 0, width, height, if bits == 32 then LayoutBgrx else LayoutBgr, (bits * width + 31) ÷ 32 * 4, true, Bytes.filled(0, 0), -1.0), "AVI")!!}
      (video as Video).add(frame, seconds) !? undefined
    }
    set at := start + length + length % 2
  }
  if video == undefined then {
    error unreadable("AVI", "it has no video stream")
  }
  return video as Video
}

/// a duration in seconds as APNG's 16-bit numerator and denominator - 1 / n when that's what it is (1 / 30
/// for 30 fps), thousandths otherwise
local function delayFraction(seconds: F64): (U64, U64) {
  if seconds > 0.0 then {
    let inverse := 1.0 / seconds
    if (inverse - inverse.round()).abs() < 0.000001 and inverse.round() <= 65535.0 then {
      return (1, inverse.round() as U64)
    }
  }
  return ((seconds * 1000.0).round().max(0.0).min(65535.0) as U64, 1000)
}

/// a frame rate as a whole numerator and denominator - fps itself over 1 when it's whole, thousandths otherwise
local function rateFraction(fps: F64): (U64, U64) {
  if fps == fps.round() then {
    return (fps as U64, 1)
  }
  return ((fps * 1000.0).round() as U64, 1000)
}

/// NETSCAPE2.0's loop count: how many times it repeats after the first, 0 forever - nothing when it plays once
local function gifLoops(plays: U64): Bytes {
  if plays == 1 then {
    return Bytes.filled(0, 0)
  }
  let repeats := if plays == 0 then 0 else plays - 1
  return Bytes.fromArray([0x21, 0xFF, 11]) ++ "NETSCAPE2.0".encode() ++ Bytes.fromArray([3, 1]) ++ uintBytes(repeats, 2) ++ Bytes.fromArray([0])
}

/// a 4-byte big-endian number
local function word(value: U64): Bytes {
  return uintBytes(value, 4, true)
}

local function apngBytes(self: VideoEncoder): Bytes {
  let pieces: Array<Bytes> := [Bytes.fromArray([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])]
  pieces.push(pngChunk("IHDR", word(self.columns) ++ word(self.rows) ++ Bytes.fromArray([8, 6, 0, 0, 0])))
  pieces.push(pngChunk("acTL", word(self.chunks.size()) ++ word(self.plays)))
  let sequence: U64 := 0
  for data, i in self.chunks {
    /// the frame's sequence number, size and place, its delay as a fraction of a second, no disposal, drawn
    /// over nothing (source)
    let (num, den) := self.delays[i]!!
    let control := word(sequence) ++ word(self.columns) ++ word(self.rows) ++ word(0) ++ word(0) ++ uintBytes(num, 2, true) ++ uintBytes(den, 2, true) ++ Bytes.fromArray([0, 0])
    pieces.push(pngChunk("fcTL", control))
    set sequence := sequence + 1
    if i == 0 then {
      pieces.push(pngChunk("IDAT", data))
    } else {
      pieces.push(pngChunk("fdAT", word(sequence) ++ data))
      set sequence := sequence + 1
    }
  }
  pieces.push(pngChunk("IEND", Bytes.filled(0, 0)))
  return joined(pieces)
}

/// a RIFF chunk: its four letters, its size, its data - padded to an even length
local function riffChunk(kind: String, data: Bytes): Bytes {
  let padding := if data.size() % 2 == 1 then Bytes.filled(1, 0) else Bytes.filled(0, 0)
  return kind.encode() ++ uintBytes(data.size(), 4) ++ data ++ padding
}

/// a RIFF list: LIST, its size, its kind, its chunks
local function riffList(kind: String, chunks: Bytes): Bytes {
  return "LIST".encode() ++ uintBytes(chunks.size() + 4, 4) ++ kind.encode() ++ chunks
}

local function aviBytes(self: VideoEncoder): Bytes {
  let count := self.chunks.size()
  let (rate, scale) := rateFraction(self.rate)
  let largest := self.chunks.map(λ(c) c.size()).max() !? 0
  let le := λ(value, width) uintBytes(value, width)
  /// the main header: microseconds a frame, the most bytes a second, padding, AVIF_HASINDEX, the frames,
  /// none before the first, one stream, the biggest frame, the size, 4 reserved
  let mainHeader := le(((1000000.0 / self.rate).round()) as U64, 4) ++ le(largest * (self.rate.ceil() as U64), 4) ++ le(0, 4) ++ le(0x10, 4) ++ le(count, 4) ++ le(0, 4) ++ le(1, 4) ++ le(largest, 4) ++ le(self.columns, 4) ++ le(self.rows, 4) ++ Bytes.filled(16, 0)
  /// the stream's header: video, MJPG, no flags, priority and language, frames before, scale and rate (fps =
  /// rate / scale), start, length, the biggest frame, quality -1 (the default), any sample size, its rectangle
  let streamHeader := "vids".encode() ++ "MJPG".encode() ++ le(0, 4) ++ le(0, 4) ++ le(0, 4) ++ le(scale, 4) ++ le(rate, 4) ++ le(0, 4) ++ le(count, 4) ++ le(largest, 4) ++ le(0xFFFFFFFF, 4) ++ le(0, 4) ++ le(0, 2) ++ le(0, 2) ++ le(self.columns, 2) ++ le(self.rows, 2)
  /// its format: a BITMAPINFOHEADER for 24-bit MJPG frames
  let streamFormat := le(40, 4) ++ le(self.columns, 4) ++ le(self.rows, 4) ++ le(1, 2) ++ le(24, 2) ++ "MJPG".encode() ++ le(self.columns * self.rows * 3, 4) ++ Bytes.filled(16, 0)
  let headers := riffList("hdrl", riffChunk("avih", mainHeader) ++ riffList("strl", riffChunk("strh", streamHeader) ++ riffChunk("strf", streamFormat)))
  let frames: Array<Bytes> := []
  let index: Array<Bytes> := []
  /// each frame's offset from the "movi" letters, where its chunk starts
  let offset: U64 := 4
  for jpeg in self.chunks {
    let chunk := riffChunk("00dc", jpeg)
    frames.push(chunk)
    index.push("00dc".encode() ++ le(0x10, 4) ++ le(offset, 4) ++ le(jpeg.size(), 4))
    set offset := offset + chunk.size()
  }
  let movie := riffList("movi", joined(frames))
  let body := "AVI ".encode() ++ headers ++ movie ++ riffChunk("idx1", joined(index))
  return "RIFF".encode() ++ uintBytes(body.size(), 4) ++ body
}

/// the samples a format's data holds, as a Sound - or why it can't
local function soundOf(rate: U64, channels: U64, data: Bytes, offset: U64, count: U64, encoding: U64, format: String): ParseError ! Sound {
  if channels == 0 then {
    error ParseError.new(#format"not #{ format } sound this can read: it has no channels")
  }
  let samples := #builtin.pcmDecode(data, offset, count - count % channels, encoding)
  if samples == undefined then {
    error ParseError.new(#format"not #{ format } sound this can read: its samples are cut short")
  }
  return Sound{rate, channels, samples as Bytes}
}

/// a bits value made one this format can write, rounded up
local function bitsOf(bits: U8, allowed: Array<U64>): U64 {
  for b in allowed if (bits as U64) <= b {
    return b
  }
  return allowed[allowed.size() - 1]!!
}

/// PCM (8, 16, 24 and 32 bits), floats (32 and 64), A-law and mu-law - WAVE_FORMAT_EXTENSIBLE too
local function decodeWav(bytes: Bytes): ParseError ! Sound {
  let size := bytes.size()
  let format: U64 := 0
  let channels: U64 := 0
  let rate: U64 := 0
  let bits: U64 := 0
  let at: U64 := 12
  for _ in Iterator.forever() while at + 8 <= size {
    let kind := bytes.slice(at..<at + 4)!!.decode()
    let length := uintAt(bytes, at + 4, 4)
    let start := at + 8
    if kind == "fmt " and start + 16 <= size then {
      set format := uintAt(bytes, start, 2)
      set channels := uintAt(bytes, start + 2, 2)
      set rate := uintAt(bytes, start + 4, 4)
      set bits := uintAt(bytes, start + 14, 2)
      /// WAVE_FORMAT_EXTENSIBLE: the real format is its subformat GUID's first two bytes
      if format == 0xFFFE and length >= 26 then {
        set format := uintAt(bytes, start + 24, 2)
      }
    }
    if kind == "data" then {
      /// a streamed WAV's data has no length - the rest of the file
      let end := if length == 0 or length == 0xFFFFFFFF or start + length > size then size else start + length
      let encoding: U64? := if format == 1 then (if bits == 8 then EncodingUnsigned8 else if bits == 16 then EncodingInt16 else if bits == 24 then EncodingInt24 else if bits == 32 then EncodingInt32 else undefined) else if format == 3 then (if bits == 32 then EncodingFloat else if bits == 64 then EncodingDouble else undefined) else if format == 6 then EncodingALaw else if format == 7 then EncodingMuLaw else undefined
      if encoding == undefined then {
        error ParseError.new(#format"not WAV sound this can read: format #{ format } at #{ bits } bits a sample")
      }
      let width := if format == 6 or format == 7 then 1 else bits ÷ 8
      return soundOf(rate, channels, bytes, start, (end - start) ÷ width, encoding as U64, "WAV")!!
    }
    set at := start + length + length % 2
  }
  error ParseError.new("not WAV sound this can read: it has no data")
}

/// an 80-bit IEEE extended float - a sample rate
local function extendedAt(bytes: Bytes, at: U64): F64 {
  let exponent := uintAt(bytes, at, 2, true) band 0x7FFF
  let mantissa := #builtin.bytesUint(bytes, at + 2, 4, true) * 4294967296.0 + #builtin.bytesUint(bytes, at + 6, 4, true)
  if exponent == 0 and mantissa == 0.0 then {
    return 0.0
  }
  return mantissa * 2.0 ^ ((exponent as F64) - 16383.0 - 63.0)
}

/// a whole number (a sample rate) as an 80-bit IEEE extended float
local function extendedBytes(value: U64): Bytes {
  if value == 0 then {
    return Bytes.filled(10, 0)
  }
  /// the mantissa's top bit is the integer bit: shifted up until it's set
  let shift: U64 := 0
  for _ in Iterator.forever() while (value shr shift) > 1 {
    set shift := shift + 1
  }
  let mantissa := (value as F64) * 2.0 ^ ((63 - shift) as F64)
  let high := (mantissa / 4294967296.0).floor()
  return uintBytes(16383 + shift, 2, true) ++ uintBytes(high as U64, 4, true) ++ uintBytes((mantissa - high * 4294967296.0) as U64, 4, true)
}

/// AIFF (big-endian whole numbers) and AIFC (also little-endian ones, floats, A-law and mu-law)
local function decodeAiff(bytes: Bytes): ParseError ! Sound {
  let size := bytes.size()
  let channels: U64 := 0
  let bits: U64 := 0
  let rate: U64 := 0
  let compression := "NONE"
  let at: U64 := 12
  for _ in Iterator.forever() while at + 8 <= size {
    let kind := bytes.slice(at..<at + 4)!!.decode()
    let length := uintAt(bytes, at + 4, 4, true)
    let start := at + 8
    if kind == "COMM" and start + 18 <= size then {
      set channels := uintAt(bytes, start, 2, true)
      set bits := uintAt(bytes, start + 6, 2, true)
      set rate := extendedAt(bytes, start + 8).round() as U64
      if length >= 22 then {
        set compression := bytes.slice(start + 18..<start + 22)!!.decode()
      }
    }
    if kind == "SSND" then {
      let offset := uintAt(bytes, start, 4, true)
      let data := start + 8 + offset
      let end := (start + length).min(size)
      let encoding: U64? := if compression == "NONE" or compression == "twos" then (if bits <= 8 then EncodingSigned8 else if bits <= 16 then EncodingInt16Big else if bits <= 24 then EncodingInt24Big else EncodingInt32Big) else if compression == "sowt" then (if bits <= 16 then EncodingInt16 else if bits <= 24 then EncodingInt24 else EncodingInt32) else if compression == "fl32" or compression == "FL32" then EncodingFloatBig else if compression == "fl64" or compression == "FL64" then EncodingDoubleBig else if compression == "alaw" or compression == "ALAW" then EncodingALaw else if compression == "ulaw" or compression == "ULAW" then EncodingMuLaw else undefined
      if encoding == undefined then {
        error ParseError.new(#format"not AIFF sound this can read: compression #{ compression }")
      }
      let width: U64 := ([1, 1, 2, 2, 3, 3, 4, 4, 4, 4, 8, 8, 1, 1])[encoding as U64]!!
      return soundOf(rate, channels, bytes, data, if end > data then (end - data) ÷ width else 0, encoding as U64, "AIFF")!!
    }
    set at := start + length + length % 2
  }
  error ParseError.new("not AIFF sound this can read: it has no sound data")
}

/// mu-law, 8 to 32-bit whole numbers, floats, doubles and A-law - big-endian
local function decodeAu(bytes: Bytes): ParseError ! Sound {
  if bytes.size() < 24 then {
    error ParseError.new("not AU sound this can read: its header is cut short")
  }
  let offset := uintAt(bytes, 4, 4, true)
  let length := uintAt(bytes, 8, 4, true)
  let kind := uintAt(bytes, 12, 4, true)
  let rate := uintAt(bytes, 16, 4, true)
  let channels := uintAt(bytes, 20, 4, true)
  let encodings: Array<U64> := [99, EncodingMuLaw, EncodingSigned8, EncodingInt16Big, EncodingInt24Big, EncodingInt32Big, EncodingFloatBig, EncodingDoubleBig]
  let encoding := if kind == 27 then EncodingALaw else if kind >= 1 and kind <= 7 then encodings[kind]!! else 99
  if encoding == 99 then {
    error ParseError.new(#format"not AU sound this can read: encoding #{ kind }")
  }
  let width: U64 := ([1, 1, 2, 2, 3, 3, 4, 4, 4, 4, 8, 8, 1, 1])[encoding]!!
  let end := if length == 0xFFFFFFFF or offset + length > bytes.size() then bytes.size() else offset + length
  return soundOf(rate, channels, bytes, offset, if end > offset then (end - offset) ÷ width else 0, encoding, "AU")!!
}

/// STREAMINFO's rate, channels, bits a sample and total samples, then every frame
local function decodeFlac(bytes: Bytes): ParseError ! Sound {
  let size := bytes.size()
  let at: U64 := 4
  let rate: U64 := 0
  let channels: U64 := 0
  let bits: U64 := 0
  let total: U64 := 0
  for _ in Iterator.forever() while at + 4 <= size {
    let header := uintAt(bytes, at, 1)
    let length := uintAt(bytes, at + 1, 3, true)
    if header band 0x7F == 0 and length >= 34 then {
      /// 20 bits of rate, 3 of channels less 1, 5 of bits less 1, 36 of total samples
      let packed := at + 4 + 10
      set rate := uintAt(bytes, packed, 3, true) shr 4
      set channels := ((uintAt(bytes, packed + 2, 1) shr 1) band 7) + 1
      set bits := (((uintAt(bytes, packed + 2, 1) band 1) shl 4) bor (uintAt(bytes, packed + 3, 1) shr 4)) + 1
      set total := ((uintAt(bytes, packed + 3, 1) band 15) shl 32) + uintAt(bytes, packed + 4, 4, true)
    }
    set at := at + 4 + length
    if header band 0x80 != 0 then {
      break _
    }
  }
  if channels == 0 or rate == 0 then {
    error ParseError.new("not FLAC sound this can read: it has no STREAMINFO")
  }
  let samples := #builtin.flacDecode(bytes, at, channels, bits, total)
  if samples == undefined then {
    error ParseError.new("not FLAC sound this can read: its frames are broken")
  }
  return Sound{rate, channels, samples as Bytes}
}

@async
local function retryAfter<Type>(left: U64, start: Lambda<(), Promise<Type>>, wait: Duration): Promise<Type> {
  let value := await start()
  if not value.is<Error>() or left <= 1 or &cancellation.isCancelled() then { return value }
  await Promise.sleep(wait)
  if &cancellation.isCancelled() then { return value }
  return await retryAfter(left - 1, start, wait.scale(2.0))
}

global method is for Unknown<Target>(self: Unknown): Boolean {
  return Target.isAssignableFrom(self.typeOf())
}

global method narrow for Unknown<Target>(self: Unknown): CastError ! Target {
  if not self.is<Target>() then { error CastError.new("value is a " ++ self.typeOf().name() ++ ", not a " ++ Target.name()) }
  return self as Target
}

global method typeOf for Unknown(self: Unknown): Type {
  return #runtime.typeof(self)
}

method equals(self: Undefined, other: Undefined): Boolean {
  return true
}

method hash(self: Undefined): U64 {
  return &hashSeed
}

method toString(self: Undefined): String {
  return "undefined"
}

function default(): Undefined {
  return undefined
}

/// "Array<U8>"
global method name for Type(self: Type): String {
  return #comptime.typeName(self)
}

global method generics for Type(self: Type): Array<Type> {
  return #comptime.typeGenerics(self)
}

global method implements for Type(self: Type, interface: Interface): Boolean {
  return #comptime.implements(self, interface)
}

global method isAssignableFrom for Type(self: Type, other: Type): Boolean {
  return #comptime.isAssignable(self, other)
}

global method fields for Type(self: Type): Map<String, Type> {
  return #comptime.typeFields(self)
}

global method variants for Type(self: Type): Array<Type> {
  return #comptime.typeVariants(self)
}

global method size for Type(self: Type): U64 {
  return #comptime.sizeOf(self)
}

global function of for Type(value: Unknown): Type {
  return value.typeOf()
}

/// the type written as name - "Point", "Shape.Circle" - found when it's used, like a value's own type
global function named for Type(name: String): Type {
  return #comptime.typeNamed(name)
}

method equals(self: Type, other: Type): Boolean {
  return #comptime.sameType(self, other)
}

method hash(self: Type): U64 {
  return self.name().hash()
}

method toString(self: Type): String {
  return self.name()
}

global method implies for Boolean(self: Boolean, other: Boolean): Boolean {
  return not self or other
}

global method toTrilean for Boolean(self: Boolean): Trilean {
  return self ? true : false
}

method equals(self: Boolean, other: Boolean): Boolean {
  return #builtin.intrinsic.EQ_BOOLEAN_BOOLEAN(self, other)
}

method hash(self: Boolean): U64 {
  return hashCombine(&hashSeed, self ? 1 : 0)
}

method compare(self: Boolean, other: Boolean): Ordering {
  return #builtin.intrinsic.CMP_BOOLEAN_BOOLEAN(self, other)
}

method toString(self: Boolean): String {
  return self ? "true" : "false"
}

function parse(text: String): ParseError ! Boolean {
  if text == "true" then { return true }
  if text == "false" then { return false }
  error ParseError.new("expected \"true\" or \"false\", got \"" ++ text ++ "\"")
}

method not(self: Boolean): Boolean {
  return #builtin.intrinsic.NOT_BOOLEAN(self)
}

/// the operator only evaluates b when a is true - this method is what it calls once it has both
method and(self: Boolean, other: Boolean): Boolean {
  return #builtin.intrinsic.AND_BOOLEAN_BOOLEAN(self, other)
}

/// the operator only evaluates b when a is false
method or(self: Boolean, other: Boolean): Boolean {
  return #builtin.intrinsic.OR_BOOLEAN_BOOLEAN(self, other)
}

method xor(self: Boolean, other: Boolean): Boolean {
  return #builtin.intrinsic.XOR_BOOLEAN_BOOLEAN(self, other)
}

method iff(self: Boolean, other: Boolean): Boolean {
  return #builtin.intrinsic.IFF_BOOLEAN_BOOLEAN(self, other)
}

function default(): Boolean {
  return false
}

global method isKnown for Trilean(self: Trilean): Boolean {
  return self != null
}

global method toBoolean for Trilean(self: Trilean): Boolean? {
  return self == null ? undefined : self == true
}

global method orElse for Trilean(self: Trilean, fallback: Boolean): Boolean {
  return self.toBoolean() ?? fallback
}

/// both the same Boolean, or both null
method equals(self: Trilean, other: Trilean): Boolean {
  if self is Boolean and other is Boolean then { return (self as Boolean).equals(other as Boolean) }
  return not (self is Boolean) and not (other is Boolean)
}

method hash(self: Trilean): U64 {
  return hashCombine(&hashSeed, self == null ? 2 : self == true ? 1 : 0)
}

method toString(self: Trilean): String {
  return self == null ? "null" : self == true ? "true" : "false"
}

function parse(text: String): ParseError ! Trilean {
  if text == "null" then { return null }
  return Boolean.parse(text)!!
}

method not(self: Trilean): Trilean {
  return self == null ? null : self == false
}

method and(self: Trilean, other: Trilean): Trilean {
  if self == false or other == false then { return false }
  if self == null or other == null then { return null }
  return true
}

method or(self: Trilean, other: Trilean): Trilean {
  if self == true or other == true then { return true }
  if self == null or other == null then { return null }
  return false
}

method xor(self: Trilean, other: Trilean): Trilean {
  if self == null or other == null then { return null }
  return self != other
}

method iff(self: Trilean, other: Trilean): Trilean {
  if self == null or other == null then { return null }
  return self == other
}

function default(): Trilean {
  return null
}

global method reverse for Ordering(self: Ordering): Ordering {
  match self {
    case Ordering.Less then { return Ordering.Greater }
    case Ordering.Greater then { return Ordering.Less }
    case _ then { return Ordering.Equal }
  }
}

global method then for Ordering(self: Ordering, other: Ordering): Ordering {
  return self == Ordering.Equal ? other : self
}

global method thenBy for Ordering(self: Ordering, next: Lambda<(), Ordering>): Ordering {
  return self == Ordering.Equal ? next() : self
}

global method isLess for Ordering(self: Ordering): Boolean {
  return self == Ordering.Less
}

global method isEqual for Ordering(self: Ordering): Boolean {
  return self == Ordering.Equal
}

global method isGreater for Ordering(self: Ordering): Boolean {
  return self == Ordering.Greater
}

global method toInteger for Ordering(self: Ordering): S8 {
  return self.isLess() ? -1 : self.isGreater() ? 1 : 0
}

global function of for Ordering<T: Comparable>(a: T, b: T): Ordering {
  return a.compare(b)
}

method equals(self: Ordering, other: Ordering): Boolean {
  return self.index() == other.index()
}

method hash(self: Ordering): U64 {
  return hashCombine(&hashSeed, self.index())
}

method compare(self: Ordering, other: Ordering): Ordering {
  return self.index().compare(other.index())
}

method toString(self: Ordering): String {
  return self.variantName()
}

local function isSigned for IntegerTypes(): Boolean {
  return Self.name().startsWith("S")
}

/// a U16 - U256's 256 doesn't fit a U8
global function bits for IntegerTypes(): U16 {
  return (Self.size() * 8) as U16
}

/// a shl / shr count brought down to one that fits in Self and means the same - bits itself at most,
/// which the intrinsic shifts every bit out by
local function shiftCount for IntegerTypes(count: U64): Self {
  return count.min(Self.bits() as U64) as Self
}

global method abs for IntegerTypes(self: Self): Self {
  return #builtin.intrinsic.ABS_Self(self)
}

global method sign for IntegerTypes(self: Self): S8 {
  return self > 0 ? 1 : self < 0 ? -1 : 0
}

global method isZero for IntegerTypes(self: Self): Boolean {
  return self == 0
}

global method isPositive for IntegerTypes(self: Self): Boolean {
  return self > 0
}

global method isNegative for IntegerTypes(self: Self): Boolean {
  return self < 0
}

global method isEven for IntegerTypes(self: Self): Boolean {
  return (self band 1) == 0
}

global method isOdd for IntegerTypes(self: Self): Boolean {
  return (self band 1) == 1
}

global method min for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.MIN_Self_Self(self, other)
}

global method max for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.MAX_Self_Self(self, other)
}

global method clamp for IntegerTypes(self: Self, range: Range<Self>): Self {
  return range.clamp(self)
}

/// square-and-multiply - log2(exponent) multiplications, an OverflowError when one doesn't fit
global method pow for IntegerTypes(self: Self, exponent: U32): Self {
  let result: Self := 1
  let base := self
  let remaining := exponent
  for _ in forever() while remaining > 0 {
    if remaining.isOdd() then { set result *= base }
    set remaining := remaining shr 1
    if remaining > 0 then { set base *= base }
  }
  return result
}

/// Newton's method from a power of two at or above the root - converges downward
global method sqrt for IntegerTypes(self: Self): CastError ! Self {
  if self < 0 then { error CastError.new("no integer square root of " ++ self.toString()) }
  if self < 2 then { return self }
  let used := Self.bits() - (self.leadingZeros() as U16)
  let x := (1 as Self).shl(((used + 1) / 2) as U64)
  for _ in forever() {
    let y := (x + self / x) / 2
    if y >= x then { return x }
    set x := y
  }
}

/// Euclid's algorithm - always non-negative
global method gcd for IntegerTypes(self: Self, other: Self): Self {
  let a := self.abs()
  let b := other.abs()
  for _ in forever() while b != 0 {
    let rest := a % b
    set a := b
    set b := rest
  }
  return a
}

global method lcm for IntegerTypes(self: Self, other: Self): Self {
  if self == 0 or other == 0 then { return 0 }
  return (self / self.gcd(other) * other).abs()
}

global method divMod for IntegerTypes(self: Self, other: Self): (Self, Self) {
  return (self // other, self % other)
}

global method modulo for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.MOD_Self_Self(self, other)
}

global method checkedAdd for IntegerTypes(self: Self, other: Self): OverflowError ! Self {
  return #builtin.intrinsic.ADD_CHECKED_Self_Self(self, other)
}

global method checkedSubtract for IntegerTypes(self: Self, other: Self): OverflowError ! Self {
  return #builtin.intrinsic.SUB_CHECKED_Self_Self(self, other)
}

global method checkedMultiply for IntegerTypes(self: Self, other: Self): OverflowError ! Self {
  return #builtin.intrinsic.MUL_CHECKED_Self_Self(self, other)
}

global method wrappingAdd for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.ADD_WRAPPING_Self_Self(self, other)
}

global method wrappingSubtract for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.SUB_WRAPPING_Self_Self(self, other)
}

global method wrappingMultiply for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.MUL_WRAPPING_Self_Self(self, other)
}

global method saturatingAdd for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.ADD_SATURATING_Self_Self(self, other)
}

global method saturatingSubtract for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.SUB_SATURATING_Self_Self(self, other)
}

global method saturatingMultiply for IntegerTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.MUL_SATURATING_Self_Self(self, other)
}

global method rotateLeft for IntegerTypes(self: Self, count: U8): Self {
  return #builtin.intrinsic.ROTL_Self_Self(self, ((count as U16) % Self.bits()) as Self)
}

global method rotateRight for IntegerTypes(self: Self, count: U8): Self {
  return #builtin.intrinsic.ROTR_Self_Self(self, ((count as U16) % Self.bits()) as Self)
}

global method countOnes for IntegerTypes(self: Self): U8 {
  return #builtin.intrinsic.POPCNT_Self(self)
}

global method countZeros for IntegerTypes(self: Self): U8 {
  return (Self.bits() - (self.countOnes() as U16)) as U8
}

global method leadingZeros for IntegerTypes(self: Self): U8 {
  return #builtin.intrinsic.CLZ_Self(self)
}

global method trailingZeros for IntegerTypes(self: Self): U8 {
  return #builtin.intrinsic.CTZ_Self(self)
}

global method isPowerOfTwo for IntegerTypes(self: Self): Boolean {
  return self > 0 and (self band (self - 1)) == 0
}

global method bit for IntegerTypes(self: Self, index: U8): Boolean {
  return (self.shr(index as U64) band 1) == 1
}

global method withBit for IntegerTypes(self: Self, index: U8, value: Boolean): Self {
  let mask := (1 as Self).shl(index as U64)
  return value ? self bor mask : self band ~mask
}

/// a signed value's bytes come from it as an S256 - 0xFF doesn't fit an S8, and its shr keeps the sign
global method toBytes for IntegerTypes(self: Self): Bytes {
  let count := (Self.bits() / 8) as U64
  let bytes := Bytes.filled(count)
  for i in 0..<count {
    set bytes[i] := Self.isSigned() ? ((self as S256).shr(i * 8) band 0xFF) as U8 : (self.shr(i * 8) band 0xFF) as U8
  }
  return bytes
}

/// two's complement for S* - the top byte's high bit counts negative
global function fromBytes for IntegerTypes(bytes: Bytes): ParseError ! Self {
  let count := (Self.bits() / 8) as U64
  if bytes.size() != count then { error ParseError.new("a " ++ Self.name() ++ " needs exactly " ++ count.toString() ++ " bytes") }
  if Self.isSigned() then {
    let signed: S256 := 0
    for byte, i in bytes {
      set signed := signed + ((byte as S256) - (i + 1 == count and byte >= 128 ? 256 : 0)).shl(i * 8)
    }
    return signed as Self
  }
  let result: Self := 0
  for byte, i in bytes {
    set result := result bor (byte as Self).shl(i * 8)
  }
  return result
}

global method toFloat for IntegerTypes(self: Self): Float {
  return self as Float
}

global method toBigInteger for IntegerTypes(self: Self): BigInteger {
  return BigInteger.parse(self.toString())!!
}

global method toCodepoint for IntegerTypes(self: Self): CastError ! Codepoint {
  return Codepoint.fromU32(self.checkedCast<U32>()!!)
}

/// `as`, with a CastError where it gives an OverflowError
global method checkedCast for IntegerTypes<Target>(self: Self): CastError ! Target {
  match self as Target {
    case Error then { error CastError.new(self.toString() ++ " doesn't fit in a " ++ Target.name()) }
    case result then { return result }
  }
}

method equals(self: Self, other: Self): Boolean {
  return #builtin.intrinsic.EQ_Self_Self(self, other)
}

method hash(self: Self): U64 {
  return hashBytes(self.toBytes())
}

method compare(self: Self, other: Self): Ordering {
  return #builtin.intrinsic.CMP_Self_Self(self, other)
}

/// the sign bit alone for S*, 0 for U*
function min(): Self {
  return Self.isSigned() ? (1 as Self).shl((Self.bits() - 1) as U64) : 0
}

/// every bit but the sign bit for S*, every bit for U*
function max(): Self {
  return ~Self.min()
}

/// digits come out least significant first; a negative value divides toward zero, so the
/// remainders are negative too and abs() fixes each one - S*.min() is never negated whole
method toString(self: Self, radix: U8 := 10): String {
  if self == 0 then { return "0" }
  let base := radix as Self
  let digits: Array<Codepoint> := []
  let rest := self
  for _ in forever() while rest != 0 {
    digits.push(digitChar((rest % base).abs() as U8))
    set rest := rest / base
  }
  if self < 0 then { digits.push('-') }
  return String.fromCodepoints(digits.reverse())
}

/// accumulates toward the sign it ends with, so S*.min() parses without overflowing
function parse(text: String, radix: U8 := 10): ParseError ! Self {
  if radix < 2 or radix > 36 then { error ParseError.new("radix must be from 2 to 36") }
  let trimmed := text.trim().replaceAll("_", "")
  let negative := trimmed.startsWith("-")
  let digits := trimmed.stripPrefix("-") ?? trimmed.stripPrefix("+") ?? trimmed
  if digits.isEmpty() or (negative and not Self.isSigned()) then { error ParseError.new("not a " ++ Self.name() ++ ": " ++ text) }
  let base := radix as Self
  let result: Self := 0
  for c in digits {
    let digit := ((c.digitValue(radix) ?! ParseError.new("not a base-" ++ radix.toString() ++ " digit: " ++ c.toString()))!!) as Self
    let shifted := result.checkedMultiply(base) !? undefined
    let next := negative ? shifted?.checkedSubtract(digit) : shifted?.checkedAdd(digit)
    set result := ((next ?? undefined) ?! ParseError.new(text ++ " doesn't fit in a " ++ Self.name()))!!
  }
  return result
}

function zero(): Self {
  return 0
}

function one(): Self {
  return 1
}

method add(self: Self, other: Self): Self {
  return #builtin.intrinsic.ADD_Self_Self(self, other)
}

method subtract(self: Self, other: Self): Self {
  return #builtin.intrinsic.SUB_Self_Self(self, other)
}

method multiply(self: Self, other: Self): Self {
  return #builtin.intrinsic.MUL_Self_Self(self, other)
}

method divide(self: Self, other: Self): Self {
  return #builtin.intrinsic.DIV_Self_Self(self, other)
}

method floorDivide(self: Self, other: Self): Self {
  return #builtin.intrinsic.FLOORDIV_Self_Self(self, other)
}

method remainder(self: Self, other: Self): Self {
  return #builtin.intrinsic.REM_Self_Self(self, other)
}

method power(self: Self, exponent: Self): Self {
  return #builtin.intrinsic.POW_Self_Self(self, exponent)
}

method negate(self: Self): Self {
  return #builtin.intrinsic.NEG_Self(self)
}

method plus(self: Self): Self {
  return self
}

method bor(self: Self, other: Self): Self {
  return #builtin.intrinsic.BOR_Self_Self(self, other)
}

method bxor(self: Self, other: Self): Self {
  return #builtin.intrinsic.BXOR_Self_Self(self, other)
}

method band(self: Self, other: Self): Self {
  return #builtin.intrinsic.BAND_Self_Self(self, other)
}

method bnot(self: Self): Self {
  return #builtin.intrinsic.BNOT_Self(self)
}

method shl(self: Self, count: U64): Self {
  return #builtin.intrinsic.SHL_Self_Self(self, Self.shiftCount(count))
}

method shr(self: Self, count: U64): Self {
  return #builtin.intrinsic.SHR_Self_Self(self, Self.shiftCount(count))
}

method next(self: Self): Self {
  return self + 1
}

method previous(self: Self): Self {
  return self - 1
}

method cast(self: Self): Target {
  if Target == Self then { return self }
  return #builtin.intrinsic.CAST_Self_Target(self)
}

function default(): Self {
  return 0
}

/// stored mantissa bits, and the largest exponent - IEEE-754 binary16, binary32, binary64
local function mantissaBits for FloatTypes(): U8 {
  return Self == F16 ? 10 : Self == F32 ? 23 : 52
}

local function maxExponent for FloatTypes(): U16 {
  return Self == F16 ? 15 : Self == F32 ? 127 : 1023
}

global function epsilon for FloatTypes(): Self {
  return (2 as Self).power(-(Self.mantissaBits() as Self))
}

global function infinity for FloatTypes(): Self {
  return 1.0 / 0.0
}

global function nan for FloatTypes(): Self {
  return 0.0 / 0.0
}

/// more digits than F64 holds - the literal rounds to Self
global function pi for FloatTypes(): Self {
  return 3.141592653589793238462643383279502884197169399375105820974944592307816406286
}

global function e for FloatTypes(): Self {
  return 2.718281828459045235360287471352662497757247093699959574966967627724076630354
}

global function tau for FloatTypes(): Self {
  return 2 * Self.pi()
}

global method abs for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.ABS_Self(self)
}

global method sign for FloatTypes(self: Self): Self {
  if self.isNaN() then { return self }
  return self > 0 ? 1.0 : self < 0 ? -1.0 : 0.0
}

global method isNaN for FloatTypes(self: Self): Boolean {
  return #builtin.intrinsic.ISNAN_Self(self)
}

global method isInfinite for FloatTypes(self: Self): Boolean {
  return #builtin.intrinsic.ISINF_Self(self)
}

global method isFinite for FloatTypes(self: Self): Boolean {
  return not self.isNaN() and not self.isInfinite()
}

global method isInteger for FloatTypes(self: Self): Boolean {
  return self.isFinite() and self == self.truncate()
}

global method min for FloatTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.MIN_Self_Self(self, other)
}

global method max for FloatTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.MAX_Self_Self(self, other)
}

global method clamp for FloatTypes(self: Self, range: Range<Self>): Self {
  return range.clamp(self)
}

global method approxEquals for FloatTypes(self: Self, other: Self, tolerance: Self := Self.epsilon()): Boolean {
  return (self - other).abs() <= tolerance
}

global method floor for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.FLOOR_Self(self)
}

global method ceil for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.CEIL_Self(self)
}

global method round for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.ROUND_Self(self)
}

global method roundHalfEven for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.ROUNDEVEN_Self(self)
}

global method truncate for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.TRUNC_Self(self)
}

global method fraction for FloatTypes(self: Self): Self {
  return self - self.truncate()
}

global method roundTo for FloatTypes(self: Self, digits: U8): Self {
  let factor := (10 as Self).power(digits as Self)
  return (self * factor).round() / factor
}

global method sqrt for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.SQRT_Self(self)
}

global method cbrt for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.CBRT_Self(self)
}

global method exp for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.EXP_Self(self)
}

global method ln for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.LN_Self(self)
}

global method log for FloatTypes(self: Self, base: Self): Self {
  return self.ln() / base.ln()
}

global method log2 for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.LOG2_Self(self)
}

global method log10 for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.LOG10_Self(self)
}

global method hypot for FloatTypes(self: Self, other: Self): Self {
  return #builtin.intrinsic.HYPOT_Self_Self(self, other)
}

global method sin for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.SIN_Self(self)
}

global method cos for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.COS_Self(self)
}

global method tan for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.TAN_Self(self)
}

global method asin for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.ASIN_Self(self)
}

global method acos for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.ACOS_Self(self)
}

global method atan for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.ATAN_Self(self)
}

global method atan2 for FloatTypes(self: Self, x: Self): Self {
  return #builtin.intrinsic.ATAN2_Self_Self(self, x)
}

global method sinh for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.SINH_Self(self)
}

global method cosh for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.COSH_Self(self)
}

global method tanh for FloatTypes(self: Self): Self {
  return #builtin.intrinsic.TANH_Self(self)
}

global method toRadians for FloatTypes(self: Self): Self {
  return self * Self.pi() / 180
}

global method toDegrees for FloatTypes(self: Self): Self {
  return self * 180 / Self.pi()
}

/// fused, so t = 1 lands exactly on to
global method lerp for FloatTypes(self: Self, to: Self, t: Self): Self {
  return #builtin.intrinsic.FMA_Self_Self_Self(to - self, t, self)
}

global method toInteger for FloatTypes(self: Self): CastError ! Integer {
  return #builtin.intrinsic.CAST_Self_S64(self)
}

/// the sign bit is cleared by abs() alone, so comparing bits tells -0.0 from 0.0 - which < can't
global method ulpDistance for FloatTypes(self: Self, other: Self): U256? {
  if self.isNaN() or other.isNaN() then { return undefined }
  let a := self.abs().toBits() as U256
  let b := other.abs().toBits() as U256
  let sameSign := (self.toBits() == self.abs().toBits()) == (other.toBits() == other.abs().toBits())
  return sameSign ? (a > b ? a - b : b - a) : a + b
}

global method toBits for FloatTypes(self: Self): Bits {
  return #builtin.intrinsic.BITCAST_Self_Bits(self)
}

global function fromBits for FloatTypes(bits: Bits): Self {
  return #builtin.intrinsic.BITCAST_Bits_Self(bits)
}

/// IEEE-754 equality - NaN equals nothing, 0.0 equals -0.0
method equals(self: Self, other: Self): Boolean {
  return #builtin.intrinsic.EQ_Self_Self(self, other)
}

/// equal values hash the same: only 0.0 and -0.0 are equal without being the same bits, so they share one
method hash(self: Self): U64 {
  let normalized := self == 0 ? 0.0 : self
  return hashBytes(normalized.toBits().toBytes())
}

/// a total order - NaN after everything, and Equal for == values, like the intrinsic
method compare(self: Self, other: Self): Ordering {
  return #builtin.intrinsic.CMP_Self_Self(self, other)
}

function min(): Self {
  return -Self.max()
}

/// the largest mantissa at the largest exponent - (2 - epsilon) * 2^maxExponent
function max(): Self {
  return (2 - Self.epsilon()) * (2 as Self).power(Self.maxExponent() as Self)
}

/// "NaN", "Infinity" and "-Infinity" for the special values
method toString(self: Self, precision: U8?): String {
  return #builtin.formatFloat(self, precision)
}

function parse(text: String): ParseError ! Self {
  return #builtin.parseFloat<Self>(text)
}

function zero(): Self {
  return 0.0
}

function one(): Self {
  return 1.0
}

method add(self: Self, other: Self): Self {
  return #builtin.intrinsic.ADD_Self_Self(self, other)
}

method subtract(self: Self, other: Self): Self {
  return #builtin.intrinsic.SUB_Self_Self(self, other)
}

method multiply(self: Self, other: Self): Self {
  return #builtin.intrinsic.MUL_Self_Self(self, other)
}

method divide(self: Self, other: Self): Self {
  return #builtin.intrinsic.DIV_Self_Self(self, other)
}

method floorDivide(self: Self, other: Self): Self {
  return #builtin.intrinsic.FLOORDIV_Self_Self(self, other)
}

method remainder(self: Self, other: Self): Self {
  return #builtin.intrinsic.REM_Self_Self(self, other)
}

method power(self: Self, exponent: Self): Self {
  return #builtin.intrinsic.POW_Self_Self(self, exponent)
}

method negate(self: Self): Self {
  return #builtin.intrinsic.NEG_Self(self)
}

method plus(self: Self): Self {
  return self
}

method cast(self: Self): Target {
  if Target == Self then { return self }
  return #builtin.intrinsic.CAST_Self_Target(self)
}

function default(): Self {
  return 0.0
}

global function new for ComplexTypes(real: Part, imaginary: Part): Self {
  return Self{realPart := real, imaginaryPart := imaginary}
}

global function fromPolar for ComplexTypes(magnitude: Part, angle: Part): Self {
  return Self.new(magnitude * angle.cos(), magnitude * angle.sin())
}

global function i for ComplexTypes(): Self {
  return Self.new(0, 1)
}

global method real for ComplexTypes(self: Self): Part {
  return self.realPart
}

global method imaginary for ComplexTypes(self: Self): Part {
  return self.imaginaryPart
}

global method magnitude for ComplexTypes(self: Self): Part {
  return self.real().hypot(self.imaginary())
}

global method magnitudeSquared for ComplexTypes(self: Self): Part {
  return self.real() * self.real() + self.imaginary() * self.imaginary()
}

global method argument for ComplexTypes(self: Self): Part {
  return self.imaginary().atan2(self.real())
}

global method toPolar for ComplexTypes(self: Self): (Part, Part) {
  return (self.magnitude(), self.argument())
}

global method conjugate for ComplexTypes(self: Self): Self {
  return Self.new(self.real(), -self.imaginary())
}

global method reciprocal for ComplexTypes(self: Self): Self {
  return self.conjugate().scale(1 / self.magnitudeSquared())
}

/// the principal root - half the angle, the root of the magnitude
global method sqrt for ComplexTypes(self: Self): Self {
  return Self.fromPolar(self.magnitude().sqrt(), self.argument() / 2)
}

global method exp for ComplexTypes(self: Self): Self {
  return Self.fromPolar(self.real().exp(), self.imaginary())
}

global method ln for ComplexTypes(self: Self): Self {
  return Self.new(self.magnitude().ln(), self.argument())
}

global method isReal for ComplexTypes(self: Self): Boolean {
  return self.imaginary() == 0
}

global method isNaN for ComplexTypes(self: Self): Boolean {
  return self.real().isNaN() or self.imaginary().isNaN()
}

global method approxEquals for ComplexTypes(self: Self, other: Self, tolerance: Part := Part.epsilon()): Boolean {
  return (self - other).magnitude() <= tolerance
}

method equals(self: Self, other: Self): Boolean {
  return #builtin.intrinsic.EQ_Self_Self(self, other)
}

method hash(self: Self): U64 {
  return hashCombine(self.real().hash(), self.imaginary().hash())
}

/// "1+2i", "1-2i"
method toString(self: Self): String {
  let sign := self.imaginary() < 0 ? "-" : "+"
  return self.real().toString() ++ sign ++ self.imaginary().abs().toString() ++ "i"
}

/// "a", "bi", "a+bi", "a-bi" - the sign between the parts is what splits them
function parse(text: String): ParseError ! Self {
  let trimmed := text.trim().replaceAll(" ", "")
  if not trimmed.endsWith("i") then { return Self.new(Part.parse(trimmed)!!, 0) }
  let body := trimmed.slice(0..<(trimmed.size() - 1)) !? ""
  let split := body.lastIndexOf(Regex("(?<=[0-9.])[+-]")!!)
  if split == undefined then { return Self.new(0, body == "" or body == "+" ? 1 : body == "-" ? -1 : Part.parse(body)!!) }
  let real := Part.parse(body.slice(0..<split) !? "")!!
  let rest := body.slice(split..<body.size()) !? ""
  let imaginary := rest == "+" ? 1 : rest == "-" ? -1 : Part.parse(rest)!!
  return Self.new(real, imaginary)
}

function zero(): Self {
  return Self.new(0, 0)
}

function one(): Self {
  return Self.new(1, 0)
}

method add(self: Self, other: Self): Self {
  return #builtin.intrinsic.ADD_Self_Self(self, other)
}

method subtract(self: Self, other: Self): Self {
  return #builtin.intrinsic.SUB_Self_Self(self, other)
}

method multiply(self: Self, other: Self): Self {
  return #builtin.intrinsic.MUL_Self_Self(self, other)
}

method divide(self: Self, other: Self): Self {
  return #builtin.intrinsic.DIV_Self_Self(self, other)
}

/// floors each part of the quotient
method floorDivide(self: Self, other: Self): Self {
  let quotient := self / other
  return Self.new(quotient.real().floor(), quotient.imaginary().floor())
}

method remainder(self: Self, other: Self): Self {
  return self - other * self.floorDivide(other)
}

method power(self: Self, exponent: Self): Self {
  return #builtin.intrinsic.POW_Self_Self(self, exponent)
}

method negate(self: Self): Self {
  return #builtin.intrinsic.NEG_Self(self)
}

method plus(self: Self): Self {
  return self
}

method scale(self: Self, factor: Part): Self {
  return Self.new(self.real() * factor, self.imaginary() * factor)
}

method cast(self: Self): Target {
  if Target == Self then { return self }
  return #builtin.intrinsic.CAST_Self_Target(self)
}

function default(): Self {
  return Self.new(0, 0)
}

global function new for QuaternionTypes(w: Part, x: Part, y: Part, z: Part): Self {
  return Self{wPart := w, xPart := x, yPart := y, zPart := z}
}

global function identity for QuaternionTypes(): Self {
  return Self.new(1, 0, 0, 0)
}

global function fromAxisAngle for QuaternionTypes(axis: Vector<Part, 3>, angle: Part): Self {
  let unit := axis.normalize()
  let half := angle / 2
  let s := half.sin()
  return Self.new(half.cos(), unit.x() * s, unit.y() * s, unit.z() * s)
}

/// rotations about x (roll), then y (pitch), then z (yaw)
global function fromEuler for QuaternionTypes(roll: Part, pitch: Part, yaw: Part): Self {
  let (cr, sr) := ((roll / 2).cos(), (roll / 2).sin())
  let (cp, sp) := ((pitch / 2).cos(), (pitch / 2).sin())
  let (cy, sy) := ((yaw / 2).cos(), (yaw / 2).sin())
  return Self.new(
    cr * cp * cy + sr * sp * sy,
    sr * cp * cy - cr * sp * sy,
    cr * sp * cy + sr * cp * sy,
    cr * cp * sy - sr * sp * cy,
  )
}

global method w for QuaternionTypes(self: Self): Part {
  return self.wPart
}

global method x for QuaternionTypes(self: Self): Part {
  return self.xPart
}

global method y for QuaternionTypes(self: Self): Part {
  return self.yPart
}

global method z for QuaternionTypes(self: Self): Part {
  return self.zPart
}

global method scalar for QuaternionTypes(self: Self): Part {
  return self.w()
}

global method vector for QuaternionTypes(self: Self): Vector<Part, 3> {
  return Vector<Part, 3>.fromArray([self.x(), self.y(), self.z()]) !? Vector<Part, 3>.zero()
}

global method magnitude for QuaternionTypes(self: Self): Part {
  return self.dot(self).sqrt()
}

global method normalize for QuaternionTypes(self: Self): Self {
  return self.scale(1 / self.magnitude())
}

global method conjugate for QuaternionTypes(self: Self): Self {
  return Self.new(self.w(), -self.x(), -self.y(), -self.z())
}

global method inverse for QuaternionTypes(self: Self): Self {
  return self.conjugate().scale(1 / self.dot(self))
}

global method dot for QuaternionTypes(self: Self, other: Self): Part {
  return self.w() * other.w() + self.x() * other.x() + self.y() * other.y() + self.z() * other.z()
}

/// q * p * q⁻¹, with the point as a pure quaternion
global method rotate for QuaternionTypes(self: Self, point: Vector<Part, 3>): Vector<Part, 3> {
  let p := Self.new(0, point.x(), point.y(), point.z())
  return (self * p * self.inverse()).vector()
}

/// spherical interpolation along the shorter arc - falls back to a normalized lerp when nearly parallel
global method slerp for QuaternionTypes(self: Self, to: Self, t: Part): Self {
  let target := to
  let cosine := self.dot(to)
  if cosine < 0 then {
    set target := -to
    set cosine := -cosine
  }
  if cosine > 1 - Part.epsilon() * 1000 then { return (self + (target - self).scale(t)).normalize() }
  let angle := cosine.acos()
  let sine := angle.sin()
  return self.scale(((1 - t) * angle).sin() / sine) + target.scale((t * angle).sin() / sine)
}

global method toAxisAngle for QuaternionTypes(self: Self): (Vector<Part, 3>, Part) {
  let unit := self.normalize()
  let angle := 2 * unit.w().min(1).max(-1).acos()
  let s := (1 - unit.w() * unit.w()).sqrt()
  if s < Part.epsilon() then { return (Vector<Part, 3>.unit(0) !? Vector<Part, 3>.zero(), angle) }
  return (unit.vector().scale(1 / s), angle)
}

global method toEuler for QuaternionTypes(self: Self): (Part, Part, Part) {
  let (w, x, y, z) := (self.w(), self.x(), self.y(), self.z())
  let roll := (2 * (w * x + y * z)).atan2(1 - 2 * (x * x + y * y))
  let pitch := (2 * (w * y - z * x)).min(1).max(-1).asin()
  let yaw := (2 * (w * z + x * y)).atan2(1 - 2 * (y * y + z * z))
  return (roll, pitch, yaw)
}

global method toMatrix for QuaternionTypes(self: Self): Matrix<Part, 3, 3> {
  let (w, x, y, z) := self.normalize() |> λ(q) (q.w(), q.x(), q.y(), q.z())
  return Matrix<Part, 3, 3>.fromRows([
    [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
    [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
    [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
  ]) !? Matrix<Part, 3, 3>.identity()
}

global method approxEquals for QuaternionTypes(self: Self, other: Self, tolerance: Part := Part.epsilon()): Boolean {
  return (self - other).magnitude() <= tolerance
}

method equals(self: Self, other: Self): Boolean {
  return #builtin.intrinsic.EQ_Self_Self(self, other)
}

method hash(self: Self): U64 {
  return [self.w(), self.x(), self.y(), self.z()].reduce(&hashSeed, λ(hash, part) hashCombine(hash, part.hash()))
}

/// "1+2i-3j+4k"
method toString(self: Self): String {
  let term := λ(value, unit) (value < 0 ? "-" : "+") ++ value.abs().toString() ++ unit
  return self.w().toString() ++ term(self.x(), "i") ++ term(self.y(), "j") ++ term(self.z(), "k")
}

/// "w+xi+yj+zk" - each part is optional, in any order, like a sum of terms
function parse(text: String): ParseError ! Self {
  let parts := [0 as Part, 0 as Part, 0 as Part, 0 as Part]
  let terms := Regex("([+-]?[^+-]*[0-9.][^+-]*|[+-]?[ijk])")!!
  for term in terms.findAll(text.replaceAll(" ", "")) {
    let t := term.text()
    let unit := "ijk".indexOf(t.slice((t.size() - 1)..<t.size()) !? "")
    let digits := unit == undefined ? t : t.slice(0..<(t.size() - 1)) !? ""
    let value := digits == "" or digits == "+" ? 1 : digits == "-" ? -1 : Part.parse(digits)!!
    set parts[unit == undefined ? 0 : unit + 1] += value
  }
  return Self.new(parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0, parts[3] ?? 0)
}

function zero(): Self {
  return Self.new(0, 0, 0, 0)
}

function one(): Self {
  return Self.identity()
}

method add(self: Self, other: Self): Self {
  return #builtin.intrinsic.ADD_Self_Self(self, other)
}

method subtract(self: Self, other: Self): Self {
  return #builtin.intrinsic.SUB_Self_Self(self, other)
}

/// the Hamilton product - not commutative
method multiply(self: Self, other: Self): Self {
  return #builtin.intrinsic.MUL_Self_Self(self, other)
}

/// self * other⁻¹
method divide(self: Self, other: Self): Self {
  return #builtin.intrinsic.DIV_Self_Self(self, other)
}

method floorDivide(self: Self, other: Self): Self {
  let q := self / other
  return Self.new(q.w().floor(), q.x().floor(), q.y().floor(), q.z().floor())
}

method remainder(self: Self, other: Self): Self {
  return self - other * self.floorDivide(other)
}

method power(self: Self, exponent: Self): Self {
  return #builtin.intrinsic.POW_Self_Self(self, exponent)
}

method negate(self: Self): Self {
  return #builtin.intrinsic.NEG_Self(self)
}

method plus(self: Self): Self {
  return self
}

method scale(self: Self, factor: Part): Self {
  return Self.new(self.w() * factor, self.x() * factor, self.y() * factor, self.z() * factor)
}

method cast(self: Self): Target {
  if Target == Self then { return self }
  return #builtin.intrinsic.CAST_Self_Target(self)
}

function default(): Self {
  return Self.new(0, 0, 0, 0)
}

/// how many digits / keeps after the point at least
local const divisionPlaces: U8 := 16

local function pow10 for Decimal(count: U64): S128 {
  let result: S128 := 1
  for _ in 0..<count {
    set result := result * 10
  }
  return result
}

/// numerator / denominator as a whole number, the dropped part rounded by mode
local function divideRounded for Decimal(numerator: S128, denominator: S128, mode: RoundingMode): S128 {
  let n := denominator < 0 ? -numerator : numerator
  let d := denominator < 0 ? -denominator : denominator
  let quotient := n / d
  let rest := n % d
  if rest == 0 then {
    return quotient
  }
  let away: S128 := n < 0 ? -1 : 1
  let twice := rest.abs() * 2
  match mode {
    case RoundingMode.Down then { return quotient }
    case RoundingMode.Up then { return quotient + away }
    case RoundingMode.Floor then { return away < 0 ? quotient - 1 : quotient }
    case RoundingMode.Ceiling then { return away > 0 ? quotient + 1 : quotient }
    case RoundingMode.HalfUp then { return twice >= d ? quotient + away : quotient }
    case RoundingMode.HalfDown then { return twice > d ? quotient + away : quotient }
    case RoundingMode.HalfEven then { return twice > d or (twice == d and quotient % 2 != 0) ? quotient + away : quotient }
  }
}

/// the units at more places - the same number
local method widen for Decimal(self: Decimal, places: U8): S128 {
  return self.units * Self.pow10((places - self.scale) as U64)
}

/// trailing zeros dropped, down to keep places
local method trim for Decimal(self: Decimal, keep: U8): Decimal {
  let units := self.units
  let scale := self.scale
  for _ in #builtin.forever() while scale > keep and units % 10 == 0 {
    set units := units / 10
    set scale := scale - 1
  }
  return Decimal{units, scale}
}

global function of for Decimal(value: S64): Decimal {
  return Decimal{units := value as S128, scale := 0}
}

global function fromParts for Decimal(coefficient: S128, places: U8): Decimal {
  return Decimal{units := coefficient, scale := places}
}

global function fromF64 for Decimal(value: F64, places: U8): ParseError ! Decimal {
  if not value.isFinite() then { error ParseError.new(value.toString() ++ " has no exact decimal value") }
  return Decimal.parse(value.toString())!!.round(places)
}

global method coefficient for Decimal(self: Decimal): S128 {
  return self.units
}

global method places for Decimal(self: Decimal): U8 {
  return self.scale
}

global method round for Decimal(self: Decimal, places: U8, mode: RoundingMode := RoundingMode.HalfEven): Decimal {
  if places >= self.scale then {
    return Decimal{units := self.widen(places), scale := places}
  }
  return Decimal{units := Self.divideRounded(self.units, Self.pow10((self.scale - places) as U64), mode), scale := places}
}

/// self.units / 10^self.scale / (other.units / 10^other.scale) at places digits is
/// self.units * 10^(places - self.scale + other.scale) / other.units
global method divideTo for Decimal(self: Decimal, other: Decimal, places: U8, mode: RoundingMode := RoundingMode.HalfEven): Decimal {
  if other.units == 0 then { #runtime.abort(Error.new("Decimal division by zero")) }
  let shift := (places as S64) - (self.scale as S64) + (other.scale as S64)
  let numerator := shift >= 0 ? self.units * Self.pow10(shift as U64) : self.units
  let denominator := shift >= 0 ? other.units : other.units * Self.pow10((-shift) as U64)
  return Decimal{units := Self.divideRounded(numerator, denominator, mode), scale := places}
}

global method normalize for Decimal(self: Decimal): Decimal {
  return self.trim(0)
}

global method abs for Decimal(self: Decimal): Decimal {
  return Decimal{units := self.units.abs(), scale := self.scale}
}

global method sign for Decimal(self: Decimal): S8 {
  return self.units < 0 ? -1 : self.units > 0 ? 1 : 0
}

global method isZero for Decimal(self: Decimal): Boolean {
  return self.units == 0
}

global method isNegative for Decimal(self: Decimal): Boolean {
  return self.units < 0
}

global method isWhole for Decimal(self: Decimal): Boolean {
  return self.units % Self.pow10(self.scale as U64) == 0
}

global method toF64 for Decimal(self: Decimal): F64 {
  return F64.parse(self.toString()) !? 0.0
}

global method toS64 for Decimal(self: Decimal): OverflowError ! S64 {
  return (self.units / Self.pow10(self.scale as U64)) as S64
}

function zero(): Decimal {
  return Decimal{units := 0, scale := 0}
}

function one(): Decimal {
  return Decimal{units := 1, scale := 0}
}

/// the larger side's places
method add(self: Decimal, other: Decimal): Decimal {
  let places := self.scale.max(other.scale)
  return Decimal{units := self.widen(places) + other.widen(places), scale := places}
}

method subtract(self: Decimal, other: Decimal): Decimal {
  let places := self.scale.max(other.scale)
  return Decimal{units := self.widen(places) - other.widen(places), scale := places}
}

/// the places add up - 1.5 * 2.25 is 3.375
method multiply(self: Decimal, other: Decimal): Decimal {
  return Decimal{units := self.units * other.units, scale := self.scale + other.scale}
}

/// at least 16 places, rounded half to even - zeros past either side's places dropped
method divide(self: Decimal, other: Decimal): Decimal {
  let keep := self.scale.max(other.scale)
  return self.divideTo(other, keep.max(divisionPlaces)).trim(keep)
}

method floorDivide(self: Decimal, other: Decimal): Decimal {
  return self.divideTo(other, 0, RoundingMode.Floor)
}

/// what's left past the whole times other fits - its sign is self's
method remainder(self: Decimal, other: Decimal): Decimal {
  let places := self.scale.max(other.scale)
  return Decimal{units := self.widen(places) % other.widen(places), scale := places}
}

/// a whole exponent only - a negative one divides
method power(self: Decimal, exponent: Decimal): Decimal {
  if not exponent.isWhole() then { #runtime.abort(Error.new("Decimal powers take a whole exponent, got " ++ exponent.toString())) }
  let count := exponent.toS64() !? 0
  let result := Decimal.one()
  for _ in 0..<(count.abs() as U64) {
    set result := result * self
  }
  return count < 0 ? Decimal.one() / result : result
}

method negate(self: Decimal): Decimal {
  return Decimal{units := -self.units, scale := self.scale}
}

method plus(self: Decimal): Decimal {
  return self
}

method compare(self: Decimal, other: Decimal): Ordering {
  let places := self.scale.max(other.scale)
  return self.widen(places).compare(other.widen(places))
}

method equals(self: Decimal, other: Decimal): Boolean {
  return self.compare(other) == Ordering.Equal
}

method hash(self: Decimal): U64 {
  let normal := self.normalize()
  return normal.units.hash() ^ normal.scale.hash()
}

method toString(self: Decimal): String {
  let digits := self.units.abs().toString().padStart((self.scale as U64) + 1, "0")
  let split := digits.size() - (self.scale as U64)
  let whole := digits.slice(0..<split) !? digits
  let sign := self.units < 0 ? "-" : ""
  return self.scale == 0 ? sign ++ whole : sign ++ whole ++ "." ++ (digits.slice(split..<digits.size()) !? "")
}

function parse(text: String): ParseError ! Decimal {
  let found := #regex"^([+-]?)([0-9][0-9_]*)?(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?quot;.match(text.trim())
  if found == undefined or (found.group(2) == undefined and found.group(3) == undefined) then {
    error ParseError.new("not a decimal number: " ++ text)
  }
  let fraction := found.group(3) ?? ""
  let digits := (found.group(2) ?? "0").replaceAll("_", "") ++ fraction
  let places := (fraction.size() as S64) - (S64.parse(found.group(4) ?? "0") !? 0)
  let units := S128.parse(digits)!! * (places < 0 ? Self.pow10((-places) as U64) : 1)
  return Decimal{units := found.group(1) == "-" ? -units : units, scale := places.max(0) as U8}
}

function default(): Decimal {
  return Decimal.zero()
}

method equals(self: RoundingMode, other: RoundingMode): Boolean {
  return self.index() == other.index()
}

method hash(self: RoundingMode): U64 {
  return self.index().hash()
}

method toString(self: RoundingMode): String {
  return ["HalfEven", "HalfUp", "HalfDown", "Up", "Down", "Ceiling", "Floor"][self.index()]!!
}

local const limbBase: S64 := 1_000_000_000

/// limbs without the zero limbs on top, zero never negative
local function make for BigInteger(negative: Boolean, limbs: Array<S64>): BigInteger {
  for _ in Iterator.forever() while limbs.last() == 0 {
    limbs.pop()
  }
  return BigInteger{negative := negative and not limbs.isEmpty(), limbs}
}

/// -1, 0 or 1 - the sizes alone
local function compareSizes for BigInteger(a: Array<S64>, b: Array<S64>): S64 {
  if a.size() != b.size() then {
    return a.size() < b.size() ? -1 : 1
  }
  for i in (0..<a.size()).reverse() {
    if a[i]!! != b[i]!! then {
      return a[i]!! < b[i]!! ? -1 : 1
    }
  }
  return 0
}

local function addSizes for BigInteger(a: Array<S64>, b: Array<S64>): Array<S64> {
  let out: Array<S64> := []
  let carry: S64 := 0
  for i in 0..<a.size().max(b.size()) {
    let total := (a[i] ?? 0) + (b[i] ?? 0) + carry
    out.push(total % limbBase)
    set carry := total / limbBase
  }
  if carry > 0 then { out.push(carry) }
  return out
}

/// a - b, a at least b
local function subtractSizes for BigInteger(a: Array<S64>, b: Array<S64>): Array<S64> {
  let out: Array<S64> := []
  let borrow: S64 := 0
  for i in 0..<a.size() {
    let difference := a[i]!! - (b[i] ?? 0) - borrow
    set borrow := difference < 0 ? 1 : 0
    out.push(difference + borrow * limbBase)
  }
  return out
}

/// schoolbook - a limb times a limb plus what's there fits an S64
local function multiplySizes for BigInteger(a: Array<S64>, b: Array<S64>): Array<S64> {
  let out := Array.filled(a.size() + b.size(), 0 as S64)
  for i in 0..<a.size() {
    let carry: S64 := 0
    for j in 0..<b.size() {
      let total := out[i + j]!! + a[i]!! * b[j]!! + carry
      set out[i + j] := total % limbBase
      set carry := total / limbBase
    }
    set out[i + b.size()] := carry
  }
  return out
}

/// the quotient and what's left of a / b, b not zero - Knuth's long division (TAOCP 4.3.1, algorithm D):
/// both scaled so b's top limb is at least half the base, then each quotient limb guessed from the top
/// limbs, at most 2 too large, and corrected
local function divideSizes for BigInteger(a: Array<S64>, b: Array<S64>): (Array<S64>, Array<S64>) {
  if Self.compareSizes(a, b) < 0 then {
    return ([], a)
  }
  let n := b.size()
  let m := a.size() - n
  let factor := limbBase / (b[n - 1]!! + 1)
  let u := Self.multiplySizes(a, [factor])
  u.resize(a.size() + 1, 0)
  let v := Self.multiplySizes(b, [factor])
  let quotient := Array.filled(m + 1, 0 as S64)
  for j in (0..=m).reverse() {
    let top := u[j + n]!! * limbBase + u[j + n - 1]!!
    let guess := top / v[n - 1]!!
    let rest := top % v[n - 1]!!
    for _ in Iterator.forever() while rest < limbBase and (guess >= limbBase or (n > 1 and guess * v[n - 2]!! > rest * limbBase + u[j + n - 2]!!)) {
      set guess := guess - 1
      set rest := rest + v[n - 1]!!
    }
    /// u[j ..= j + n] minus guess times v - one v back when it went below zero
    let product := Self.multiplySizes(v, [guess])
    let window := u.slice(j..<(j + n + 1))!!
    if Self.compareSizes(Self.make(false, window.toArray()).limbs, Self.make(false, product.toArray()).limbs) < 0 then {
      set guess := guess - 1
      set product := Self.subtractSizes(product, v)
    }
    let left := Self.subtractSizes(window, product)
    for i in 0..=n {
      set u[j + i] := left[i] ?? 0
    }
    set quotient[j] := guess
  }
  let (rest, _) := Self.divideSizes(Self.make(false, u.slice(0..<n)!!).limbs, [factor])
  return (Self.make(false, quotient).limbs, rest)
}

/// self / other's sizes - other zero panics
local function division for BigInteger(self: BigInteger, other: BigInteger): (Array<S64>, Array<S64>) {
  if other.isZero() then { #runtime.abort(Error.new("BigInteger division by zero")) }
  return Self.divideSizes(self.limbs, other.limbs)
}

global function of for BigInteger(value: S64): BigInteger {
  let size := (value as S128).abs()
  let limbs: Array<S64> := []
  for _ in Iterator.forever() while size > 0 {
    limbs.push((size % limbBase) as S64)
    set size := size / limbBase
  }
  return BigInteger{negative := value < 0, limbs}
}

global method abs for BigInteger(self: BigInteger): BigInteger {
  return BigInteger{negative := false, limbs := self.limbs}
}

global method sign for BigInteger(self: BigInteger): S8 {
  return self.negative ? -1 : self.limbs.isEmpty() ? 0 : 1
}

global method isZero for BigInteger(self: BigInteger): Boolean {
  return self.limbs.isEmpty()
}

global method isPositive for BigInteger(self: BigInteger): Boolean {
  return not self.negative and not self.limbs.isEmpty()
}

global method isNegative for BigInteger(self: BigInteger): Boolean {
  return self.negative
}

global method isEven for BigInteger(self: BigInteger): Boolean {
  return (self.limbs.first() ?? 0).isEven()
}

global method isOdd for BigInteger(self: BigInteger): Boolean {
  return not self.isEven()
}

global method min for BigInteger(self: BigInteger, other: BigInteger): BigInteger {
  return other < self ? other : self
}

global method max for BigInteger(self: BigInteger, other: BigInteger): BigInteger {
  return other > self ? other : self
}

/// by squaring
global method pow for BigInteger(self: BigInteger, exponent: U32): BigInteger {
  let result := BigInteger.one()
  let base := self
  let remaining := exponent
  for _ in Iterator.forever() while remaining > 0 {
    if remaining.isOdd() then { set result := result * base }
    set base := base * base
    set remaining := remaining shr 1
  }
  return result
}

/// Newton's steps down from a power of ten above the root
global method sqrt for BigInteger(self: BigInteger): CastError ! BigInteger {
  if self.negative then { error CastError.new("no integer square root of " ++ self.toString()) }
  if self.isZero() then { return self }
  let x := BigInteger.of(10).pow(((self.digitCount() + 1) / 2) as U32)
  for _ in Iterator.forever() {
    let next := (x + self / x) / BigInteger.of(2)
    if next >= x then { return x }
    set x := next
  }
}

global method gcd for BigInteger(self: BigInteger, other: BigInteger): BigInteger {
  let a := self.abs()
  let b := other.abs()
  for _ in Iterator.forever() while not b.isZero() {
    set (a, b) := (b, a % b)
  }
  return a
}

global method lcm for BigInteger(self: BigInteger, other: BigInteger): BigInteger {
  return self.isZero() or other.isZero() ? BigInteger.zero() : self.abs() / self.gcd(other) * other.abs()
}

global method divMod for BigInteger(self: BigInteger, other: BigInteger): (BigInteger, BigInteger) {
  return (self // other, self % other)
}

global method modulo for BigInteger(self: BigInteger, other: BigInteger): BigInteger {
  let rest := self % other
  return not rest.isZero() and rest.negative != other.negative ? rest + other : rest
}

global method digitCount for BigInteger(self: BigInteger): U64 {
  return self.isZero() ? 1 : (self.limbs.size() - 1) * 9 + self.limbs.last()!!.toString().size()
}

global method toF64 for BigInteger(self: BigInteger): F64 {
  return F64.parse(self.toString()) !? 0.0
}

/// through the widest integer of the sign, then `as`
global method toInteger for BigInteger<Target>(self: BigInteger): OverflowError ! Target {
  let wide := self.negative ? (S256.parse(self.toString()) !? undefined) as Unknown : (U256.parse(self.toString()) !? undefined) as Unknown
  if wide == undefined then { error OverflowError.new(self.toString() ++ " doesn't fit in a " ++ Target.name()) }
  return (wide.checkedCast<Target>() !? undefined) ?? error OverflowError.new(self.toString() ++ " doesn't fit in a " ++ Target.name())
}

function zero(): BigInteger {
  return BigInteger{negative := false, limbs := []}
}

function one(): BigInteger {
  return BigInteger{negative := false, limbs := [1]}
}

method add(self: BigInteger, other: BigInteger): BigInteger {
  if self.negative == other.negative then {
    return Self.make(self.negative, Self.addSizes(self.limbs, other.limbs))
  }
  if Self.compareSizes(self.limbs, other.limbs) >= 0 then {
    return Self.make(self.negative, Self.subtractSizes(self.limbs, other.limbs))
  }
  return Self.make(other.negative, Self.subtractSizes(other.limbs, self.limbs))
}

method subtract(self: BigInteger, other: BigInteger): BigInteger {
  return self + -other
}

method multiply(self: BigInteger, other: BigInteger): BigInteger {
  return Self.make(self.negative != other.negative, Self.multiplySizes(self.limbs, other.limbs))
}

/// toward zero, like the fixed integers
method divide(self: BigInteger, other: BigInteger): BigInteger {
  let (quotient, _) := self.division(other)
  return Self.make(self.negative != other.negative, quotient)
}

method floorDivide(self: BigInteger, other: BigInteger): BigInteger {
  let (quotient, rest) := self.division(other)
  let truncated := Self.make(self.negative != other.negative, quotient)
  return self.negative != other.negative and not rest.isEmpty() ? truncated - BigInteger.one() : truncated
}

/// its sign is self's
method remainder(self: BigInteger, other: BigInteger): BigInteger {
  let (_, rest) := self.division(other)
  return Self.make(self.negative, rest)
}

/// an exponent of 0 or more
method power(self: BigInteger, exponent: BigInteger): BigInteger {
  if exponent.negative then { #runtime.abort(Error.new("BigInteger powers take an exponent of 0 or more, got " ++ exponent.toString())) }
  return self.pow(exponent.toInteger<U32>()!!)
}

method negate(self: BigInteger): BigInteger {
  return BigInteger{negative := not self.negative and not self.limbs.isEmpty(), limbs := self.limbs}
}

method plus(self: BigInteger): BigInteger {
  return self
}

method compare(self: BigInteger, other: BigInteger): Ordering {
  if self.negative != other.negative then {
    return self.negative ? Ordering.Less : Ordering.Greater
  }
  let sizes := Self.compareSizes(self.limbs, other.limbs)
  return (self.negative ? -sizes : sizes).compare(0)
}

method equals(self: BigInteger, other: BigInteger): Boolean {
  return self.negative == other.negative and self.limbs == other.limbs
}

method hash(self: BigInteger): U64 {
  return self.negative.hash() ^ self.limbs.hash()
}

method toString(self: BigInteger): String {
  if self.isZero() then { return "0" }
  let digits := self.limbs.reverse().mapIndexed(λ(i, limb) → i == 0 ? limb.toString() : limb.toString().padStart(9, "0"))
  return (self.negative ? "-" : "") ++ digits.join("")
}

function parse(text: String): ParseError ! BigInteger {
  let found := #regex"^([+-]?)([0-9][0-9_]*)quot;.match(text.trim())
  if found == undefined then { error ParseError.new("not a whole number: " ++ text) }
  let digits := found.group(2)!!.replaceAll("_", "")
  let limbs: Array<S64> := []
  let end := digits.size()
  for _ in Iterator.forever() while end > 0 {
    let start := end > 9 ? end - 9 : 0
    limbs.push(S64.parse(digits.slice(start..<end)!!)!!)
    set end := start
  }
  return Self.make(found.group(1) == "-", limbs)
}

function default(): BigInteger {
  return BigInteger.zero()
}

/// top / bottom in lowest terms, the bottom positive - a zero bottom panics
local function make for Rational(top: BigInteger, bottom: BigInteger): Rational {
  if bottom.isZero() then { #runtime.abort(Error.new("Rational with a zero denominator")) }
  let common := top.gcd(bottom)
  let sign := bottom.isNegative() ? BigInteger.of(-1) : BigInteger.one()
  return Rational{top := top / common * sign, bottom := bottom / common * sign}
}

/// top / bottom (bottom positive) as a whole number, the dropped part rounded by mode - as Decimal rounds
local function rounded for Rational(top: BigInteger, bottom: BigInteger, mode: RoundingMode): BigInteger {
  let quotient := top / bottom
  let rest := top % bottom
  if rest.isZero() then { return quotient }
  let away := top.isNegative() ? BigInteger.of(-1) : BigInteger.one()
  let half := (rest.abs() * BigInteger.of(2)).compare(bottom)
  return match mode {
    case RoundingMode.Down then quotient
    case RoundingMode.Up then quotient + away
    case RoundingMode.Floor then top.isNegative() ? quotient - BigInteger.one() : quotient
    case RoundingMode.Ceiling then top.isNegative() ? quotient : quotient + BigInteger.one()
    case RoundingMode.HalfUp then half != Ordering.Less ? quotient + away : quotient
    case RoundingMode.HalfDown then half == Ordering.Greater ? quotient + away : quotient
    case RoundingMode.HalfEven then half == Ordering.Greater or (half == Ordering.Equal and quotient.isOdd()) ? quotient + away : quotient
  }
}

global function of for Rational(numerator: S64, denominator: S64 := 1): Rational {
  return Self.make(BigInteger.of(numerator), BigInteger.of(denominator))
}

global function fromParts for Rational(numerator: BigInteger, denominator: BigInteger): Rational {
  return Self.make(numerator, denominator)
}

global function fromDecimal for Rational(value: Decimal): Rational {
  return Self.make(value.coefficient().toBigInteger(), BigInteger.of(10).pow(value.places() as U32))
}

global method numerator for Rational(self: Rational): BigInteger {
  return self.top
}

global method denominator for Rational(self: Rational): BigInteger {
  return self.bottom
}

global method reciprocal for Rational(self: Rational): Rational {
  return Self.make(self.bottom, self.top)
}

global method abs for Rational(self: Rational): Rational {
  return Rational{top := self.top.abs(), bottom := self.bottom}
}

global method sign for Rational(self: Rational): S8 {
  return self.top.sign()
}

global method isZero for Rational(self: Rational): Boolean {
  return self.top.isZero()
}

global method isNegative for Rational(self: Rational): Boolean {
  return self.top.isNegative()
}

global method isWhole for Rational(self: Rational): Boolean {
  return self.bottom == BigInteger.one()
}

global method floor for Rational(self: Rational): BigInteger {
  return Self.rounded(self.top, self.bottom, RoundingMode.Floor)
}

global method ceil for Rational(self: Rational): BigInteger {
  return Self.rounded(self.top, self.bottom, RoundingMode.Ceiling)
}

global method truncate for Rational(self: Rational): BigInteger {
  return Self.rounded(self.top, self.bottom, RoundingMode.Down)
}

global method round for Rational(self: Rational, mode: RoundingMode := RoundingMode.HalfEven): BigInteger {
  return Self.rounded(self.top, self.bottom, mode)
}

global method toDecimal for Rational(self: Rational, places: U8, mode: RoundingMode := RoundingMode.HalfEven): OverflowError ! Decimal {
  let coefficient := Self.rounded(self.top * BigInteger.of(10).pow(places as U32), self.bottom, mode)
  return Decimal.fromParts(coefficient.toInteger<S128>()!!, places)
}

/// 20 significant digits worked out exactly, then read as an F64
global method toF64 for Rational(self: Rational): F64 {
  if self.isZero() then { return 0.0 }
  let shift := (self.bottom.digitCount() as S64) - (self.top.digitCount() as S64) + 20
  let scaled := shift > 0 ? self.top * BigInteger.of(10).pow(shift as U32) / self.bottom : self.top / (self.bottom * BigInteger.of(10).pow((-shift) as U32))
  return F64.parse(scaled.toString() ++ "e" ++ (-shift).toString()) !? 0.0
}

function zero(): Rational {
  return Rational{top := BigInteger.zero(), bottom := BigInteger.one()}
}

function one(): Rational {
  return Rational{top := BigInteger.one(), bottom := BigInteger.one()}
}

method add(self: Rational, other: Rational): Rational {
  return Self.make(self.top * other.bottom + other.top * self.bottom, self.bottom * other.bottom)
}

method subtract(self: Rational, other: Rational): Rational {
  return Self.make(self.top * other.bottom - other.top * self.bottom, self.bottom * other.bottom)
}

method multiply(self: Rational, other: Rational): Rational {
  return Self.make(self.top * other.top, self.bottom * other.bottom)
}

method divide(self: Rational, other: Rational): Rational {
  if other.isZero() then { #runtime.abort(Error.new("Rational division by zero")) }
  return Self.make(self.top * other.bottom, self.bottom * other.top)
}

method floorDivide(self: Rational, other: Rational): Rational {
  return Rational{top := (self / other).floor(), bottom := BigInteger.one()}
}

/// its sign is self's
method remainder(self: Rational, other: Rational): Rational {
  return self - other * Rational{top := (self / other).truncate(), bottom := BigInteger.one()}
}

/// a whole exponent only - a negative one divides
method power(self: Rational, exponent: Rational): Rational {
  if not exponent.isWhole() then { #runtime.abort(Error.new("Rational powers take a whole exponent, got " ++ exponent.toString())) }
  let count := exponent.top.abs().toInteger<U32>()!!
  let raised := Rational{top := self.top.pow(count), bottom := self.bottom.pow(count)}
  return exponent.isNegative() ? raised.reciprocal() : raised
}

method negate(self: Rational): Rational {
  return Rational{top := -self.top, bottom := self.bottom}
}

method plus(self: Rational): Rational {
  return self
}

method compare(self: Rational, other: Rational): Ordering {
  return (self.top * other.bottom).compare(other.top * self.bottom)
}

method equals(self: Rational, other: Rational): Boolean {
  return self.top == other.top and self.bottom == other.bottom
}

method hash(self: Rational): U64 {
  return self.top.hash() ^ self.bottom.hash()
}

method toString(self: Rational): String {
  return self.isWhole() ? self.top.toString() : self.top.toString() ++ "/" ++ self.bottom.toString()
}

function parse(text: String): ParseError ! Rational {
  let found := #regex"^([+-]?[0-9][0-9_]*)(?:/([+-]?[0-9][0-9_]*)|\.([0-9_]+))?quot;.match(text.trim())
  if found == undefined then { error ParseError.new("not a fraction: " ++ text) }
  let fraction := (found.group(3) ?? "").replaceAll("_", "")
  let top := BigInteger.parse(found.group(1)!! ++ fraction)!!
  let bottom := found.group(2) == undefined ? BigInteger.of(10).pow(fraction.size() as U32) : BigInteger.parse(found.group(2)!!)!!
  if bottom.isZero() then { error ParseError.new("a zero denominator: " ++ text) }
  return Self.make(top, bottom)
}

function default(): Rational {
  return Rational.zero()
}

/// a unit's name inside another's - "Meter/Second" in a product is "(Meter/Second)"
local function part for Quantity<Type, Unit>(name: String): String {
  return name.contains("/") or name.contains("·") ? "(" ++ name ++ ")" : name
}

/// "Meter" raised to a power - "Meter²", "Meter³"; the digits are written raised
local function power for Quantity<Type, Unit>(name: String, times: U64): String {
  let raised := ["⁰", "¹", "²", "³", "⁴", "⁵", "⁶", "⁷", "⁸", "⁹"]
  return name ++ times.toString().codepoints().map((digit) => raised[digit.toString().parse<U64>()!!]).join("")
}

/// a unit split into what it's a power of and the power - "Meter²" is ("Meter", 2), "Meter" is ("Meter", 1)
local function powerOf for Quantity<Type, Unit>(name: String): (String, U64) {
  let found := name.match(/^(.+?)([⁰¹²³⁴⁵⁶⁷⁸⁹]+)$/)
  if found == undefined then {
    return (name, 1)
  }
  let raised := "⁰¹²³⁴⁵⁶⁷⁸⁹"
  let digits := found!!.groups[1].codepoints().map((digit) => raised.indexOf(digit.toString())!!.toString()).join("")
  return (found!!.groups[0], digits.parse<U64>()!!)
}

/// two units multiplied - "Newton·Meter", or one unit's power: "Meter" times "Meter" is "Meter²"
local function product for Quantity<Type, Unit>(left: String, right: String): String {
  let (leftBase, leftPower) := Self.powerOf(left)
  let (rightBase, rightPower) := Self.powerOf(right)
  if leftBase == rightBase then {
    return Self.power(Self.part(leftBase), leftPower + rightPower)
  }
  return Self.part(left) ++ "·" ++ Self.part(right)
}

/// a unit as the compiler names it - its name, then what it comes to: "Kilometer|1000|0|Meter^1" - as a
/// quantity of value in it; a bare name, a unit it can't read (a type parameter), is a base unit of its own
local function inUnit for Quantity<Type, Unit>(value: Type, named: String): Self {
  let parts := named.split("|")
  if parts.size() < 4 then {
    return Self{amount := value, unit := named, scale := 1.0, offset := 0.0, dims := Map.of((named, 1))}
  }
  let dims: Map<String, S64> := Map.of()
  for power in parts[3].split(" ") if power != "" {
    let (name, exponent) := power.splitOnce("^")!!
    dims.set(name, exponent.toInteger()!!)
  }
  return Self{amount := value, unit := parts[0], scale := parts[1].toNumber()!!, offset := parts[2].toNumber()!!, dims}
}

global function of for Quantity<Type, Unit>(value: Type): Quantity<Type, Unit> {
  return Self.inUnit(value, #comptime.typeName(Unit))
}

/// self in another unit of what it measures - through the base units, scale and offset both - to 12
/// significant digits, past which is the scales' rounding
local function into for Quantity<Type, Unit>(self: Self, unit: String, scale: F64, offset: F64): Self {
  let measured := self.amount as F64 * self.scale + self.offset
  let amount := ((measured - offset) / scale).roundSignificant(12)
  return Self{amount := amount as Type, unit, scale, offset, dims := self.dims}
}

global method value for Quantity<Type, Unit>(self: Self): Type {
  return self.amount
}

global method unitName for Quantity<Type, Unit>(self: Self): String {
  return self.unit
}

global method add for Quantity<Type, Unit>(self: Self, other: Self): Self {
  return Self{amount := self.amount + other.amount, unit := self.unit, scale := self.scale, offset := self.offset, dims := self.dims}
}

global method subtract for Quantity<Type, Unit>(self: Self, other: Self): Self {
  return Self{amount := self.amount - other.amount, unit := self.unit, scale := self.scale, offset := self.offset, dims := self.dims}
}

global method negate for Quantity<Type, Unit>(self: Self): Self {
  return Self{amount := -self.amount, unit := self.unit, scale := self.scale, offset := self.offset, dims := self.dims}
}

global method ratio for Quantity<Type, Unit>(self: Self, other: Self): Type {
  return self.amount / other.amount
}

/// base units multiplied (sign 1) or divided (sign -1) - those whose powers cancel left out
local function joined for Quantity<Type, Unit>(left: Map<String, S64>, right: Map<String, S64>, sign: S64): Map<String, S64> {
  let out := left.clone()
  for (name, power) in right {
    out.set(name, (out.get(name) ?? 0) + sign * power)
  }
  out.retain((name, power) => power != 0)
  return out
}

/// a product or quotient - a plain number when the units cancel (2 Kilometer / 500 Meter is 4), scaled
/// by what's left of the units' scales
local function made for Quantity<Type, Unit>(amount: Type, unit: String, scale: F64, dims: Map<String, S64>): Quantity<Type, Unknown> | Type {
  if dims.isEmpty() then {
    return scale == 1.0 ? amount : (amount as F64 * scale).roundSignificant(12) as Type
  }
  return Quantity{amount, unit, scale, offset := 0.0, dims}
}

/// also what a * b between two quantities is
global method times for Quantity<Type, Unit, Other>(self: Self, other: Quantity<Type, Other>): Quantity<Type, Product<Unit, Other>> {
  return Self.made(self.amount * other.amount, Self.product(self.unit, other.unit), self.scale * other.scale, Self.joined(self.dims, other.dims, 1))
}

/// also what a / b between quantities of two units is
global method per for Quantity<Type, Unit, Other>(self: Self, other: Quantity<Type, Other>): Quantity<Type, Per<Unit, Other>> {
  return Self.made(self.amount / other.amount, Self.part(self.unit) ++ "/" ++ Self.part(other.unit), self.scale / other.scale, Self.joined(self.dims, other.dims, -1))
}

global method convert for Quantity<Type, Unit, Target>(self: Self, factor: Type? := undefined): Quantity<Type, Target> {
  let target := Self.inUnit(self.amount, #comptime.typeName(Target))
  if factor == undefined then {
    return Self.into(self, target.unit, target.scale, target.offset)
  }
  return Quantity{amount := self.amount * factor, unit := target.unit, scale := target.scale, offset := target.offset, dims := target.dims}
}

method cast(self: Self): Quantity<Type, Target> {
  return self.convert<Target>()
}

method scale(self: Self, factor: Type): Self {
  return Self{amount := self.amount * factor, unit := self.unit, scale := self.scale, offset := self.offset, dims := self.dims}
}

method equals(self: Self, other: Self): Boolean {
  return self.amount == other.amount
}

method hash(self: Self): U64 {
  return self.amount.hash()
}

method compare(self: Self, other: Self): Ordering {
  return self.amount.compare(other.amount)
}

method toString(self: Self): String {
  return self.amount.toString() ++ " " ++ self.unit
}

global function pi for Math(): F64 {
  return F64.pi()
}

global function tau for Math(): F64 {
  return F64.tau()
}

global function e for Math(): F64 {
  return F64.e()
}

global function infinity for Math(): F64 {
  return F64.infinity()
}

global function nan for Math(): F64 {
  return F64.nan()
}

global function min for Math<T: Comparable>(values: ..T): T {
  return values.min() !? abort(EmptyError.new("Math.min of no values"))
}

global function max for Math<T: Comparable>(values: ..T): T {
  return values.max() !? abort(EmptyError.new("Math.max of no values"))
}

global function abs for Math<T: Numeric>(x: T): T {
  return x < T.zero() ? -x : x
}

global function sign for Math<T: Numeric>(x: T): T {
  return x < T.zero() ? -T.one() : x > T.zero() ? T.one() : T.zero()
}

global function clamp for Math<T: Comparable>(x: T, low: T, high: T): T {
  return x < low ? low : x > high ? high : x
}

global function sum for Math<T: Numeric>(values: ..T): T {
  return values.sum()
}

global function product for Math<T: Numeric>(values: ..T): T {
  return values.product()
}

global function mean for Math(values: ..F64): EmptyError ! F64 {
  if values.isEmpty() then {
    error EmptyError.new("Math.mean of no values")
  }
  return values.sum() ÷ (values.size() as F64)
}

global function median for Math(values: ..F64): EmptyError ! F64 {
  if values.isEmpty() then {
    error EmptyError.new("Math.median of no values")
  }
  let sorted ≔ values.sorted()
  let middle ≔ sorted.size() ÷ 2
  let upper ≔ sorted[middle] ?? 0.0
  return sorted.size() % 2 = 1 ? upper : (sorted[middle - 1] ?? upper + upper) ÷ 2.0
}

global function floor for Math(x: F64): F64 {
  return x.floor()
}

global function ceil for Math(x: F64): F64 {
  return x.ceil()
}

/// halves away from zero - to `decimals` places after the point
global function round for Math(x: F64, decimals: U8 ≔ 0): F64 {
  return decimals = 0 ? x.round() : x.roundTo(decimals)
}

global function trunc for Math(x: F64): F64 {
  return x.truncate()
}

global function fract for Math(x: F64): F64 {
  return x.fraction()
}

global function sqrt for Math(x: F64): F64 {
  return x.sqrt()
}

global function cbrt for Math(x: F64): F64 {
  return x.cbrt()
}

/// the length of a vector with these parts - each pair taken with hypot, so nothing overflows on the way
global function hypot for Math(values: ..F64): F64 {
  let length ≔ 0.0
  for value in values {
    set length ≔ length.hypot(value)
  }
  return length
}

global function pow for Math(base: F64, exponent: F64): F64 {
  return base ^ exponent
}

global function exp for Math(x: F64): F64 {
  return x.exp()
}

global function ln for Math(x: F64): F64 {
  return x.ln()
}

global function log for Math(x: F64, base: F64): F64 {
  return x.log(base)
}

global function log2 for Math(x: F64): F64 {
  return x.log2()
}

global function log10 for Math(x: F64): F64 {
  return x.log10()
}

global function sin for Math(angle: F64): F64 {
  return angle.sin()
}

global function cos for Math(angle: F64): F64 {
  return angle.cos()
}

global function tan for Math(angle: F64): F64 {
  return angle.tan()
}

global function asin for Math(x: F64): F64 {
  return x.asin()
}

global function acos for Math(x: F64): F64 {
  return x.acos()
}

global function atan for Math(x: F64): F64 {
  return x.atan()
}

/// the angle from the positive x-axis to the point (x, y) - y first, as atan(y / x) has it
global function atan2 for Math(y: F64, x: F64): F64 {
  return y.atan2(x)
}

global function sinh for Math(x: F64): F64 {
  return x.sinh()
}

global function cosh for Math(x: F64): F64 {
  return x.cosh()
}

global function tanh for Math(x: F64): F64 {
  return x.tanh()
}

global function toRadians for Math(degrees: F64): F64 {
  return degrees.toRadians()
}

global function toDegrees for Math(radians: F64): F64 {
  return radians.toDegrees()
}

global function lerp for Math(a: F64, b: F64, t: F64): F64 {
  return a + (b - a) * t
}

global function inverseLerp for Math(a: F64, b: F64, x: F64): F64 {
  return (x - a) ÷ (b - a)
}

/// x moved from one range to the same place in another - Math.remap(5.0, 0.0..<10.0, 100.0..<200.0) is 150
global function remap for Math(x: F64, from: Range<F64>, to: Range<F64>): F64 {
  let t ≔ Math.inverseLerp(from.start(), from.end(), x)
  return Math.lerp(to.start(), to.end(), t)
}

global function gcd for Math(a: S64, b: S64): S64 {
  return a.gcd(b)
}

global function lcm for Math(a: S64, b: S64): S64 {
  return a.lcm(b)
}

/// 1 * 2 * ... * n - 1 for 0 - an OverflowError past U64
global function factorial for Math(n: U64): OverflowError ! U64 {
  let result: U64 ≔ 1
  for k in 2..=n {
    set result ≔ result.checkedMultiply(k)!!
  }
  return result
}

/// the ways to choose k of n - 0 when k > n; an OverflowError past U64
global function binomial for Math(n: U64, k: U64): OverflowError ! U64 {
  if k > n then {
    return 0
  }
  let smaller ≔ k.min(n - k)
  let result: U64 ≔ 1
  for i in 1..=smaller {
    /// exact at each step - result * (n - smaller + i) is a multiple of i
    set result ≔ result.checkedMultiply(n - smaller + i)!! ÷ i
  }
  return result
}

global function isPrime for Math(n: U64): Boolean {
  if n < 2 then {
    return false
  }
  if n < 4 then {
    return true
  }
  if n % 2 = 0 or n % 3 = 0 then {
    return false
  }
  let d: U64 ≔ 5
  for _ in Iterator.forever() while d ≤ n ÷ d {
    if n % d = 0 or n % (d + 2) = 0 then {
      return false
    }
    set d ≔ d + 6
  }
  return true
}

global function isNan for Math(x: F64): Boolean {
  return x.isNaN()
}

global function isFinite for Math(x: F64): Boolean {
  return x.isFinite()
}

/// a and b at most tolerance apart - relative to the larger, or absolute when both are below 1
global function approxEquals for Math(a: F64, b: F64, tolerance: F64 ≔ 1e-9): Boolean {
  let scale ≔ a.abs().max(b.abs()).max(1.0)
  return (a - b).abs() ≤ tolerance * scale
}

/// the code point starting at byte i, and how many bytes it took - undefined when malformed
local function decodeAt for TextTypes(bytes: Bytes, i: U64): (U32, U64)? {
  let at := λ(k) (bytes[i + k] ?? 0) as U32
  if Self == ASCII then { return at(0) < 0x80 ? (at(0), 1) : undefined }
  if Self == UTF32 then { return i + 4 <= bytes.size() ? (bytes.readInteger<U32>(i) !? 0, 4) : undefined }
  if Self == UTF16 then {
    if i + 2 > bytes.size() then { return undefined }
    let high := (bytes.readInteger<U16>(i) !? 0) as U32
    if high < 0xD800 or high > 0xDFFF then { return (high, 2) }
    if high > 0xDBFF or i + 4 > bytes.size() then { return undefined }
    let low := (bytes.readInteger<U16>(i + 2) !? 0) as U32
    if low < 0xDC00 or low > 0xDFFF then { return undefined }
    return (0x10000 + ((high - 0xD800) shl 10) + (low - 0xDC00), 4)
  }
  let lead := at(0)
  let width: U64 := lead < 0x80 ? 1 : lead >= 0xF8 ? 0 : lead >= 0xF0 ? 4 : lead >= 0xE0 ? 3 : lead >= 0xC0 ? 2 : 0
  if width == 0 or i + width > bytes.size() then { return undefined }
  let value := width == 1 ? lead : lead band (0x7F shr width)
  for k in 1..<width {
    if (at(k) band 0xC0) != 0x80 then { return undefined }
    set value := (value shl 6) bor (at(k) band 0x3F)
  }
  /// an overlong form - a value that fits in fewer bytes - isn't valid UTF-8
  let smallest: U32 := width == 2 ? 0x80 : width == 3 ? 0x800 : width == 4 ? 0x10000 : 0
  return value < smallest ? undefined : (value, width)
}

/// every code point in bytes, or a ParseError at the first malformed one (surrogates included -
/// Codepoint.fromU32 turns them down)
local function decodeAll for TextTypes(bytes: Bytes): ParseError ! Array<Codepoint> {
  let invalid := ParseError.new("not valid " ++ Self.name())
  let result: Array<Codepoint> := []
  let i: U64 := 0
  for _ in forever() while i < bytes.size() {
    let (value, width) := (Self.decodeAt(bytes, i) ?! invalid)!!
    result.push(((Codepoint.fromU32(value) !? undefined) ?! invalid)!!)
    set i += width
  }
  return result
}

/// one code point in Self's encoding - ASCII has no room for the rest, and writes '?' for them
local function encodeOne for TextTypes(c: Codepoint): Array<U8> {
  let v := c.value()
  if Self == ASCII then { return [v < 0x80 ? v as U8 : 0x3F] }
  if Self == UTF32 then { return v.toBytes().toArray() }
  if Self == UTF16 then {
    if v < 0x10000 then { return (v as U16).toBytes().toArray() }
    let rest := v - 0x10000
    return [..((0xD800 + (rest shr 10)) as U16).toBytes(), ..((0xDC00 + (rest band 0x3FF)) as U16).toBytes()]
  }
  if v < 0x80 then { return [v as U8] }
  if v < 0x800 then { return [(0xC0 bor (v shr 6)) as U8, (0x80 bor (v band 0x3F)) as U8] }
  if v < 0x10000 then { return [(0xE0 bor (v shr 12)) as U8, (0x80 bor ((v shr 6) band 0x3F)) as U8, (0x80 bor (v band 0x3F)) as U8] }
  return [(0xF0 bor (v shr 18)) as U8, (0x80 bor ((v shr 12) band 0x3F)) as U8, (0x80 bor ((v shr 6) band 0x3F)) as U8, (0x80 bor (v band 0x3F)) as U8]
}

/// where part next occurs at or after from, in code points, and how many code points it covers
local method findPart for TextTypes(self: Self, part: Self | Regex, from: U64): (U64, U64)? {
  match part {
    case Regex as regex then {
      let found := regex.find(self as String, from)
      return found == undefined ? undefined : (found.start(), found.end() - found.start())
    }
    case _ then {
      let text := self.codepoints()
      let needle := (part as Self).codepoints()
      for start in from..<(text.size() + 1) while start + needle.size() <= text.size() if (0..<needle.size()).all(λ(k) text[start + k] == needle[k]) {
        { return (start, needle.size()) }
      }
      return undefined
    }
  }
}

global function fromCodepoints for TextTypes(codepoints: Array<Codepoint>): Self {
  let bytes: Array<U8> := []
  for c in codepoints {
    set bytes ++= Self.encodeOne(c)
  }
  return Self{units := Bytes.fromArray(bytes)}
}

global function decode for TextTypes(bytes: Bytes): ParseError ! Self {
  Self.decodeAll(bytes)!!
  return Self{units := bytes.clone()}
}

global function repeat for TextTypes(text: Self, count: U64): Self {
  return text.repeat(count)
}

global method byteLength for TextTypes(self: Self): U64 {
  return self.units.size()
}

/// units are valid by construction, so decoding them can't fail
global method codepoints for TextTypes(self: Self): Array<Codepoint> {
  return Self.decodeAll(self.units) !? []
}

/// extended grapheme clusters - "e" and a combining accent are one
global method graphemes for TextTypes(self: Self): Array<Self> {
  let text := self.codepoints()
  let starts := #builtin.graphemeBreaks(text)
  return starts.mapIndexed(λ(i, start) Self.fromCodepoints(text.slice(start..<(starts[i + 1] ?? text.size())) !? []))
}

/// a final line break doesn't start one more, empty line
global method lines for TextTypes(self: Self): Array<Self> {
  let result := self.split("\n", undefined).map(λ(line) line.stripSuffix("\r") ?? line)
  if result.size() > 1 and (result.last() ?? "").isEmpty() then { result.pop() }
  return result
}

global method words for TextTypes(self: Self): Array<Self> {
  let result: Array<Self> := []
  let current: Array<Codepoint> := []
  for c in self.codepoints() {
    if not c.isWhitespace() then {
      current.push(c)
    } else {
      if not current.isEmpty() then {
        result.push(Self.fromCodepoints(current))
        set current := []
      }
    }
  }
  if not current.isEmpty() then { result.push(Self.fromCodepoints(current)) }
  return result
}

global method encode for TextTypes(self: Self): Bytes {
  return self.units.clone()
}

/// the leftmost match starts at 0 whenever any match does
global method startsWith for TextTypes(self: Self, prefix: Self | Regex): Boolean {
  return self.findPart(prefix, 0)?[0] == 0
}

global method endsWith for TextTypes(self: Self, suffix: Self | Regex): Boolean {
  match suffix {
    case Regex as regex then {
      let anchored := Regex.new("(?:" ++ regex.source() ++ ")quot;, regex.flags()) !? regex
      return anchored.test(self as String)
    }
    case _ then {
      let tail := (suffix as Self).size()
      return tail <= self.size() and self.findPart(suffix, self.size() - tail)?[0] == self.size() - tail
    }
  }
}

global method indexOf for TextTypes(self: Self, part: Self | Regex, from: U64 := 0): U64? {
  return self.findPart(part, from)?[0]
}

global method lastIndexOf for TextTypes(self: Self, part: Self | Regex): U64? {
  let last: U64? := undefined
  let from: U64 := 0
  for _ in forever() {
    let found := self.findPart(part, from)
    if found == undefined then { return last }
    set last := found[0]
    set from := found[0] + 1
  }
}

/// non-overlapping, left to right
global method count for TextTypes(self: Self, part: Self | Regex): U64 {
  let total: U64 := 0
  let from: U64 := 0
  for _ in forever() {
    let found := self.findPart(part, from)
    if found == undefined then { return total }
    set total += 1
    set from := found[0] + found[1].max(1)
  }
}

global method slice for TextTypes(self: Self, range: Range<U64>): IndexError ! Self {
  return Self.fromCodepoints(self.codepoints().slice(range)!!)
}

global method charAt for TextTypes(self: Self, index: U64): Codepoint? {
  return self.codepoints()[index]
}

/// an empty match splits between code points, but never before the first or after the last
global method split for TextTypes(self: Self, separator: Self | Regex, limit: U64?): Array<Self> {
  let text := self.codepoints()
  let parts: Array<Self> := []
  let from: U64 := 0
  for round in forever() {
    if limit != undefined and parts.size() + 1 >= limit then { break round }
    let found := self.findPart(separator, from)
    if found != undefined and found[1] == 0 and found[0] == from then { set found := self.findPart(separator, from + 1) }
    if found == undefined or (found[1] == 0 and found[0] >= text.size()) then { break round }
    parts.push(Self.fromCodepoints(text.slice(from..<found[0]) !? []))
    set from := found[0] + found[1]
  }
  parts.push(Self.fromCodepoints(text.slice(from..<text.size()) !? []))
  return parts
}

global method splitOnce for TextTypes(self: Self, separator: Self | Regex): (Self, Self)? {
  let found := self.findPart(separator, 0)
  if found == undefined then { return undefined }
  let text := self.codepoints()
  return (Self.fromCodepoints(text.slice(0..<found[0]) !? []), Self.fromCodepoints(text.slice((found[0] + found[1])..<text.size()) !? []))
}

global method join for TextTypes(self: Self, parts: Iterable<Self>): Self {
  let bytes: Array<U8> := []
  for part, i in parts {
    if i > 0 then { set bytes ++= self.units }
    set bytes ++= part.units
  }
  return Self{units := Bytes.fromArray(bytes)}
}

global method replace for TextTypes(self: Self, part: Self | Regex, with: Self): Self {
  match part {
    case Regex as regex then { return regex.replace(self as String, with as String) as Self }
    case _ then {
      let found := self.findPart(part, 0)
      if found == undefined then { return self }
      let text := self.codepoints()
      return Self.fromCodepoints([..(text.slice(0..<found[0]) !? []), ..with.codepoints(), ..(text.slice((found[0] + found[1])..<text.size()) !? [])])
    }
  }
}

global method replaceAll for TextTypes(self: Self, part: Self | Regex, with: Self): Self {
  match part {
    case Regex as regex then { return regex.replaceAll(self as String, with as String) as Self }
    case _ then { return with.join(self.split(part, undefined)) }
  }
}

global method repeat for TextTypes(self: Self, count: U64): Self {
  let bytes: Array<U8> := []
  for _ in 0..<count {
    set bytes ++= self.units
  }
  return Self{units := Bytes.fromArray(bytes)}
}

global method reverse for TextTypes(self: Self): Self {
  return Self.fromCodepoints(self.graphemes().reverse().flatMap(λ(g) g.codepoints()))
}

global method insert for TextTypes(self: Self, index: U64, part: Self): IndexError ! Self {
  let text := self.codepoints()
  if index > text.size() then { error IndexError.new("index " ++ index.toString() ++ " is past the end of the text") }
  return Self.fromCodepoints([..(text.slice(0..<index) !? []), ..part.codepoints(), ..(text.slice(index..<text.size()) !? [])])
}

global method remove for TextTypes(self: Self, range: Range<U64>): IndexError ! Self {
  let text := self.codepoints()
  let (start, end) := bounds(range)
  if end > text.size() then { error IndexError.new("range " ++ range.toString() ++ " is past the end of the text") }
  return Self.fromCodepoints([..(text.slice(0..<start) !? []), ..(text.slice(end..<text.size()) !? [])])
}

global method trim for TextTypes(self: Self): Self {
  return self.trimStart().trimEnd()
}

global method trimStart for TextTypes(self: Self): Self {
  return Self.fromCodepoints(self.codepoints().dropWhile(λ(c) c.isWhitespace()))
}

global method trimEnd for TextTypes(self: Self): Self {
  return Self.fromCodepoints(self.codepoints().reverse().dropWhile(λ(c) c.isWhitespace()).reverse())
}

global method stripPrefix for TextTypes(self: Self, prefix: Self): Self? {
  return self.startsWith(prefix) ? self.slice(prefix.size()..<self.size()) !? undefined : undefined
}

global method stripSuffix for TextTypes(self: Self, suffix: Self): Self? {
  return self.endsWith(suffix) ? self.slice(0..<(self.size() - suffix.size())) !? undefined : undefined
}

global method padStart for TextTypes(self: Self, length: U64, fill: Codepoint := ' '): Self {
  let missing := length - self.size().min(length)
  return Self.fromCodepoints(Array.filled(missing, fill)) ++ self
}

global method padEnd for TextTypes(self: Self, length: U64, fill: Codepoint := ' '): Self {
  let missing := length - self.size().min(length)
  return self ++ Self.fromCodepoints(Array.filled(missing, fill))
}

/// each code point's own mapping - some map to several ("ß" to "SS")
global method toUpper for TextTypes(self: Self): Self {
  return Self.fromCodepoints(self.codepoints().flatMap(λ(c) c.toUpper().codepoints()))
}

global method toLower for TextTypes(self: Self): Self {
  return Self.fromCodepoints(self.codepoints().flatMap(λ(c) c.toLower().codepoints()))
}

global method capitalize for TextTypes(self: Self): Self {
  let text := self.codepoints()
  if text.isEmpty() then { return self }
  return Self.fromCodepoints([..(text.first() ?? ' ').toUpper().codepoints(), ..text.drop(1)])
}

global method isBlank for TextTypes(self: Self): Boolean {
  return self.codepoints().all(λ(c) c.isWhitespace())
}

global method isAscii for TextTypes(self: Self): Boolean {
  return self.codepoints().all(λ(c) c.isAscii())
}

/// canonical (NFC, NFD) or compatibility (NFKC, NFKD) form
global method normalize for TextTypes(self: Self, form: NFC | NFD | NFKC | NFKD := NFC): Self {
  return Self.fromCodepoints(#builtin.normalize(self.codepoints(), form))
}

global method compareIgnoreCase for TextTypes(self: Self, other: Self): Ordering {
  return self.toLower().compare(other.toLower())
}

global method toNumber for TextTypes(self: Self): ParseError ! Number {
  return Number.parse(self as String)
}

global method toInteger for TextTypes(self: Self, radix: U8 := 10): ParseError ! Integer {
  return Integer.parse(self as String, radix)
}

global method parse for TextTypes<Target: FromString>(self: Self): ParseError ! Target {
  return Target.parse(self as String)
}

global method matches for TextTypes(self: Self, regex: Regex): Array<Match> {
  return regex.findAll(self as String).collect()
}

/// "{name}" becomes values' name, through its toString(); a placeholder with no value stays as written
global method format for TextTypes(self: Self, values: Map<String, Unknown>): Self {
  let text := self.codepoints()
  let result: Array<Codepoint> := []
  let i: U64 := 0
  for _ in forever() while i < text.size() {
    let c := text[i] ?? ' '
    let close := c == '{' ? (text.slice((i + 1)..<text.size()) !? []).indexOf('}') : undefined
    let name := close == undefined ? undefined : String.fromCodepoints(text.slice((i + 1)..<(i + 1 + close)) !? [])
    let value := name == undefined ? undefined : values.get(name)
    if value == undefined then {
      result.push(c)
      set i += 1
    } else {
      set result ++= value.toString().codepoints()
      set i += close + 2
    }
  }
  return Self.fromCodepoints(result)
}

/// the text ==, hash and compare look at - itself, or its &stringNormalization form when one is injected
local method canonical for TextTypes(self: Self): Self {
  return &stringNormalization.map(λ(form) self.normalize(form)) ?? self
}

/// Levenshtein's distance - one row of the table at a time, each cell the cheapest of a removal, an
/// insertion and a replacement (free when the codepoints are the same)
global method editDistance for TextTypes(self: Self, other: Self): U64 {
  let a := self.codepoints()
  let b := other.codepoints()
  let previous: Array<U64> := (0..=b.size()).toArray()
  for i in 0..<a.size() {
    let current: Array<U64> := [i + 1]
    for j in 0..<b.size() {
      let replaced := previous[j]!! + (a[i]!! == b[j]!! ? 0 : 1)
      current.push(replaced.min(previous[j + 1]!! + 1).min(current[j]!! + 1))
    }
    set previous := current
  }
  return previous[b.size()]!!
}

/// a codepoint that starts a word - the first, one after anything but a letter or digit, or a capital
/// after a lowercase letter (fooBar)
local function wordStartAt for TextTypes(text: Array<Codepoint>, at: U64): Boolean {
  if at == 0 then {
    return true
  }
  let before := text[at - 1]!!
  return not before.isAlphanumeric() or (text[at]!!.isUpper() and before.isLower())
}

/// each of query's codepoints found in order, ignoring case: a point for each, 4 more when it follows
/// the one before at once, 5 more at the start of a word, 2 more when query is the whole text
global method fuzzyScore for TextTypes(self: Self, query: Self): U64? {
  let text := self.codepoints()
  let lower := text.map(λ(c) c.toLower().codepoints()[0] ?? c)
  let score: U64 := 0
  let from: U64 := 0
  let previous: U64? := undefined
  for wanted in query.toLower().codepoints() {
    let found := (from..<lower.size()).find(λ(i) lower[i]!! == wanted)
    if found == undefined then {
      return undefined
    }
    set score += 1
    if previous != undefined and found == previous + 1 then {
      set score += 4
    }
    if wordStartAt(text, found) then {
      set score += 5
    }
    set previous := found
    set from := found + 1
  }
  if query.size() > 0 and query.size() == self.size() then {
    set score += 2
  }
  return score
}

global method dedent for TextTypes(self: Self): Self {
  let lines := self.replaceAll("\r\n", "\n").split("\n")
  let indents := lines.filter(λ(line) not line.isBlank()).map(λ(line) line.size() - line.trimStart().size())
  /// the shortest run of whitespace every non-blank line starts with, codepoint for codepoint
  let common := indents.isEmpty() ? 0 : indents.min()!!
  for line in lines if not line.isBlank() {
    for i in 0..<common if line.charAt(i) != lines.find(λ(other) not other.isBlank())!!.charAt(i) {
      set common := i
    }
  }
  return lines.map(λ(line) line.isBlank() ? "" : line.slice(common..<line.size())!!).join("\n")
}

global method indent for TextTypes(self: Self, prefix: Self := "  "): Self {
  return self.replaceAll("\r\n", "\n").split("\n").map(λ(line) line.isBlank() ? line : prefix ++ line).join("\n")
}

/// valid text in one encoding has exactly one byte form, so equal text is equal bytes
method equals(self: Self, other: Self): Boolean {
  return self.canonical().units == other.canonical().units
}

method hash(self: Self): U64 {
  return hashBytes(self.canonical().units)
}

method compare(self: Self, other: Self): Ordering {
  return self.canonical().codepoints().compare(other.canonical().codepoints())
}

method toString(self: Self): String {
  return Self == UTF8 ? self : String.fromCodepoints(self.codepoints())
}

method iterator(self: Self): Iterator<Codepoint> {
  let i: U64 := 0
  for _ in forever() while i < self.units.size() {
    let (value, width) := Self.decodeAt(self.units, i) ?? (0, 1)
    yield Codepoint.fromU32(value) !? '?'
    set i += width
  }
}

function fromIterable(items: Iterable<Codepoint>): Self {
  return Self.fromCodepoints(items.toArray())
}

method contains(self: Self, part: Self | Regex): Boolean {
  return self.findPart(part, 0) != undefined
}

method size(self: Self): U64 {
  return self.codepoints().size()
}

method isEmpty(self: Self): Boolean {
  return self.units.isEmpty()
}

method get(self: Self, key: U64): Codepoint? {
  return self.charAt(key)
}

/// re-encodes in place - the replacement may take a different number of bytes
method set(self: Self, key: U64, value: Codepoint): Error ! Undefined {
  let text := self.codepoints()
  if key >= text.size() then { error IndexError.new("index " ++ key.toString() ++ " is past the end of the text") }
  set text[key] := value
  set self.units := Self.fromCodepoints(text).units
}

method cast(self: Self): Target {
  if Target == Self then { return self }
  if Target == ASCII and not self.isAscii() then { error CastError.new("text has non-ASCII characters") }
  return Target.fromCodepoints(self.codepoints())
}

method concat(self: Self, other: Self): Self {
  return Self{units := self.units ++ other.units}
}

function default(): Self {
  return Self{units := Bytes.filled(0)}
}

method clone(self: Self): Self {
  return Self{units := self.units.clone()}
}

global function new for StringBuilder(): StringBuilder {
  return StringBuilder{parts := [], length := 0}
}

global method append for StringBuilder(self: StringBuilder, value: Unknown): StringBuilder {
  let text := #format"#{ value }"
  self.parts.push(text)
  set self.length += text.size()
  return self
}

global method appendLine for StringBuilder(self: StringBuilder, value: Unknown := ""): StringBuilder {
  return self.append(value).append("\n")
}

global method appendAll for StringBuilder(self: StringBuilder, values: Iterable<Unknown>, separator: String := ""): StringBuilder {
  for value, i in values {
    if i > 0 then {
      self.append(separator)
    }
    self.append(value)
  }
  return self
}

global method size for StringBuilder(self: StringBuilder): U64 {
  return self.length
}

global method isEmpty for StringBuilder(self: StringBuilder): Boolean {
  return self.length == 0
}

global method clear for StringBuilder(self: StringBuilder): Undefined {
  self.parts.clear()
  set self.length := 0
}

method toString(self: StringBuilder): String {
  let joined := self.parts.join("")
  set self.parts := [joined]
  return joined
}

function default(): StringBuilder {
  return StringBuilder.new()
}

/// the superscript and subscript letters are their own tokens (xᵢ is x indexed by i), never part of a name
local const scriptLetters := "ᵃᵇᶜᵈᵉᶠᵍʰⁱʲᵏˡᵐⁿᵒᵖʳˢᵗᵘᵛʷˣʸᶻₐₑₕᵢⱼₖₗₘₙₒₚᵣₛₜᵤᵥₓ"

/// a binary Unicode property - ID_Start, ID_Continue, ...
local method hasProperty for Codepoint(self: Codepoint, name: String): Boolean {
  return #builtin.unicodeProperty(self, name)
}

global function fromU32 for Codepoint(value: U32): CastError ! Codepoint {
  return #builtin.intrinsic.CAST_U32_CODEPOINT(value)
}

global method value for Codepoint(self: Codepoint): U32 {
  return #builtin.intrinsic.CAST_CODEPOINT_U32(self)
}

global method isLetter for Codepoint(self: Codepoint): Boolean {
  return self.category().startsWith("L")
}

global method isDigit for Codepoint(self: Codepoint, radix: U8 := 10): Boolean {
  return self.digitValue(radix) != undefined
}

global method isAlphanumeric for Codepoint(self: Codepoint): Boolean {
  return self.isLetter() or self.category().startsWith("N")
}

/// Unicode's White_Space property - short enough to list
global method isWhitespace for Codepoint(self: Codepoint): Boolean {
  let v := self.value()
  let singles: Array<U32> := [0x20, 0x85, 0xA0, 0x1680, 0x2028, 0x2029, 0x202F, 0x205F, 0x3000]
  return (v >= 0x9 and v <= 0xD) or (v >= 0x2000 and v <= 0x200A) or singles.contains(v)
}

global method isUpper for Codepoint(self: Codepoint): Boolean {
  return self.category() == "Lu"
}

global method isLower for Codepoint(self: Codepoint): Boolean {
  return self.category() == "Ll"
}

global method isPunctuation for Codepoint(self: Codepoint): Boolean {
  return self.category().startsWith("P")
}

global method isControl for Codepoint(self: Codepoint): Boolean {
  return self.category() == "Cc"
}

global method isAscii for Codepoint(self: Codepoint): Boolean {
  return self.value() < 0x80
}

global method isIdStart for Codepoint(self: Codepoint): Boolean {
  return (self == '_' or self.hasProperty("ID_Start")) and not scriptLetters.has(self)
}

global method isIdContinue for Codepoint(self: Codepoint): Boolean {
  return self.hasProperty("ID_Continue") and not scriptLetters.has(self)
}

/// any Unicode symbol (category S), plus the ASCII operator characters
global method isSymbol for Codepoint(self: Codepoint): Boolean {
  return self.category().startsWith("S") or ":!#$%&*+./<=>?@\\^|~-".has(self)
}

/// a String - some code points uppercase to several ("ß" to "SS")
global method toUpper for Codepoint(self: Codepoint): String {
  return String.fromCodepoints(#builtin.unicodeUpper(self))
}

global method toLower for Codepoint(self: Codepoint): String {
  return String.fromCodepoints(#builtin.unicodeLower(self))
}

/// 0-9, then a-z / A-Z for 10 and up
global method digitValue for Codepoint(self: Codepoint, radix: U8 := 10): U8? {
  let v := self.value()
  let digit: U32? := v >= 48 and v <= 57 ? v - 48 : v >= 97 and v <= 122 ? v - 87 : v >= 65 and v <= 90 ? v - 55 : undefined
  return digit != undefined and digit < radix as U32 ? digit as U8 : undefined
}

global method utf8Length for Codepoint(self: Codepoint): U8 {
  let v := self.value()
  return v < 0x80 ? 1 : v < 0x800 ? 2 : v < 0x10000 ? 3 : 4
}

global method utf16Length for Codepoint(self: Codepoint): U8 {
  return self.value() < 0x10000 ? 1 : 2
}

/// the Unicode General_Category - "Lu", "Nd", ...
global method category for Codepoint(self: Codepoint): String {
  return #builtin.unicodeCategory(self)
}

method equals(self: Codepoint, other: Codepoint): Boolean {
  return #builtin.intrinsic.EQ_CODEPOINT_CODEPOINT(self, other)
}

method hash(self: Codepoint): U64 {
  return self.value().hash()
}

method compare(self: Codepoint, other: Codepoint): Ordering {
  return #builtin.intrinsic.CMP_CODEPOINT_CODEPOINT(self, other)
}

function min(): Codepoint {
  return '\0'
}

function max(): Codepoint {
  return '\u{10FFFF}'
}

method toString(self: Codepoint): String {
  return String.fromCodepoints([self])
}

function parse(text: String): ParseError ! Codepoint {
  let all := text.codepoints()
  if all.size() != 1 then { error ParseError.new("expected exactly one character, got \"" ++ text ++ "\"") }
  return all[0] ?? '?'
}

method next(self: Codepoint): Codepoint {
  let v := self.value() + 1
  return Codepoint.fromU32(v == 0xD800 ? 0xE000 : v) !? self
}

method previous(self: Codepoint): Codepoint {
  let v := self.value() - 1
  return Codepoint.fromU32(v == 0xDFFF ? 0xD7FF : v) !? self
}

method cast(self: Codepoint): Target {
  return Target == U32 ? self.value() : self.toString()
}

function default(): Codepoint {
  return '\0'
}

local method at for Bytes(self: Bytes, index: U64): U8 {
  return self.memory.offset(index as S64).read()
}

local method put for Bytes(self: Bytes, index: U64, value: U8): Undefined {
  self.memory.offset(index as S64).write(value)
}

local method outOfRange for Bytes(self: Bytes, what: String): IndexError {
  return IndexError.new(what ++ " is past the end of " ++ self.used.toString() ++ " bytes")
}

global function filled for Bytes(size: U64, fill: U8 := 0): Bytes {
  let bytes := Bytes{memory := allocate<U8>(size), used := size}
  bytes.fill(fill, undefined)
  return bytes
}

global function fromArray for Bytes(bytes: Array<U8>): Bytes {
  let result := Bytes.filled(bytes.size())
  for byte, i in bytes {
    result.put(i, byte)
  }
  return result
}

global function fromHex for Bytes(text: String): ParseError ! Bytes {
  let digits := text.trim()
  if digits.size() % 2 != 0 then { error ParseError.new("hex text needs an even number of digits") }
  let result := Bytes.filled(digits.size() / 2)
  for i in 0..<result.size() {
    result.put(i, U8.parse(digits.slice((2 * i)..<(2 * i + 2)) !? "", 16)!!)
  }
  return result
}

/// padding is optional - decoding stops at the first '='
global function fromBase64 for Bytes(text: String): ParseError ! Bytes {
  let alphabet := "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
  let invalid := ParseError.new("not valid base64")
  let sextets: Array<U8> := []
  for c in text.trim() until c == '=' {
    sextets.push(((alphabet.indexOf(c.toString()) ?! invalid)!!) as U8)
  }
  if sextets.size() % 4 == 1 then { error invalid }
  let result: Array<U8> := []
  for chunk in sextets.chunks(4) {
    let n := chunk.size()
    let word := chunk.reduce(0 as U32, λ(acc, v) (acc shl 6) bor (v as U32)).shl((4 - n) * 6)
    for k in 0..<(n - 1) {
      result.push((word.shr(16 - 8 * k) band 0xFF) as U8)
    }
  }
  return Bytes.fromArray(result)
}

global method slice for Bytes(self: Bytes, range: Range<U64>): IndexError ! Bytes {
  let (start, end) := bounds(range)
  if end > self.used or start > end then { error self.outOfRange("range " ++ range.toString()) }
  let result := Bytes.filled(end - start)
  result.copyFrom(self.sliceView(start, end), 0)!!
  return result
}

/// the same memory, a narrower window - for copying out of without an intermediate copy
local method sliceView for Bytes(self: Bytes, start: U64, end: U64): Bytes {
  return Bytes{memory := self.memory.offset(start as S64), used := end - start}
}

global method indexOf for Bytes(self: Bytes, part: Bytes, from: U64 := 0): U64? {
  for start in from..<(self.used + 1) while start + part.used <= self.used if (0..<part.used).all(λ(k) self.at(start + k) == part.at(k)) {
    { return start }
  }
  return undefined
}

global method startsWith for Bytes(self: Bytes, prefix: Bytes): Boolean {
  return prefix.used <= self.used and (0..<prefix.used).all(λ(k) self.at(k) == prefix.at(k))
}

global method endsWith for Bytes(self: Bytes, suffix: Bytes): Boolean {
  let offset := self.used - suffix.used.min(self.used)
  return suffix.used <= self.used and (0..<suffix.used).all(λ(k) self.at(offset + k) == suffix.at(k))
}

/// an empty separator doesn't split at all
global method split for Bytes(self: Bytes, separator: Bytes): Array<Bytes> {
  if separator.isEmpty() then { return [self.clone()] }
  let parts: Array<Bytes> := []
  let from: U64 := 0
  for _ in forever() {
    let found := self.indexOf(separator, from)
    if found == undefined then {
      parts.push(self.slice(from..<self.used) !? Bytes.filled(0))
      return parts
    }
    parts.push(self.slice(from..<found) !? Bytes.filled(0))
    set from := found + separator.used
  }
}

global method fill for Bytes(self: Bytes, value: U8, range: Range<U64>?): Undefined {
  let (start, end) := range == undefined ? (0, self.used) : bounds(range)
  for i in start..<end.min(self.used) {
    self.put(i, value)
  }
}

global method copyFrom for Bytes(self: Bytes, source: Bytes, at: U64 := 0): IndexError ! Undefined {
  if at + source.used > self.used then { error self.outOfRange("writing " ++ source.used.toString() ++ " bytes at " ++ at.toString()) }
  for i in 0..<source.used {
    self.put(at + i, source.at(i))
  }
}

global method reverse for Bytes(self: Bytes): Bytes {
  let result := Bytes.filled(self.used)
  for i in 0..<self.used {
    result.put(self.used - 1 - i, self.at(i))
  }
  return result
}

global method toArray for Bytes(self: Bytes): Array<U8> {
  return Array.generate(self.used, λ(i) self.at(i))
}

global method toHex for Bytes(self: Bytes): String {
  return self.toArray().map(λ(byte) byte.toString(16).padStart(2, '0')).join()
}

global method toBase64 for Bytes(self: Bytes): String {
  let alphabet := "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".codepoints()
  let result: Array<Codepoint> := []
  for chunk in self.toArray().chunks(3) {
    let word := chunk.reduce(0 as U32, λ(acc, byte) (acc shl 8) bor (byte as U32)).shl((3 - chunk.size()) * 8)
    for k in 0..<4 {
      result.push(k <= chunk.size() ? alphabet[(word.shr(18 - 6 * k) band 0x3F) as U64] ?? '=' : '=')
    }
  }
  return String.fromCodepoints(result)
}

global method decode for Bytes<Encoding: UTF8 | UTF16 | UTF32 | ASCII>(self: Bytes): ParseError ! Encoding {
  return Encoding.decode(self)
}

global method readInteger for Bytes<Target>(self: Bytes, at: U64, endian: Little | Big := Little): IndexError ! Target {
  let width := (Target.bits() / 8) as U64
  let raw := self.slice(at..<(at + width))!!
  return Target.fromBytes(endian == Big ? raw.reverse() : raw) !? 0
}

global method readFloat for Bytes<Target>(self: Bytes, at: U64, endian: Little | Big := Little): IndexError ! Target {
  if Target == F16 then { return F16.fromBits(self.readInteger<U16>(at, endian)!!) }
  if Target == F32 then { return F32.fromBits(self.readInteger<U32>(at, endian)!!) }
  return F64.fromBits(self.readInteger<U64>(at, endian)!!)
}

global method writeInteger for Bytes<Source>(self: Bytes, at: U64, value: Source, endian: Little | Big := Little): IndexError ! Undefined {
  let raw := value.toBytes()
  self.copyFrom(endian == Big ? raw.reverse() : raw, at)!!
}

global method writeFloat for Bytes<Source>(self: Bytes, at: U64, value: Source, endian: Little | Big := Little): IndexError ! Undefined {
  self.writeInteger(at, value.toBits(), endian)!!
}

global method toBase64Url for Bytes(self: Bytes): String {
  return self.toBase64().replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "")
}

global function fromBase64Url for Bytes(text: String): ParseError ! Bytes {
  if text.contains("+") or text.contains("/") then {
    error ParseError.new("not base64url: " ++ text)
  }
  return Bytes.fromBase64(text.trim().replaceAll("-", "+").replaceAll("_", "/"))!!
}

/// what CRC-32 does to each byte value, eight bits at a time - worked out once
local const crcTable: Array<U32> := crcTableMade()

local function crcTableMade for Bytes(): Array<U32> {
  let table: Array<U32> := []
  for value in 0..<256 {
    let crc := value as U32
    for _ in 0..<8 {
      set crc := crc band 1 == 1 ? crc shr 1 bxor 0xEDB88320 : crc shr 1
    }
    table.push(crc)
  }
  return table
}

global method crc32 for Bytes(self: Bytes): U32 {
  let crc: U32 := 0xFFFFFFFF
  for byte in self {
    set crc := crcTable[((crc bxor byte as U32) band 0xFF) as U64]!! bxor (crc shr 8)
  }
  return crc bxor 0xFFFFFFFF
}

global method fnv1a for Bytes(self: Bytes): U64 {
  return hashBytes(self, 0xcbf29ce484222325)
}

/// the message padded to whole 64-byte blocks - a 1 bit, zeros, then its length in bits in 8 bytes,
/// big-endian for SHA, little-endian for MD5
local method padded for Bytes(self: Bytes, endian: Little | Big): Bytes {
  let length := Bytes.filled(8)
  length.writeInteger<U64>(0, self.size() * 8, endian)!!
  let zeros := (55 - self.size() % 64 + 64) % 64
  return self ++ Bytes.fromArray([0x80]) ++ Bytes.filled(zeros) ++ length
}

local const sha256Rounds: Array<U32> := [

/// FIPS 180-4's SHA-256 - U32 arithmetic wraps with +%
global method sha256 for Bytes(self: Bytes): Bytes {
  let data := self.padded(Big)
  let h: Array<U32> := [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]
  for block in (0..<data.size()).step(64) {
    let w: Array<U32> := (0..<16).map(λ(t) data.readInteger<U32>(block + t * 4, Big)!!).toArray()
    for t in 16..<64 {
      let s0 := w[t - 15]!!.rotateRight(7) bxor w[t - 15]!!.rotateRight(18) bxor (w[t - 15]!! shr 3)
      let s1 := w[t - 2]!!.rotateRight(17) bxor w[t - 2]!!.rotateRight(19) bxor (w[t - 2]!! shr 10)
      w.push(w[t - 16]!! +% s0 +% w[t - 7]!! +% s1)
    }
    let (a, b, c, d, e, f, g, k) := (h[0]!!, h[1]!!, h[2]!!, h[3]!!, h[4]!!, h[5]!!, h[6]!!, h[7]!!)
    for t in 0..<64 {
      let first := k +% (e.rotateRight(6) bxor e.rotateRight(11) bxor e.rotateRight(25)) +% ((e band f) bxor (bnot e band g)) +% sha256Rounds[t]!! +% w[t]!!
      let second := (a.rotateRight(2) bxor a.rotateRight(13) bxor a.rotateRight(22)) +% ((a band b) bxor (a band c) bxor (b band c))
      set (k, g, f, e, d, c, b, a) := (g, f, e, d +% first, c, b, a, first +% second)
    }
    set h := [h[0]!! +% a, h[1]!! +% b, h[2]!! +% c, h[3]!! +% d, h[4]!! +% e, h[5]!! +% f, h[6]!! +% g, h[7]!! +% k]
  }
  return Bytes.fromIterable(h.flatMap(λ(word) word.toBytes().reverse()))
}

/// FIPS 180-4's SHA-1
global method sha1 for Bytes(self: Bytes): Bytes {
  let data := self.padded(Big)
  let h: Array<U32> := [0x67452301, 0xEFCDAB89, 0x98BADCFE, 0x10325476, 0xC3D2E1F0]
  for block in (0..<data.size()).step(64) {
    let w: Array<U32> := (0..<16).map(λ(t) data.readInteger<U32>(block + t * 4, Big)!!).toArray()
    for t in 16..<80 {
      w.push((w[t - 3]!! bxor w[t - 8]!! bxor w[t - 14]!! bxor w[t - 16]!!).rotateLeft(1))
    }
    let (a, b, c, d, e) := (h[0]!!, h[1]!!, h[2]!!, h[3]!!, h[4]!!)
    for t in 0..<80 {
      let (f, constant) := t < 20 ? ((b band c) bor (bnot b band d), 0x5A827999 as U32) : t < 40 ? (b bxor c bxor d, 0x6ED9EBA1 as U32) : t < 60 ? ((b band c) bor (b band d) bor (c band d), 0x8F1BBCDC as U32) : (b bxor c bxor d, 0xCA62C1D6 as U32)
      let next := a.rotateLeft(5) +% f +% e +% constant +% w[t]!!
      set (e, d, c, b, a) := (d, c, b.rotateLeft(30), a, next)
    }
    set h := [h[0]!! +% a, h[1]!! +% b, h[2]!! +% c, h[3]!! +% d, h[4]!! +% e]
  }
  return Bytes.fromIterable(h.flatMap(λ(word) word.toBytes().reverse()))
}

/// each MD5 round's left rotation
local const md5Shifts: Array<U8> := [7, 12, 17, 22].repeat(4) ++ [5, 9, 14, 20].repeat(4) ++ [4, 11, 16, 23].repeat(4) ++ [6, 10, 15, 21].repeat(4)

/// floor(2^32 * abs(sin(i + 1))) for each round
local const md5Constants: Array<U32> := (0..<64).map(λ(i) ((i + 1) as F64).sin().abs() * 4294967296.0).map(λ(x) x.floor() as U32).toArray()

/// RFC 1321's MD5 - little-endian throughout
global method md5 for Bytes(self: Bytes): Bytes {
  let data := self.padded(Little)
  let h: Array<U32> := [0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476]
  for block in (0..<data.size()).step(64) {
    let m: Array<U32> := (0..<16).map(λ(t) data.readInteger<U32>(block + t * 4, Little)!!).toArray()
    let (a, b, c, d) := (h[0]!!, h[1]!!, h[2]!!, h[3]!!)
    for i in 0..<64 {
      let (f, g) := i < 16 ? ((b band c) bor (bnot b band d), i) : i < 32 ? ((d band b) bor (bnot d band c), (5 * i + 1) % 16) : i < 48 ? (b bxor c bxor d, (3 * i + 5) % 16) : (c bxor (b bor bnot d), (7 * i) % 16)
      let mixed := a +% f +% md5Constants[i]!! +% m[g]!!
      set (a, d, c, b) := (d, c, b, b +% mixed.rotateLeft(md5Shifts[i]!!))
    }
    set h := [h[0]!! +% a, h[1]!! +% b, h[2]!! +% c, h[3]!! +% d]
  }
  return Bytes.fromIterable(h.flatMap(λ(word) word.toBytes()))
}

/// RFC 2104 - the key padded to SHA-256's 64-byte block (hashed first when longer), then
/// sha256((key bxor 0x5c...) ++ sha256((key bxor 0x36...) ++ message))
global method hmacSha256 for Bytes(self: Bytes, key: Bytes): Bytes {
  let block := key.size() > 64 ? key.sha256() : key
  let padded := block ++ Bytes.filled(64 - block.size())
  let inner := Bytes.fromIterable(padded.map(λ(b) b bxor 0x36))
  let outer := Bytes.fromIterable(padded.map(λ(b) b bxor 0x5c))
  return (outer ++ (inner ++ self).sha256()).sha256()
}

global method compress for Bytes(self: Bytes, format: Compression := Compression.Gzip): Bytes {
  let deflated := Bytes.fromArray(deflate(self.toArray()))
  match format {
    case Compression.Deflate then {
      return deflated
    }
    case Compression.Zlib then {
      let checksum := Bytes.filled(4)
      checksum.writeInteger<U32>(0, adler32(self), Big)!!
      return Bytes.fromArray([0x78, 0x5e]) ++ deflated ++ checksum
    }
    case Compression.Gzip then {
      let trailer := Bytes.filled(8)
      trailer.writeInteger<U32>(0, self.crc32(), Little)!!
      trailer.writeInteger<U32>(4, (self.size() % 4294967296) as U32, Little)!!
      return Bytes.fromArray([0x1f, 0x8b, 8, 0, 0, 0, 0, 0, 0, 255]) ++ deflated ++ trailer
    }
  }
}

global method decompress for Bytes(self: Bytes, format: Compression := Compression.Gzip): ParseError ! Bytes {
  match format {
    case Compression.Deflate then {
      /// zlib's own reader, given a zlib header to read past
      return #builtin.zlibDecompress(Bytes.fromArray([0x78, 0x01]) ++ self)!!
    }
    case Compression.Zlib then {
      return #builtin.zlibDecompress(self)!!
    }
    case Compression.Gzip then {
      if self.size() < 18 or self[0] != 0x1f or self[1] != 0x8b or self[2] != 8 then {
        error ParseError.new("not gzip data")
      }
      /// past the header's optional extra field, file name, comment and header checksum
      let flags := self[3]!!
      let at: U64 := 10
      if flags band 4 != 0 then {
        set at += 2 + self.readInteger<U16>(at, Little)!! as U64
      }
      for flag in [8 as U8, 16 as U8] if flags band flag != 0 {
        set at := (self.indexOf(Bytes.filled(1), at) ?! ParseError.new("the gzip header ends too soon")) + 1
      }
      if flags band 2 != 0 then {
        set at += 2
      }
      /// the last 8 bytes are the data's CRC-32 and size
      let end := self.size() - 8
      let data := Bytes.fromArray([0x78, 0x01]) ++ self.slice(at..<end)!!
      let inflated := #builtin.zlibDecompress(data)!!
      if self.readInteger<U32>(end, Little)!! != inflated.crc32() then {
        error ParseError.new("gzip data whose checksum doesn't match")
      }
      return inflated
    }
  }
}

/// RFC 1950's Adler-32 - two sums modulo 65521
local function adler32 for Bytes(data: Bytes): U32 {
  let (a, b) := (1 as U32, 0 as U32)
  for byte in data {
    set a := (a + byte as U32) % 65521
    set b := (b + a) % 65521
  }
  return (b shl 16) bor a
}

/// one fixed-Huffman DEFLATE block (RFC 1951's 3.2.6): each position's longest match of 3 to 258 bytes up
/// to 32 KiB back - found through a chain of the earlier positions whose next 3 bytes hash alike - as a
/// length and a distance, a literal byte where there's none
local function deflate for Bytes(data: Array<U8>): Array<U8> {
  let writer := BitWriter.new()
  writer.putBits(1, 1)
  writer.putBits(1, 2)
  let latest: Map<U64, U64> := Map.of()
  let previous: Map<U64, U64> := Map.of()
  let at: U64 := 0
  for _ in forever() while at < data.size() {
    let best := (length := 0 as U64, distance := 0 as U64)
    let candidate := at + 3 <= data.size() ? latest[tripleHash(data, at)] : undefined
    for _ in 0..<48 while candidate != undefined and at - candidate < 32768 {
      let length := (0..<(data.size() - at).min(258)).takeWhile(λ(k) data[candidate + k] == data[at + k]).count(λ(k) true)
      if length > best.length then {
        set best := (length := length, distance := at - candidate)
      }
      set candidate := previous[candidate]
    }
    let step := best.length >= 3 ? best.length : 1
    if best.length >= 3 then {
      writer.putMatch(best.length, best.distance)
    } else {
      writer.putFixed(data[at]!! as U64)
    }
    for p in at..<at + step if p + 3 <= data.size() {
      let hash := tripleHash(data, p)
      if latest.has(hash) then {
        previous.set(p, latest[hash]!!)
      }
      latest.set(hash, p)
    }
    set at += step
  }
  writer.putFixed(256)
  return writer.finish()
}

local function tripleHash for Bytes(data: Array<U8>, at: U64): U64 {
  return ((data[at]!! as U64 shl 10) bxor (data[at + 1]!! as U64 shl 5) bxor data[at + 2]!! as U64) band 0x7FFF
}

local function new for BitWriter(): BitWriter {
  return BitWriter{out := [], buffer := 0, count := 0}
}

local method putBits for BitWriter(self: BitWriter, value: U64, bits: U64): Undefined {
  set self.buffer := self.buffer bor (value shl self.count)
  set self.count += bits
  for _ in forever() while self.count >= 8 {
    self.out.push((self.buffer band 0xFF) as U8)
    set self.buffer := self.buffer shr 8
    set self.count -= 8
  }
}

/// a Huffman code - written most significant bit first, so reversed
local method putCode for BitWriter(self: BitWriter, code: U64, bits: U64): Undefined {
  self.putBits((0..<bits).reduce(0 as U64, λ(out, i) (out shl 1) bor ((code shr i) band 1)), bits)
}

/// a literal or length symbol in the fixed code
local method putFixed for BitWriter(self: BitWriter, symbol: U64): Undefined {
  if symbol < 144 then {
    self.putCode(0x30 + symbol, 8)
  } else if symbol < 256 then {
    self.putCode(0x190 + symbol - 144, 9)
  } else if symbol < 280 then {
    self.putCode(symbol - 256, 7)
  } else {
    self.putCode(0xC0 + symbol - 280, 8)
  }
}

local const lengthBases: Array<U64> := [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258]

local const lengthExtras: Array<U64> := [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0]

local const distanceBases: Array<U64> := [1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385, 24577]

local const distanceExtras: Array<U64> := [0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13]

local method putMatch for BitWriter(self: BitWriter, length: U64, distance: U64): Undefined {
  let l := lengthBases.lastIndexWhere(λ(base) base <= length)!!
  self.putFixed(257 + l)
  self.putBits(length - lengthBases[l]!!, lengthExtras[l]!!)
  let d := distanceBases.lastIndexWhere(λ(base) base <= distance)!!
  self.putCode(d, 5)
  self.putBits(distance - distanceBases[d]!!, distanceExtras[d]!!)
}

/// the last partial byte, padded with zeros
local method finish for BitWriter(self: BitWriter): Array<U8> {
  if self.count > 0 then {
    self.out.push((self.buffer band 0xFF) as U8)
  }
  return self.out
}

method equals(self: Bytes, other: Bytes): Boolean {
  return self.used == other.used and (0..<self.used).all(λ(i) self.at(i) == other.at(i))
}

method hash(self: Bytes): U64 {
  return hashBytes(self)
}

/// the first differing byte decides; a prefix sorts first
method compare(self: Bytes, other: Bytes): Ordering {
  for i in 0..<self.used.min(other.used) {
    let order := self.at(i).compare(other.at(i))
    if order != Ordering.Equal then { return order }
  }
  return self.used.compare(other.used)
}

method toString(self: Bytes): String {
  return self.toHex()
}

method iterator(self: Bytes): Iterator<U8> {
  for i in 0..<self.used {
    yield self.at(i)
  }
}

function fromIterable(items: Iterable<U8>): Bytes {
  return Bytes.fromArray(items.toArray())
}

method contains(self: Bytes, item: U8): Boolean {
  return (0..<self.used).any(λ(i) self.at(i) == item)
}

method size(self: Bytes): U64 {
  return self.used
}

method isEmpty(self: Bytes): Boolean {
  return self.used == 0
}

method get(self: Bytes, key: U64): U8? {
  return key < self.used ? self.at(key) : undefined
}

method set(self: Bytes, key: U64, value: U8): Error ! Undefined {
  if key >= self.used then { error self.outOfRange("index " ++ key.toString()) }
  self.put(key, value)
}

method concat(self: Bytes, other: Bytes): Bytes {
  let result := Bytes.filled(self.used + other.used)
  result.copyFrom(self, 0)!!
  result.copyFrom(other, self.used)!!
  return result
}

function default(): Bytes {
  return Bytes.filled(0)
}

method clone(self: Bytes): Bytes {
  let copy := Bytes.filled(self.used)
  copy.copyFrom(self, 0) !? undefined
  return copy
}

method equals(self: Compression, other: Compression): Boolean {
  return self.index() == other.index()
}

method hash(self: Compression): U64 {
  return self.index().hash()
}

method toString(self: Compression): String {
  return self.variantName()
}

global function parse for Json(text: String): ParseError ! Unknown {
  let reader := DocumentReader.of(text)
  let value := reader.jsonValue()!!
  reader.skipSpace()
  if not reader.atEnd() then {
    error reader.failure("JSON", "something after the document")
  }
  return value
}

global function decode for Json<Target>(text: String): ParseError ! Target {
  return decoded<Target>(Json.parse(text)!!, "the document")!!
}

global function encode for Json(value: Unknown, indent: U64 := 0): String {
  return writeJson(value, " ".repeat(indent), "")
}

method toString(self: Json): String {
  return Json.encode(self)
}

/// every row's fields - RFC 4180: a quoted field may hold separators, line breaks and quotes written twice
global function parse for Csv(text: String, separator: Codepoint := ','): ParseError ! Array<Array<String>> {
  let rows: Array<Array<String>> := []
  let row: Array<String> := []
  let field: Array<Codepoint> := []
  let (quoted, wasQuoted, line) := (false, false, 1 as U64)
  let chars := text.codepoints()
  let i: U64 := 0
  for _ in forever() while i < chars.size() {
    let c := chars[i]!!
    set i += 1
    if quoted then {
      if c == '"' and chars[i] == '"' then {
        field.push('"')
        set i += 1
      } else if c == '"' then {
        set quoted := false
      } else {
        set line += c == '\n' ? 1 : 0
        field.push(c)
      }
    } else if c == '"' then {
      if not field.isEmpty() then {
        error ParseError.new("not CSV - a quote in the middle of a field, on line " ++ line.toString())
      }
      set (quoted, wasQuoted) := (true, true)
    } else if c == separator then {
      row.push(String.fromCodepoints(field))
      set (field, wasQuoted) := ([], false)
    } else if c == '\n' then {
      row.push(String.fromCodepoints(field))
      rows.push(row)
      set (row, field, wasQuoted) := ([], [], false)
      set line += 1
    } else if c != '\r' or chars[i] != '\n' then {
      if wasQuoted then {
        error ParseError.new("not CSV - text after a quoted field's closing quote, on line " ++ line.toString())
      }
      field.push(c)
    }
  }
  if quoted then {
    error ParseError.new("not CSV - a quoted field that never ends, on line " ++ line.toString())
  }
  if not field.isEmpty() or not row.isEmpty() or wasQuoted then {
    row.push(String.fromCodepoints(field))
    rows.push(row)
  }
  return rows
}

global function records for Csv(text: String, separator: Codepoint := ','): ParseError ! Array<Map<String, String>> {
  let rows := Csv.parse(text, separator)!!
  let header := rows[0] ?? []
  return rows.drop(1).enumerate().map(λ((i, row)) {
    if row.size() != header.size() then {
      error ParseError.new("not CSV - " ++ row.size().toString() ++ " field(s) where the header has " ++ header.size().toString() ++ ", on line " ++ (i + 2).toString())
    }
    return Map.fromIterable(header.zip(row))
  }).toArray()
}

/// each record's fields by name into a Row - an empty field undefined unless the field is text
global function decode for Csv<Row>(text: String, separator: Codepoint := ','): ParseError ! Table<Row> {
  let fields := Type.of<Row>().fields()
  let rows := Csv.records(text, separator)!!.enumerate().map(λ((i, record)) {
    let values := fields.entries().map(λ((name, type)) {
      let cell := record[name]
      return (name, decodedAs(cell == "" and type.name() != "String" ? undefined : cell, type.name(), "row " ++ (i + 1).toString() ++ "'s " ++ name)!!)
    })
    return #runtime.construct(Type.of<Row>(), Map.fromIterable(values))!! as Row
  })
  return Table.fromRows(rows)
}

global function write for Csv(rows: Iterable<Iterable<Unknown>>, separator: Codepoint := ','): String {
  let mark := separator.toString()
  let field := λ(value: Unknown) {
    let text := value == undefined ? "" : value.toString()
    return text.contains(mark) or text.contains("\"") or text.contains("\n") or text.contains("\r") ? "\"" ++ text.replaceAll("\"", "\"\"") ++ "\"" : text
  }
  return rows.map(λ(row) row.map(field).join(mark) ++ "\n").join("")
}

/// a header row of Row's fields, then each row's fields in that order
global function encode for Csv<Row>(rows: Table<Row>, separator: Codepoint := ','): String {
  let names := rows.columns()
  return Csv.write([names, ..rows.toArray().map(λ(row) names.map(λ(name) row.get(name)))], separator)
}

global function parse for Toml(text: String): ParseError ! Map<String, Unknown> {
  let reader := DocumentReader.of(text)
  let root: Map<String, Unknown> := Map.of()
  let current := root
  for _ in forever() {
    reader.tomlSpace()
    if reader.atEnd() then {
      return root
    }
    if reader.take("[[") then {
      /// [[a.b]] - one more table in the array a.b
      let path := reader.tomlKey()!!
      if not reader.take("]]") then {
        error reader.failure("TOML", "expected ']]'")
      }
      let made: Map<String, Unknown> := Map.of()
      let list := reader.tomlTable(root, path.dropLast(1))!!.getOrInsert(path.last()!!, λ [] as Array<Unknown>)
      list.narrow<Array<Unknown>>()?.push(made) ?! reader.failure("TOML", path.join(".") ++ " isn't an array of tables")
      set current := made
    } else if reader.take("[") then {
      let path := reader.tomlKey()!!
      if not reader.take("]") then {
        error reader.failure("TOML", "expected ']'")
      }
      set current := reader.tomlTable(root, path)!!
    } else {
      let key := reader.tomlKey()!!
      if not reader.take("=") then {
        error reader.failure("TOML", "expected '='")
      }
      reader.tomlPut(current, key, reader.tomlValue()!!)!!
    }
    reader.tomlBlank()
    if not reader.atEnd() and reader.peek() != '\n' and reader.peek() != '\r' then {
      error reader.failure("TOML", "expected the end of the line")
    }
  }
}

global function decode for Toml<Target>(text: String): ParseError ! Target {
  return decoded<Target>(Toml.parse(text)!!, "the document")!!
}

/// spaces and a comment, up to the end of the line
local method tomlBlank for DocumentReader(self: DocumentReader): Undefined {
  for _ in forever() while self.peek() == ' ' | '\t' {
    set self.at += 1
  }
  if self.peek() == '#' then {
    for _ in forever() while self.peek() != undefined and self.peek() != '\n' {
      set self.at += 1
    }
  }
}

/// blank lines and comments too
local method tomlSpace for DocumentReader(self: DocumentReader): Undefined {
  for _ in forever() {
    self.tomlBlank()
    if not (self.take("\n") or self.take("\r")) then {
      return undefined
    }
  }
}

/// a dotted key's parts - a.b."c d"
local method tomlKey for DocumentReader(self: DocumentReader): ParseError ! Array<String> {
  let parts: Array<String> := []
  for _ in forever() {
    self.tomlBlank()
    let part := self.peek() == '"' ? self.tomlBasicString()!! : self.peek() == '\'' ? self.tomlLiteralString()!! : String.fromCodepoints(self.takeWhile(λ(c) c.isAscii() and c.isAlphanumeric() or c == '_' | '-'))
    if part == "" then {
      error self.failure("TOML", "expected a key")
    }
    parts.push(part)
    self.tomlBlank()
    if not self.take(".") then {
      return parts
    }
  }
}

local method takeWhile for DocumentReader(self: DocumentReader, where: Lambda<Codepoint, Boolean>): Array<Codepoint> {
  let start := self.at
  for _ in forever() while self.peek()?.map(where) == true {
    set self.at += 1
  }
  return self.text.slice(start..<self.at)!!
}

/// the table a path of keys leads to from root - each made when missing; an array of tables' last
local method tomlTable for DocumentReader(self: DocumentReader, root: Map<String, Unknown>, path: Array<String>): ParseError ! Map<String, Unknown> {
  let at := root
  for part in path {
    let next := at.getOrInsert(part, λ Map<String, Unknown>.of())
    set at := next.narrow<Map<String, Unknown>>() ?? next.narrow<Array<Unknown>>()?.last()?.narrow<Map<String, Unknown>>() ?! self.failure("TOML", part ++ " is already a value, not a table")
  }
  return at
}

local method tomlPut for DocumentReader(self: DocumentReader, table: Map<String, Unknown>, key: Array<String>, value: Unknown): ParseError ! Undefined {
  let at := self.tomlTable(table, key.dropLast(1))!!
  if at.has(key.last()!!) then {
    error self.failure("TOML", key.join(".") ++ " is set twice")
  }
  at.set(key.last()!!, value)
}

local method tomlValue for DocumentReader(self: DocumentReader): ParseError ! Unknown {
  self.tomlBlank()
  match self.peek() {
    case '"' then {
      return self.tomlBasicString()!!
    }
    case '\'' then {
      return self.tomlLiteralString()!!
    }
    case '[' then {
      set self.at += 1
      let items: Array<Unknown> := []
      for _ in forever() {
        self.tomlSpace()
        if self.take("]") then {
          return items
        }
        items.push(self.tomlValue()!!)
        self.tomlSpace()
        if not self.take(",") and self.peek() != ']' then {
          error self.failure("TOML", "expected ',' or ']'")
        }
      }
    }
    case '{' then {
      set self.at += 1
      let table: Map<String, Unknown> := Map.of()
      self.tomlBlank()
      if self.take("}") then {
        return table
      }
      for _ in forever() {
        let key := self.tomlKey()!!
        if not self.take("=") then {
          error self.failure("TOML", "expected '='")
        }
        self.tomlPut(table, key, self.tomlValue()!!)!!
        self.tomlBlank()
        if self.take("}") then {
          return table
        }
        if not self.take(",") then {
          error self.failure("TOML", "expected ',' or '}'")
        }
      }
    }
    case _ then {
      return self.tomlBare()!!
    }
  }
}

/// a basic string's escapes - \uXXXX and \UXXXXXXXX too
local method tomlEscape for DocumentReader(self: DocumentReader): ParseError ! Codepoint {
  let escaped := self.peek() ?! self.failure("TOML", "a string that never ends")
  set self.at += 1
  if escaped == 'u' | 'U' then {
    return Codepoint.fromU32(self.hex(escaped == 'u' ? 4 : 8)!!) !? (error self.failure("TOML", "an escape that's no codepoint"))
  }
  let index := "\"\\bfnrte".indexOf(escaped.toString()) ?! self.failure("TOML", "'\\" ++ escaped.toString() ++ "' isn't an escape")
  return ['"', '\\', '\u{8}', '\u{c}', '\n', '\r', '\t', '\u{1b}'][index]!!
}

/// "..." or """...""" - a multi-line one drops a line break right after its opening quotes, and a
/// backslash ending a line drops the break and the whitespace after it
local method tomlBasicString for DocumentReader(self: DocumentReader): ParseError ! String {
  let out: Array<Codepoint> := []
  let multiLine := self.take("\"\"\"")
  if multiLine then {
    self.take("\r")
    self.take("\n")
  } else {
    set self.at += 1
  }
  for _ in forever() {
    if multiLine and self.take("\"\"\"") then {
      /// up to two more quotes belong to the string
      for _ in 0..<2 if self.take("\"") {
        out.push('"')
      }
      return String.fromCodepoints(out)
    }
    let c := self.peek() ?! self.failure("TOML", "a string that never ends")
    set self.at += 1
    if not multiLine and c == '"' then {
      return String.fromCodepoints(out)
    }
    if not multiLine and c == '\n' then {
      error self.failure("TOML", "a string that never ends")
    }
    if c != '\\' then {
      out.push(c)
    } else if multiLine and self.peek() == ' ' | '\t' | '\n' | '\r' then {
      self.takeWhile(λ(w) w == ' ' | '\t' | '\n' | '\r')
    } else {
      out.push(self.tomlEscape()!!)
    }
  }
}

/// '...' or '''...''' - no escapes
local method tomlLiteralString for DocumentReader(self: DocumentReader): ParseError ! String {
  let multiLine := self.take("'''")
  if multiLine then {
    self.take("\n")
  } else {
    set self.at += 1
  }
  let out: Array<Codepoint> := []
  for _ in forever() {
    if multiLine and self.take("'''") then {
      for _ in 0..<2 if self.take("'") {
        out.push('\'')
      }
      return String.fromCodepoints(out)
    }
    let c := self.peek() ?! self.failure("TOML", "a string that never ends")
    set self.at += 1
    if not multiLine and c == '\'' then {
      return String.fromCodepoints(out)
    }
    if not multiLine and c == '\n' then {
      error self.failure("TOML", "a string that never ends")
    }
    out.push(c)
  }
}

/// a number, boolean, date or time written bare - up to a separator; a space only inside a date-time
local method tomlBare for DocumentReader(self: DocumentReader): ParseError ! Unknown {
  let start := self.at
  for _ in forever() while self.peek() != undefined and not "\n\r,]}#".contains(self.peek()!!.toString()) and (self.peek() != ' ' or (self.at - start == 10 and self.peek(1)?.isDigit() == true)) {
    set self.at += 1
  }
  let word := String.fromCodepoints(self.text.slice(start..<self.at)!!)
  let bad := λ(what: String) self.failure("TOML", word ++ " isn't " ++ what)
  match word {
    case "true" then { return true }
    case "false" then { return false }
    case "inf" | "+inf" then { return F64.infinity() }
    case "-inf" then { return -F64.infinity() }
    case "nan" | "+nan" | "-nan" then { return F64.nan() }
    case "" then { error self.failure("TOML", "expected a value") }
    case _ then {}
  }
  if word.size() >= 8 and word.charAt(2) == ':' then {
    return TimeOfDay.parse(word) !? (error bad("a time"))
  }
  if word.size() >= 10 and word.charAt(4) == '-' and word.charAt(7) == '-' then {
    let iso := word.replace(" ", "T")
    if iso.size() == 10 then {
      return Date.parse(iso) !? (error bad("a date"))
    }
    let zoned := iso.endsWith("Z") or iso.endsWith("z") or iso.slice(19..<iso.size())!!.contains(#regex"[+-]")
    return zoned ? Instant.parse(iso) !? (error bad("a date-time")) : DateTime.parse(iso) !? (error bad("a date-time"))
  }
  if word.contains("__") or word.startsWith("_") or word.endsWith("_") then {
    error bad("a number - a misplaced _")
  }
  let digits := word.replaceAll("_", "")
  for (prefix, radix) in [("0x", 16 as U8), ("0o", 8 as U8), ("0b", 2 as U8)] if digits.startsWith(prefix) {
    return digits.slice(2..<digits.size())!!.toInteger(radix) !? (error bad("a number"))
  }
  if digits.contains(#regex"[.eE]") then {
    return digits.toNumber() !? (error bad("a number"))
  }
  if digits.stripPrefix("+")?.startsWith("0") == true and digits.size() > 2 or digits.stripPrefix("-")?.startsWith("0") == true and digits.size() > 2 or digits.startsWith("0") and digits.size() > 1 then {
    error bad("a number - a leading zero")
  }
  return digits.stripPrefix("+")?.toInteger() ?? digits.toInteger() !? (error bad("a value"))
}

/// the first document's lines that hold something - their indents, texts without the indent and
/// comments, numbers - read as blocks by indentation
global function parse for Yaml(text: String): ParseError ! Unknown {
  let raw := text.replaceAll("\r\n", "\n").split("\n")
  let lines: Array<YamlLine> := []
  let started := false
  for full, i in raw {
    if full.startsWith("---") then {
      if started then {
        break full
      }
      set started := true
      continue full
    }
    if full.startsWith("...") then {
      break full
    }
    if full.startsWith("%") then {
      continue full
    }
    if full.slice(0..<full.size() - full.trimStart().size())!!.contains("\t") then {
      error yamlFailure(i + 1, "a tab in the indentation")
    }
    let content := uncommented(full)
    if content.isBlank() then {
      continue full
    }
    set started := true
    lines.push(YamlLine{indent := content.size() - content.trimStart().size(), text := content.trimStart(), number := i + 1})
  }
  if lines.isEmpty() then {
    return undefined
  }
  let reader := YamlReader{lines, at := 0, raw}
  let value := reader.block()!!
  if reader.lines[reader.at] != undefined then {
    error yamlFailure(reader.lines[reader.at]!!.number, "a line that doesn't fit where it's indented")
  }
  return value
}

global function decode for Yaml<Target>(text: String): ParseError ! Target {
  return decoded<Target>(Yaml.parse(text)!!, "the document")!!
}

local function yamlFailure for Yaml(line: U64, what: String): ParseError {
  return ParseError.new("not YAML (or not the YAML this reads) - " ++ what ++ ", on line " ++ line.toString())
}

/// the text before a # that starts a comment - one after whitespace, outside quotes
local function uncommented for Yaml(text: String): String {
  let quote: Codepoint? := undefined
  for c, i in text.codepoints() {
    if quote == undefined and c == '#' and (i == 0 or text.charAt(i - 1)!!.isWhitespace()) then {
      return text.slice(0..<i)!!.trimEnd()
    }
    if quote == undefined and c == '"' | '\'' then {
      set quote := c
    } else if c == quote then {
      set quote := undefined
    }
  }
  return text.trimEnd()
}

/// "key: value" as (key, value) - the first ": ", or a ":" ending the text, outside quotes and brackets
local function splitKey for Yaml(text: String): (String, String)? {
  let quote: Codepoint? := undefined
  let depth := 0
  for c, i in text.codepoints() {
    if quote != undefined then {
      if c == quote then {
        set quote := undefined
      }
    } else if c == '"' | '\'' then {
      set quote := c
    } else if c == '[' | '{' then {
      set depth += 1
    } else if c == ']' | '}' then {
      set depth -= 1
    } else if c == ':' and depth == 0 and (i + 1 == text.size() or text.charAt(i + 1) == ' ') then {
      return (text.slice(0..<i)!!.trim(), text.slice(i + 1..<text.size())!!.trim())
    }
  }
  return undefined
}

/// a plain or quoted scalar - YAML 1.2's core schema: null ~, true false, integers, floats, the rest text
local function scalar for Yaml(text: String, line: U64): ParseError ! Unknown {
  let word := text.trim()
  if word.startsWith("\"") then {
    return Json.parse(word) !? (error yamlFailure(line, word ++ " isn't a quoted string"))
  }
  if word.startsWith("'") then {
    return word.stripPrefix("'")?.stripSuffix("'")?.replaceAll("''", "'") ?! yamlFailure(line, word ++ " isn't a quoted string")
  }
  match word {
    case "" | "~" | "null" | "Null" | "NULL" then { return undefined }
    case "true" | "True" | "TRUE" then { return true }
    case "false" | "False" | "FALSE" then { return false }
    case ".inf" | "+.inf" then { return F64.infinity() }
    case "-.inf" then { return -F64.infinity() }
    case ".nan" then { return F64.nan() }
    case _ then {}
  }
  if word.startsWith("&") or word.startsWith("*") or word.startsWith("!") then {
    error yamlFailure(line, "anchors, aliases and tags aren't read")
  }
  return word.toInteger() ?? word.stripPrefix("0x")?.toInteger(16) ?? word.toNumber() ?? word
}

/// a value on one line - [flow], {flow}, or a scalar
local function inline for Yaml(text: String, line: U64): ParseError ! Unknown {
  let word := text.trim()
  let parts := λ topLevelParts(word.slice(1..<word.size() - 1)!!, ',').filter(λ(part) part != "")
  if word.startsWith("[") and word.endsWith("]") then {
    return parts().map(λ(part) inline(part, line)!!).toArray()
  }
  if word.startsWith("{") and word.endsWith("}") then {
    return Map.fromIterable(parts().map(λ(part) {
      let (key, value) := splitKey(part) ?! yamlFailure(line, part ++ " isn't key: value")
      return (scalar(key, line)!!.toString(), inline(value, line)!!)
    }))
  }
  return scalar(word, line)!!
}

/// text split at each separator outside brackets and quotes
local function topLevelParts for Yaml(text: String, separator: Codepoint): Array<String> {
  let parts: Array<String> := []
  let (depth, start) := (0, 0 as U64)
  for c, i in text.codepoints() {
    set depth += c == '[' | '{' ? 1 : c == ']' | '}' ? -1 : 0
    if c == separator and depth == 0 then {
      parts.push(text.slice(start..<i)!!.trim())
      set start := i + 1
    }
  }
  parts.push(text.slice(start..<text.size())!!.trim())
  return parts
}

local method isItem for YamlLine(self: YamlLine): Boolean {
  return self.text == "-" or self.text.startsWith("- ")
}

/// the value at the line being read - a sequence, a mapping or one scalar
local method block for YamlReader(self: YamlReader): ParseError ! Unknown {
  let first := self.lines[self.at] ?! yamlFailure(0, "nothing to read")
  if first.isItem() then {
    return self.sequence(first.indent)!!
  }
  if splitKey(first.text) != undefined then {
    return self.mapping(first.indent)!!
  }
  set self.at += 1
  return inline(first.text, first.number)!!
}

/// what follows a "key:" or "- " - the rest of the line, a block scalar, or a block on the lines below
local method after for YamlReader(self: YamlReader, rest: String, indent: U64, line: U64): ParseError ! Unknown {
  if rest.startsWith("|") or rest.startsWith(">") then {
    return self.blockScalar(rest, indent, line)
  }
  if rest != "" then {
    return inline(rest, line)!!
  }
  let next := self.lines[self.at]
  if next == undefined or next.indent < indent or (next.indent == indent and not next.isItem()) then {
    return undefined
  }
  return next.indent == indent ? self.sequence(indent)!! : self.block()!!
}

local method mapping for YamlReader(self: YamlReader, indent: U64): ParseError ! Map<String, Unknown> {
  let map: Map<String, Unknown> := Map.of()
  for _ in forever() {
    let line := self.lines[self.at]
    if line == undefined or line.indent < indent then {
      return map
    }
    if line.indent > indent then {
      error yamlFailure(line.number, "a line indented more than the mapping it's in")
    }
    let (key, rest) := splitKey(line.text) ?? (return map)
    set self.at += 1
    let name := scalar(key, line.number)!!.toString()
    if map.has(name) then {
      error yamlFailure(line.number, name ++ " is set twice")
    }
    map.set(name, self.after(rest, indent, line.number)!!)
  }
}

local method sequence for YamlReader(self: YamlReader, indent: U64): ParseError ! Array<Unknown> {
  let items: Array<Unknown> := []
  for _ in forever() {
    let line := self.lines[self.at]
    if line == undefined or line.indent != indent or not line.isItem() then {
      return items
    }
    let rest := line.text.stripPrefix("-")!!.trimStart()
    /// "- key: value" starts a mapping indented as far as key
    if splitKey(rest) != undefined and not rest.startsWith(#regex"[\[{\"']") then {
      let inner := indent + line.text.size() - rest.size()
      set self.lines[self.at] := YamlLine{indent := inner, text := rest, number := line.number}
      items.push(self.mapping(inner)!!)
    } else {
      set self.at += 1
      items.push(self.after(rest, indent + 1, line.number)!!)
    }
  }
}

/// a | or > block scalar - the raw lines after line `from` indented past `parent`; > folds single line
/// breaks into spaces; a - after it drops the last line break, a + keeps every trailing one
local method blockScalar for YamlReader(self: YamlReader, header: String, parent: U64, from: U64): String {
  let body := self.raw.drop(from).takeWhile(λ(raw) raw.isBlank() or raw.size() - raw.trimStart().size() > parent).toArray()
  /// the line reader skips them too
  for _ in forever() while self.lines[self.at]?.number?.let(λ(n) n <= from + body.size()) == true {
    set self.at += 1
  }
  let indent := body.filter(λ(raw) not raw.isBlank()).map(λ(raw) raw.size() - raw.trimStart().size()).min() ?? 0
  let lines := body.map(λ(raw) raw.isBlank() ? "" : raw.slice(indent..<raw.size())!!).toArray()
  let trailing := lines.reverse().takeWhile(λ(line) line == "").count(λ(_) true)
  let kept := lines.take(lines.size() - trailing)
  let text := header.startsWith(">") ? kept.enumerate().map(λ((i, line)) i == 0 ? line : line == "" or kept[i - 1] == "" or line.startsWith(" ") ? "\n" ++ line : " " ++ line).join("") : kept.join("\n")
  return header.contains("-") ? text : header.contains("+") ? text ++ "\n".repeat(trailing + 1) : text ++ "\n"
}

global function parse for Arguments<Options: Struct>(args: Array<String>, defaults: Options): ParseError ! Options {
  let fields := fieldsOfDefaults(defaults)
  let values := flagValues(args, fields)!!
  let filled := defaults.clone()
  for (field, value) in fields.zip(values) {
    set #runtime.fieldsOf(filled)[field.name] := value
  }
  return filled
}

global function help for Arguments<Options: Struct>(defaults: Options, usage: String := ""): String {
  return helpText(fieldsOfDefaults(defaults), usage)
}

global function parseFields for Arguments<Options: Struct>(args: Array<String>, fields: Array<ArgumentField>): ParseError ! Options {
  let values := flagValues(args, fields)!!
  return #runtime.construct(Type.of<Options>(), Map.fromIterable(fields.zip(values).map(λ((field, value)) (field.name, value))))!! as Options
}

global function helpFields for Arguments(fields: Array<ArgumentField>, usage: String := ""): String {
  return helpText(fields, usage)
}

@effects(&stdout, &stderr)
global function forMain for Arguments<Options: Struct>(args: Array<String>, fields: Array<ArgumentField>, usage: String := ""): Options {
  let before := args.take(args.indexOf("--") ?? args.size()).toArray()
  let hTaken := fields.any(λ(field) shortOf(fields, field) == "h")
  if before.contains("--help") or (not hTaken and before.contains("-h")) then {
    &stdout.writeText(helpText(fields, usage) ++ "\n")
    exit(0)
  }
  match Arguments.parseFields<Options>(args, fields) {
    case Error(e) then {
      &stderr.writeText("error: " ++ e.message() ++ "\n\n" ++ helpText(fields, usage) ++ "\n")
      exit(2)
    }
    case options then {
      return options
    }
  }
}

/// a struct value's fields as flags - each one's default its value in defaults
local function fieldsOfDefaults for Arguments(defaults: Struct): Array<ArgumentField> {
  return Type.of(defaults).fields().entries().map(λ((name, type)) ArgumentField{name, type := type.name(), description := "", short := undefined, value := #runtime.fieldsOf(defaults)[name], required := false}).toArray()
}

/// rest and passed aren't flags - they take the arguments that aren't, and those after --
local function notAFlag for Arguments(field: ArgumentField): Boolean {
  return field.name == "rest" or field.name == "passed"
}

/// the letter -x names a field by: its own short ("" for none), or its first letter when it's alone in
/// starting with it
local function shortOf for Arguments(fields: Array<ArgumentField>, field: ArgumentField): String? {
  if field.short != undefined then {
    return field.short == "" ? undefined : field.short
  }
  let first := field.name.charAt(0)!!.toString()
  let sharing := fields.count(λ(other) not notAFlag(other) and other.name.startsWith(first))
  return notAFlag(field) or fields.any(λ(other) other.short == first) or sharing != 1 ? undefined : first
}

/// each field's value from args, in fields' order - the flag given, or else the field's default
local function flagValues for Arguments(args: Array<String>, fields: Array<ArgumentField>): ParseError ! Array<Unknown> {
  let values: Array<Unknown> := fields.map(λ(field) field.value).toArray()
  let given := fields.map(λ(_) false).toArray()
  let lists: Map<U64, Array<String>> := Map.of()
  let positional: Array<String> := []
  let passed: Array<String> := []
  let passedAt := fields.findIndex(λ(field) field.name == "passed")
  let i: U64 := 0
  let optionsOver := false
  for _ in forever() while i < args.size() {
    let arg := args[i]!!
    set i += 1
    if optionsOver then {
      (passedAt == undefined ? positional : passed).push(arg)
      continue _
    }
    if not arg.startsWith("-") or arg == "-" then {
      positional.push(arg)
      continue _
    }
    if arg == "--" then {
      set optionsOver := true
      continue _
    }
    /// --name=value, --name value, --flag, --no-flag, -n value
    let (body, value) := arg.stripPrefix("--") ?? arg.stripPrefix("-")!!.splitOnce("=")?.let(λ((b, v)) (b, v as String?)) ?? (arg.stripPrefix("--") ?? arg.stripPrefix("-")!!, undefined)
    let long := arg.startsWith("--")
    let index := long ? fields.findIndex(λ(field) not notAFlag(field) and flagName(field.name) == body) : fields.findIndex(λ(field) shortOf(fields, field) == body)
    let negated := long and index == undefined and body.startsWith("no-")
    let target := index ?? (negated ? fields.findIndex(λ(field) flagName(field.name) == body.stripPrefix("no-") and field.type == "Boolean") : undefined) ?! ParseError.new("unknown option " ++ arg)
    let field := fields[target]!!
    let type := field.type.stripSuffix("?") ?? field.type
    set given[target] := true
    if type == "Boolean" and value == undefined then {
      set values[target] := not negated
      continue _
    }
    if negated then {
      error ParseError.new(arg ++ " takes no value")
    }
    let list := type.startsWith("Array<") or type.startsWith("Set<")
    /// a flag that can be given alone takes its value only after =
    if value == undefined and field.alone != undefined then {
      if list then {
        lists.getOrInsert(target, λ [])
      } else {
        set values[target] := field.alone
      }
      continue _
    }
    let text := value ?? args[i] ?! ParseError.new(arg ++ " needs a value")
    if value == undefined then {
      set i += 1
    }
    if list then {
      let items := lists.getOrInsert(target, λ [])
      items.pushAll(field.separator == "" ? [text] : text.split(field.separator).map(λ(item) item.trim()).filter(λ(item) item != ""))
    } else {
      set values[target] := decodedAs(text, type, "--" ++ flagName(field.name))!!
    }
  }
  for (target, texts) in lists.entries() {
    set values[target] := decodedAs(texts, fields[target]!!.type, "--" ++ flagName(fields[target]!!.name))!!
  }
  if not positional.isEmpty() then {
    let rest := fields.findIndex(λ(field) field.name == "rest") ?! ParseError.new("unexpected argument " ++ positional[0]!!)
    set values[rest] := decodedAs(positional, fields[rest]!!.type, "the arguments")!!
    set given[rest] := true
  }
  if passedAt != undefined and not passed.isEmpty() then {
    set values[passedAt] := decodedAs(passed, fields[passedAt]!!.type, "the arguments after --")!!
    set given[passedAt] := true
  }
  for (field, wasGiven) in fields.zip(given) {
    if field.required and not wasGiven then {
      error ParseError.new(field.name == "rest" ? "arguments are missing" : field.name == "passed" ? "arguments after -- are missing" : "--" ++ flagName(field.name) ++ " is required")
    }
  }
  return values
}

/// usage, then a line per flag - its type, then its description, and its default or that it's required.
/// A flag too long to line the rest up with goes on a line of its own, and usage and descriptions are
/// wrapped at 100 columns
local function helpText for Arguments(fields: Array<ArgumentField>, usage: String): String {
  let rows := fields.filter(λ(field) not notAFlag(field)).map(λ(field) {
    let type := field.type.stripSuffix("?") ?? field.type
    let short := shortOf(fields, field)?.let(λ(letter) "-" ++ letter ++ ", ") ?? "    "
    let list := type.startsWith("Array<") or type.startsWith("Set<")
    let shown := list ? "<" ++ Type.named(type).generics()[0]!!.name() ++ ">" ++ field.separator ++ "..." : "<" ++ type ++ ">"
    let named := short ++ "--" ++ flagName(field.name)
    let flag := type == "Boolean" ? named : field.alone != undefined ? named ++ "[=" ++ shown ++ "]" : named ++ " " ++ shown
    let current := field.value
    let fact := field.required ? "required" : current == undefined or current == false or current.toString() == "[]" ? "" : "default " ++ current.toString()
    let note := field.description == "" ? fact : fact == "" ? field.description : field.description ++ " (" ++ fact ++ ")"
    return (flag, note)
  }).toArray()
  let width := rows.map(λ((flag, _)) flag.size()).filter(λ(size) size <= 28).max() ?? 0
  let column := " ".repeat(2 + width + 2)
  let lines := usage == "" ? [] : usage.split("\n").flatMap(λ(line) wrapped(line, "", "")).toArray() ++ [""]
  lines.push("Options:")
  for (flag, note) in rows {
    if note == "" then {
      lines.push("  " ++ flag)
    } else if flag.size() > width then {
      lines.push("  " ++ flag)
      lines.pushAll(wrapped(note, column, column))
    } else {
      lines.pushAll(wrapped(note, "  " ++ flag.padEnd(width) ++ "  ", column))
    }
  }
  return lines.join("\n")
}

/// text as lines no wider than 100 columns - the first starting with `first`, the rest with `next`
local function wrapped for Arguments(text: String, first: String, next: String): Array<String> {
  let lines: Array<String> := []
  let line := first
  for word in text.split(" ") {
    if line != first and line.size() + 1 + word.size() > 100 then {
      lines.push(line)
      set line := next ++ word
    } else {
      set line := line == first ? line ++ word : line ++ " " ++ word
    }
  }
  lines.push(line)
  return lines
}

/// "maxConnections" as "max-connections" - a "-" before each capital that follows a lowercase letter
local function flagName for Arguments(field: String): String {
  return field.replaceAll(#regex"(?<=[a-z0-9])(?=[A-Z])", "-").toLower()
}

local method word for Mask(self: Mask, index: U64): U64 {
  return self.words[index] ?? 0
}

/// clears the bits past width in the last word, after an operation that may have set them
local method trim for Mask(self: Mask): Mask {
  let spare := self.width % 64
  if spare != 0 and not self.words.isEmpty() then { set self.words[self.words.size() - 1] := self.word(self.words.size() - 1) band ((1 as U64).shl(spare) - 1) }
  return self
}

local method check for Mask(self: Mask, index: U64): IndexError ! Undefined {
  if index >= self.width then { error IndexError.new("bit " ++ index.toString() ++ " is past the end of " ++ self.width.toString() ++ " bits") }
}

global function filled for Mask(size: U64, value: Boolean := false): Mask {
  return Mask{words := Array.filled((size + 63) / 64, value ? ~(0 as U64) : 0), width := size}.trim()
}

global function fromInteger for Mask<Source>(value: Source): Mask {
  let mask := Mask.filled(Source.bits() as U64)
  for i in 0..<mask.width if value.bit(i as U8) {
    { mask.set(i) !? undefined }
  }
  return mask
}

global method test for Mask(self: Mask, index: U64): IndexError ! Boolean {
  self.check(index)!!
  return (self.word(index / 64).shr(index % 64) band 1) == 1
}

global method set for Mask(self: Mask, index: U64): IndexError ! Undefined {
  self.check(index)!!
  set self.words[index / 64] := self.word(index / 64) bor (1 as U64).shl(index % 64)
}

global method clear for Mask(self: Mask, index: U64): IndexError ! Undefined {
  self.check(index)!!
  set self.words[index / 64] := self.word(index / 64) band ~(1 as U64).shl(index % 64)
}

global method toggle for Mask(self: Mask, index: U64): IndexError ! Undefined {
  self.check(index)!!
  set self.words[index / 64] := self.word(index / 64) bxor (1 as U64).shl(index % 64)
}

global method setAll for Mask(self: Mask): Undefined {
  self.words.fill(~(0 as U64))
  self.trim()
}

global method clearAll for Mask(self: Mask): Undefined {
  self.words.fill(0)
}

global method count for Mask(self: Mask): U64 {
  return self.words.reduce(0 as U64, λ(total, w) total + (w.countOnes() as U64))
}

global method any for Mask(self: Mask): Boolean {
  return self.words.any(λ(w) w != 0)
}

global method all for Mask(self: Mask): Boolean {
  return self.count() == self.width
}

global method none for Mask(self: Mask): Boolean {
  return not self.any()
}

global method ones for Mask(self: Mask): Iterator<U64> {
  for w, n in self.words {
    let rest := w
    for _ in forever() while rest != 0 {
      yield n * 64 + (rest.trailingZeros() as U64)
      set rest := rest band (rest - 1)
    }
  }
}

global method resize for Mask(self: Mask, size: U64): Mask {
  let result := Mask.filled(size)
  for i in self.ones() while i < size {
    result.set(i) !? undefined
  }
  return result
}

global method toInteger for Mask<Target>(self: Mask): CastError ! Target {
  let bits := Target.bits() as U64
  if self.ones().any(λ(i) i >= bits) then { error CastError.new("a " ++ self.width.toString() ++ "-bit mask with bits set past " ++ bits.toString() ++ " doesn't fit in a " ++ Target.name()) }
  let result: Target := 0
  for i in self.ones() {
    set result := result.withBit(i as U8, true)
  }
  return result
}

method equals(self: Mask, other: Mask): Boolean {
  return self.width == other.width and self.words == other.words
}

method hash(self: Mask): U64 {
  return self.words.reduce(hashCombine(&hashSeed, self.width), λ(hash, w) hashCombine(hash, w))
}

/// highest bit first, like an integer literal - "0b1010"
method toString(self: Mask): String {
  return "0b" ++ String.fromCodepoints(Array.generate(self.width, λ(i) (self.test(self.width - 1 - i) !? false) ? '1' : '0'))
}

/// the last digit is bit 0 - the same order an integer literal is written in
function parse(text: String): ParseError ! Mask {
  let digits := (text.trim().stripPrefix("0b") ?? text.trim()).replaceAll("_", "").codepoints().reverse()
  let mask := Mask.filled(digits.size())
  for digit, i in digits {
    if digit != '0' and digit != '1' then { error ParseError.new("a mask is written in 0s and 1s, got '" ++ digit.toString() ++ "'") }
    if digit == '1' then { mask.set(i) !? undefined }
  }
  return mask
}

/// a shorter mask counts as 0s past its end, and the result is as wide as the wider one
method bor(self: Mask, other: Mask): Mask {
  let n := self.words.size().max(other.words.size())
  return Mask{words := Array.generate(n, λ(i) self.word(i) bor other.word(i)), width := self.width.max(other.width)}
}

method bxor(self: Mask, other: Mask): Mask {
  let n := self.words.size().max(other.words.size())
  return Mask{words := Array.generate(n, λ(i) self.word(i) bxor other.word(i)), width := self.width.max(other.width)}
}

method band(self: Mask, other: Mask): Mask {
  let n := self.words.size().max(other.words.size())
  return Mask{words := Array.generate(n, λ(i) self.word(i) band other.word(i)), width := self.width.max(other.width)}
}

method bnot(self: Mask): Mask {
  return Mask{words := self.words.map(λ(w) ~w), width := self.width}.trim()
}

/// toward higher indices - bits shifted past the end are dropped
method shl(self: Mask, count: U64): Mask {
  let result := Mask.filled(self.width)
  for i in self.ones() if i + count < self.width {
    result.set(i + count) !? undefined
  }
  return result
}

method shr(self: Mask, count: U64): Mask {
  let result := Mask.filled(self.width)
  for i in self.ones() if i >= count {
    result.set(i - count) !? undefined
  }
  return result
}

method iterator(self: Mask): Iterator<Boolean> {
  for i in 0..<self.width {
    yield self.test(i) !? false
  }
}

function fromIterable(items: Iterable<Boolean>): Mask {
  let bits := items.toArray()
  let mask := Mask.filled(bits.size())
  for bit, i in bits if bit {
    mask.set(i) !? undefined
  }
  return mask
}

method size(self: Mask): U64 {
  return self.width
}

method isEmpty(self: Mask): Boolean {
  return self.width == 0
}

method get(self: Mask, key: U64): Boolean? {
  return self.test(key) !? undefined
}

method set(self: Mask, key: U64, value: Boolean): Error ! Undefined {
  return value ? self.set(key) : self.clear(key)
}

function default(): Mask {
  return Mask.filled(0)
}

method clone(self: Mask): Mask {
  return Mask{words := self.words.clone(), width := self.width}
}

/// the pattern (ECMAScript syntax, flags "i", "m", "s", "u", "x") as a backtracking program
local function compile for Regex(pattern: String, flags: String): ParseError ! Bytes {
  return #builtin.regexCompile(pattern, flags)
}

/// runs the program on text from start - anchored tries only start itself, otherwise each position from
/// start on; positions are code point indexes
local method execute for Regex(self: Regex, text: String, start: U64, anchored: Boolean): Match? {
  let spans := #builtin.regexExecute(self.program, text, start, anchored)
  return spans == undefined ? undefined : Match{input := text, spans := spans, names := #builtin.regexGroups(self.program)}
}

/// "$1", "$name" and "$" in a replacement, filled in from one match
local function expand for Regex(template: String, found: Match): String {
  let text := template.codepoints()
  let result: Array<Codepoint> := []
  let i: U64 := 0
  for _ in forever() while i < text.size() {
    let c := text[i] ?? ' '
    let name := c == '#39; ? text.drop(i + 1).takeWhile(λ(n) n.isIdContinue()) : []
    if c == '#39; and text[i + 1] == '#39; then {
      result.push('#39;)
      set i += 2
    } else {
      if name.isEmpty() then {
        result.push(c)
        set i += 1
      } else {
        let key := String.fromCodepoints(name)
        let value := name.all(λ(n) n.isDigit()) ? found.group((key.toInteger() !? 0) as U64) : found.named(key)
        set result ++= (value ?? "").codepoints()
        set i += 1 + name.size()
      }
    }
  }
  return String.fromCodepoints(result)
}

global function new for Regex(pattern: String, flags: String := ""): ParseError ! Regex {
  return Regex{pattern := pattern, options := flags, program := Self.compile(pattern, flags)!!}
}

global function escape for Regex(text: String): String {
  return String.fromCodepoints(text.codepoints().flatMap(λ(c) "\\^$.|?*+()[]{}/-".has(c) ? ['\\', c] : [c]))
}

global method source for Regex(self: Regex): String {
  return self.pattern
}

global method flags for Regex(self: Regex): String {
  return self.options
}

global method test for Regex(self: Regex, text: String): Boolean {
  return self.execute(text, 0, false) != undefined
}

global method matchAt for Regex(self: Regex, text: String, start: U64): U64 {
  return self.execute(text, start, true)?.end() ?? start
}

global method find for Regex(self: Regex, text: String, from: U64 := 0): Match? {
  return self.execute(text, from, false)
}

/// an empty match moves on by one code point, so the search always advances
global method findAll for Regex(self: Regex, text: String): Iterator<Match> {
  let from: U64 := 0
  let length := text.size()
  for _ in forever() while from <= length {
    let found := self.execute(text, from, false)
    if found == undefined then { return }
    yield found
    set from := found.end() == found.start() ? found.end() + 1 : found.end()
  }
}

global method replace for Regex(self: Regex, text: String, with: String | Lambda<Match, String>): String {
  let found := self.find(text)
  if found == undefined then { return text }
  let replacement := with is String ? Self.expand(with as String, found) : (with as Lambda<Match, String>)(found)
  return (text.slice(0..<found.start()) !? "") ++ replacement ++ (text.slice(found.end()..<text.size()) !? "")
}

global method replaceAll for Regex(self: Regex, text: String, with: String | Lambda<Match, String>): String {
  let pieces: Array<String> := []
  let last: U64 := 0
  for found in self.findAll(text) {
    pieces.push(text.slice(last..<found.start()) !? "")
    pieces.push(with is String ? Self.expand(with as String, found) : (with as Lambda<Match, String>)(found))
    set last := found.end()
  }
  pieces.push(text.slice(last..<text.size()) !? "")
  return pieces.join()
}

global method split for Regex(self: Regex, text: String, limit: U64?): Array<String> {
  return text.split(self, limit)
}

/// the named groups, in the order they open
global method groupNames for Regex(self: Regex): Array<String> {
  return #builtin.regexGroups(self.program).entries().collect().sortedBy(λ(entry) entry[1]).map(λ(entry) entry[0])
}

method equals(self: Regex, other: Regex): Boolean {
  return self.pattern == other.pattern and self.options == other.options
}

method hash(self: Regex): U64 {
  return hashCombine(self.pattern.hash(), self.options.hash())
}

method toString(self: Regex): String {
  return self.pattern
}

method clone(self: Regex): Regex {
  return Regex{pattern := self.pattern, options := self.options, program := self.program}
}

/// no database injected is an error like any other the database gives
local function database for Query(): IOError ! Database {
  return &database ?! IOError.new("no database to run the query on - inject one as &database")
}

/// a row, a Map of its columns, as a Row - a struct's fields decoded from them, a Boolean from the 0
/// or 1 SQLite keeps it as; any other Row is the Map itself
local function row for Query<Row>(self: Query<Row>, columns: Map<String, Unknown>, at: U64): IOError ! Row {
  if not Type.of<Row>().isStruct() then {
    return columns as Row
  }
  let values := Type.of<Row>().fields().entries().map(λ((name, type)) {
    let value := columns[name]
    let read := type.name() == "Boolean" and value is S64 ? value != 0 : value
    return (name, decodedAs(read, type.name(), "row " ++ (at + 1).toString() ++ "." ++ name) !? λ(failure) error IOError.new(self.statement.trim() ++ ": " ++ failure.message()))
  })
  return #runtime.construct(Type.of<Row>(), Map.fromIterable(values))!! as Row
}

global method run for Query<Row>(self: Query<Row>): IOError ! Table<Row> {
  let rows := Query.database()!!.query(self.statement, self.values)!!
  return Table.fromRows(rows.enumerate().map(λ((i, columns)) self.row(columns, i)!!))
}

global method first for Query<Row>(self: Query<Row>): IOError ! Row? {
  let columns := Query.database()!!.query(self.statement, self.values)!!.first()
  return columns == undefined ? undefined : self.row(columns, 0)!!
}

global method execute for Query<Row>(self: Query<Row>): IOError ! U64 {
  return Query.database()!!.execute(self.statement, self.values)!!
}

global method sql for Query<Row>(self: Query<Row>): String {
  return self.statement
}

global method parameters for Query<Row>(self: Query<Row>): Array<Unknown> {
  return self.values.clone()
}

method toString(self: Query<Row>): String {
  return self.statement
}

global method source for Wgsl(self: Wgsl): String {
  return self.code
}

method equals(self: Wgsl, other: Wgsl): Boolean {
  return self.code == other.code
}

method toString(self: Wgsl): String {
  return self.code
}

global method source for Glsl(self: Glsl): String {
  return self.code
}

method equals(self: Glsl, other: Glsl): Boolean {
  return self.code == other.code
}

method toString(self: Glsl): String {
  return self.code
}

global method source for Hlsl(self: Hlsl): String {
  return self.code
}

method equals(self: Hlsl, other: Hlsl): Boolean {
  return self.code == other.code
}

method toString(self: Hlsl): String {
  return self.code
}

global method source for Msl(self: Msl): String {
  return self.code
}

method equals(self: Msl, other: Msl): Boolean {
  return self.code == other.code
}

method toString(self: Msl): String {
  return self.code
}

global method source for Spirv(self: Spirv): String {
  return self.code
}

method equals(self: Spirv, other: Spirv): Boolean {
  return self.code == other.code
}

method toString(self: Spirv): String {
  return self.code
}

/// another process - the JavaScript host's (see JavaScript and TypeScript)
@js("host:process", "run")
local function start for Command(words: Array<String>): CommandResult

@js("host:process", "attach")
local function share for Command(words: Array<String>): S64

global function of for Command(words: Array<String>): Command {
  return Command{words := words.clone(), environment := [], piped := []}
}

/// a program that can't start comes back from the host as an Error - as an IOError
global method run for Command(self: Command): IOError ! CommandResult {
  if self.words.size() == 0 then {
    error IOError.new("a command needs a program to run")
  }
  match Command.start(self.words) {
    case Error(e) then {
      error IOError.new(e.message())
    }
    case result then {
      return result
    }
  }
}

global method attach for Command(self: Command): IOError ! S64 {
  if self.words.size() == 0 then {
    error IOError.new("a command needs a program to run")
  }
  match Command.share(self.words) {
    case Error(e) then {
      error IOError.new(e.message())
    }
    case code then {
      return code
    }
  }
}

global method words for Command(self: Command): Array<String> {
  return self.words.clone()
}

/// kept beside the words, and handed to the host with them - "NAME=value" on top of this program's own
global method withEnvironment for Command(self: Command, name: String, value: String): Command {
  return Command{words := self.words.clone(), environment := self.environment.filter(λ(pair) not pair.startsWith(name ++ "=")) ++ [name ++ "=" ++ value]}
}

global method pipe for Command(self: Command, next: Command): Command {
  return Command{words := self.words, environment := self.environment, piped := self.piped ++ [next.words] ++ next.piped}
}

global method start for Command(self: Command): IOError ! Process {
  if self.words.size() == 0 then {
    error IOError.new("a command needs a program to run")
  }
  let id := Process.spawn([self.words] ++ self.piped, self.environment) !? (error e) IOError.new(e.message())
  return Process{id, command := self.toString(), out := [], err := [], exitCode := undefined}
}

method toString(self: Command): String {
  return self.words.map(λ(word) word.contains(" ") or word.contains("'") or word == "" ? "'" ++ word.replaceAll("'", "'\\''") ++ "'" : word).join(" ")
}

global method name for Definition(self: Definition): String {
  return self.definitionName
}

global method kind for Definition(self: Definition): DefinitionKind {
  return self.definitionKind
}

global method file for Definition(self: Definition): String {
  return self.definitionFile
}

global method arguments for Definition(self: Definition): Array<Unknown> {
  return self.attributeArguments.clone()
}

/// the syntax tree is the compiler's - while compiling, the comptime engine gives it
global method ast for Definition(self: Definition): Error ! Ast.Definition {
  error "A definition's syntax tree is only there while compiling - '" ++ self.definitionName ++ "' has none now"
}

global method value for Definition(self: Definition): Unknown {
  return self.definitionValue
}

method toString(self: Definition): String {
  return self.definitionKind.toString() ++ " " ++ self.definitionName
}

/// the host's streams - processes, sockets and watchers, each a stream of events (see Process.Event):
/// started, told things, and waited on a little at a time
@js("host:streams", "spawn")
local function spawn for Process(pipeline: Array<Array<String>>, environment: Array<String>): Error ! F64

@js("host:streams", "write")
local function writeTo for Process(id: F64, data: String | Bytes): Error ! Undefined

@js("host:streams", "closeInput")
local function closeInputOf for Process(id: F64): Error ! Undefined

@js("host:streams", "kill")
local function killStream for Process(id: F64): Error ! Undefined

@js("host:streams", "next")
local function nextOf for Process(id: F64, ms: F64): Error ! Event?

/// stream id's next event, waiting a little at a time - undefined once &cancellation is cancelled
@require(&cancellation)
local function nextEvent for Process(id: F64): IOError ! Event? {
  for _ in forever() until &cancellation.isCancelled() {
    match Process.nextOf(id, 50.0) {
      case Error(e) then {
        error IOError.new(e.message())
      }
      case undefined then {}
      case event then {
        return event
      }
    }
  }
  return undefined
}

/// one more event taken in - false once it's exited, or waiting was stopped
@require(&cancellation)
local method pump for Process(self: Process): IOError ! Boolean {
  if self.exitCode != undefined then {
    return false
  }
  let event := Process.nextEvent(self.id)!! ?? (return false)
  match event.kind {
    case "out" then { self.out.pushAll(event.bytes) }
    case "err" then { self.err.pushAll(event.bytes) }
    case "exit" then {
      set self.exitCode := event.code
      return false
    }
    case "error" then {
      set self.exitCode := -1
      error IOError.new(self.command ++ ": " ++ event.text)
    }
    case _ then {}
  }
  return true
}

/// buffer's first line, taken out of it, waiting for the process to write one - what's left once it's exited
@require(&cancellation)
local method lineFrom for Process(self: Process, buffer: Array<U8>): IOError ! String? {
  for _ in forever() {
    let at := buffer.indexOf(10)
    if at != undefined then {
      let line := Bytes.fromArray(buffer.take(at)).decode<String>() !? ""
      buffer.removeWhere(λ(_, i) i <= at)
      return line.stripSuffix("\r") ?? line
    }
    if not self.pump()!! then {
      if buffer.isEmpty() then {
        return undefined
      }
      let rest := Bytes.fromArray(buffer.clone()).decode<String>() !? ""
      buffer.clear()
      return rest
    }
  }
}

global method write for Process(self: Process, data: String | Bytes): IOError ! Undefined {
  if self.exitCode != undefined then {
    error IOError.new(self.command ++ " has exited - nothing reads what's written to it")
  }
  Process.writeTo(self.id, data) !? (error e) IOError.new(e.message())
}

global method closeInput for Process(self: Process): Undefined {
  Process.closeInputOf(self.id)
}

global method readLine for Process(self: Process): IOError ! String? {
  return self.lineFrom(self.out)!!
}

global method readErrorLine for Process(self: Process): IOError ! String? {
  return self.lineFrom(self.err)!!
}

global method read for Process(self: Process): IOError ! Bytes? {
  for _ in forever() while self.out.isEmpty() and self.pump()!! {}
  if self.out.isEmpty() then {
    return undefined
  }
  let taken := Bytes.fromArray(self.out.clone())
  self.out.clear()
  return taken
}

global method wait for Process(self: Process): IOError ! S64 {
  for _ in forever() while self.pump()!! {}
  return self.exitCode ?? -1
}

global method kill for Process(self: Process): Undefined {
  if self.exitCode == undefined then {
    Process.killStream(self.id)
  }
}

/// what's arrived taken in, without waiting
global method isRunning for Process(self: Process): Boolean {
  inject cancellation := Cancellation.new()
  for _ in forever() while self.exitCode == undefined {
    match Process.nextOf(self.id, 0.0) {
      case Error(_) then { return false }
      case undefined then { return true }
      case event then {
        if event.kind == "out" then { self.out.pushAll(event.bytes) }
        if event.kind == "err" then { self.err.pushAll(event.bytes) }
        if event.kind == "exit" or event.kind == "error" then { set self.exitCode := event.kind == "exit" ? event.code : -1 }
      }
    }
  }
  return false
}

method toString(self: Process): String {
  return "Process " ++ self.command ++ (self.exitCode == undefined ? " running" : " exited with " ++ self.exitCode.toString())
}

@js("host:streams", "connect")
local function open for WebSocket(url: String): Error ! F64

@js("host:streams", "send")
local function sendTo for WebSocket(id: F64, data: String | Bytes): Error ! Undefined

@js("host:streams", "disconnect")
local function closeStream for WebSocket(id: F64, code: S64, reason: String): Error ! Undefined

global function connect for WebSocket(url: String | Url): IOError ! WebSocket {
  let address := url.toString()
  let id := WebSocket.open(address) !? (error e) IOError.new(e.message())
  let first := Process.nextEvent(id)!! ?! IOError.new("stopped waiting for " ++ address ++ " to open")
  if first.kind != "open" then {
    error IOError.new("couldn't connect to " ++ address ++ ": " ++ (first.text == "" ? first.kind : first.text))
  }
  return WebSocket{id, url := address, open := true}
}

global method send for WebSocket(self: WebSocket, message: String | Bytes): IOError ! Undefined {
  if not self.open then {
    error IOError.new("the socket to " ++ self.url ++ " is closed")
  }
  WebSocket.sendTo(self.id, message) !? (error e) IOError.new(e.message())
}

global method receive for WebSocket(self: WebSocket): IOError ! (String | Bytes)? {
  for _ in forever() while self.open {
    let event := Process.nextEvent(self.id)!! ?? (return undefined)
    match event.kind {
      case "message" then {
        return event.binary ? event.bytes : event.text
      }
      case "close" then {
        set self.open := false
      }
      case "error" then {
        set self.open := false
        error IOError.new("the socket to " ++ self.url ++ " failed: " ++ event.text)
      }
      case _ then {}
    }
  }
  return undefined
}

global method close for WebSocket(self: WebSocket, code: U16 := 1000, reason: String := ""): Undefined {
  if self.open then {
    WebSocket.closeStream(self.id, code as S64, reason)
    set self.open := false
  }
}

global method isOpen for WebSocket(self: WebSocket): Boolean {
  return self.open
}

method toString(self: WebSocket): String {
  return "WebSocket " ++ self.url ++ (self.open ? "" : " (closed)")
}

@js("host:streams", "watch")
local function watchStream for FileWatcher(path: String, recursive: Boolean): Error ! F64

@js("host:streams", "unwatch")
local function unwatchStream for FileWatcher(id: F64): Error ! Undefined

/// the host says when it's watching - a change made once new returns is seen
global function new for FileWatcher(path: String | Path, recursive: Boolean := true): IOError ! FileWatcher {
  let root := path.toString()
  let id := FileWatcher.watchStream(root, recursive) !? (error e) IOError.new(e.message())
  inject cancellation := Cancellation.new()
  let ready := Process.nextEvent(id)!!
  if ready?.kind == "error" then {
    error IOError.new("can't watch " ++ root ++ ": " ++ ready!!.text)
  }
  return FileWatcher{id, root, open := true}
}

/// a "change" event as a FileChange
local method changeOf for FileWatcher(self: FileWatcher, event: Process.Event): IOError ! FileChange? {
  if event.kind == "error" then {
    error IOError.new("watching " ++ self.root ++ " failed: " ++ event.text)
  }
  if event.kind != "change" then {
    return undefined
  }
  return FileChange{path := event.text, kind := [FileChangeKind.Created, FileChangeKind.Changed, FileChangeKind.Removed][event.code as U64]!!}
}

global method next for FileWatcher(self: FileWatcher): IOError ! FileChange? {
  for _ in forever() while self.open {
    let event := Process.nextEvent(self.id)!! ?? (return undefined)
    let change := self.changeOf(event)!!
    if change != undefined then {
      return change
    }
  }
  return undefined
}

/// every distinct change until within has passed
global method changes for FileWatcher(self: FileWatcher, within: Duration): IOError ! Array<FileChange> {
  let found: Set<FileChange> := Set.of()
  let until := Instant.now() + within
  for _ in forever() while self.open and Instant.now() < until {
    match Process.nextOf(self.id, (until - Instant.now()).toMilliseconds().min(50.0)) {
      case Error(e) then {
        error IOError.new(e.message())
      }
      case undefined then {}
      case event then {
        self.changeOf(event)!!?.let(λ(change) found.add(change))
      }
    }
  }
  return found.toArray()
}

global method close for FileWatcher(self: FileWatcher): Undefined {
  if self.open then {
    FileWatcher.unwatchStream(self.id)
    set self.open := false
  }
}

method toString(self: FileWatcher): String {
  return "FileWatcher " ++ self.root ++ (self.open ? "" : " (closed)")
}

method toString(self: FileChange): String {
  return self.kind.toString() ++ " " ++ self.path
}

method equals(self: FileChangeKind, other: FileChangeKind): Boolean {
  return self.index() == other.index()
}

method hash(self: FileChangeKind): U64 {
  return self.index().hash()
}

method toString(self: FileChangeKind): String {
  return self.variantName()
}

global method text for Match(self: Match): String {
  return self.group(0) ?? ""
}

global method range for Match(self: Match): Range<U64> {
  return self.spans[0] ?? 0..<0
}

global method start for Match(self: Match): U64 {
  return self.range().start()
}

global method end for Match(self: Match): U64 {
  return self.range().end()
}

global method group for Match(self: Match, index: U64): String? {
  let span := self.spans[index]
  return span == undefined ? undefined : self.input.slice(span) !? undefined
}

global method named for Match(self: Match, name: String): String? {
  let index := self.names.get(name)
  return index == undefined ? undefined : self.group(index)
}

global method groups for Match(self: Match): Array<String?> {
  return (1..<self.spans.size()).toArray().map(λ(i) self.group(i))
}

global method namedGroups for Match(self: Match): Map<String, String> {
  let result: Map<String, String> := Map.of()
  for entry in self.names {
    let (name, index) := entry
    let value := self.group(index)
    if value != undefined then { result.set(name, value) }
  }
  return result
}

method equals(self: Match, other: Match): Boolean {
  return self.input == other.input and self.spans == other.spans
}

method toString(self: Match): String {
  return self.text()
}

method clone(self: Match): Match {
  return Match{input := self.input, spans := self.spans.clone(), names := self.names.clone()}
}

method equals(self: Request, other: Request): Boolean {
  return self.method == other.method and self.path == other.path and self.params == other.params
    and self.query == other.query and self.form == other.form and self.headers == other.headers and self.body == other.body
}

/// "POST /api/todos"
method toString(self: Request): String {
  return self.method ++ " " ++ self.path
}

method clone(self: Request): Request {
  return Request{self.method, self.path, self.params.clone(), self.query.clone(), self.form.clone(), self.headers.clone(), self.body}
}

local function typed for Response(body: String | Bytes, contentType: String, status: U16): Response {
  return Response{status, headers := Map.of(("Content-Type", contentType)), body}
}

global function text for Response(body: String, status: U16 := 200): Response {
  return Response.typed(body, "text/plain; charset=utf-8", status)
}

global function html for Response(page: Html, status: U16 := 200): Response {
  return Response.typed(page.toString(), "text/html; charset=utf-8", status)
}

global function json for Response(value: Json, status: U16 := 200): Response {
  return Response.typed(value.toString(), "application/json", status)
}

global function css for Response(sheet: Stylesheet, status: U16 := 200): Response {
  return Response.typed(sheet.toString(), "text/css; charset=utf-8", status)
}

global function bytes for Response(body: Bytes, status: U16 := 200): Response {
  return Response.typed(body, "application/octet-stream", status)
}

global function redirect for Response(to: String, status: U16 := 303): Response {
  return Response{status, headers := Map.of(("Location", to))}
}

global function empty for Response(status: U16 := 204): Response {
  return Response{status}
}

global method ok for Response(self: Response): Boolean {
  return self.status >= 200 and self.status <= 299
}

global method bodyText for Response(self: Response): ParseError ! String {
  match self.body {
    case String as text then { return text }
    case Bytes as bytes then { return String.fromUtf8(bytes)!! }
  }
}

global method bodyJson for Response(self: Response): ParseError ! Unknown {
  let reader := JsonReader{text := self.bodyText()!!.codepoints(), at := 0}
  let value := reader.value()!!
  reader.space()
  if reader.at < reader.text.size() then {
    error ParseError.new("not JSON - something after the document")
  }
  return value
}

local method peek for JsonReader(self: JsonReader): Codepoint? {
  return self.text[self.at]
}

local method space for JsonReader(self: JsonReader): Undefined {
  for _ in forever() while self.peek() == ' ' | '\n' | '\r' | '\t' {
    set self.at += 1
  }
}

local method value for JsonReader(self: JsonReader): ParseError ! Unknown {
  self.space()
  match self.peek() {
    case '{' then {
      set self.at += 1
      let members: Map<String, Unknown> := Map.of()
      self.space()
      if self.peek() == '}' then { set self.at += 1; return members }
      for _ in forever() {
        self.space()
        let name := self.string()!!
        self.space()
        self.expect(':')!!
        members.set(name, self.value()!!)
        self.space()
        if self.peek() == '}' then { set self.at += 1; return members }
        self.expect(',')!!
      }
    }
    case '[' then {
      set self.at += 1
      let items: Array<Unknown> := []
      self.space()
      if self.peek() == ']' then { set self.at += 1; return items }
      for _ in forever() {
        items.push(self.value()!!)
        self.space()
        if self.peek() == ']' then { set self.at += 1; return items }
        self.expect(',')!!
      }
    }
    case '"' then { return self.string()!! }
    case 't' then { self.word("true")!!; return true }
    case 'f' then { self.word("false")!!; return false }
    case 'n' then { self.word("null")!!; return undefined }
    case _ then {
      let start := self.at
      for _ in forever() while self.peek() in "-+.eE0123456789".codepoints() {
        set self.at += 1
      }
      return String.fromCodepoints(self.text[start..<self.at]).parse<F64>() !? error ParseError.new("not JSON - no value here")
    }
  }
}

local method expect for JsonReader(self: JsonReader, char: Codepoint): ParseError ! Undefined {
  if self.peek() != char then {
    error ParseError.new("not JSON - expected '" ++ char.toString() ++ "'")
  }
  set self.at += 1
}

local method word for JsonReader(self: JsonReader, word: String): ParseError ! Undefined {
  for char in word.codepoints() {
    self.expect(char)!!
  }
}

/// a string - its escapes read, \uXXXX (a surrogate pair one code point) among them
local method string for JsonReader(self: JsonReader): ParseError ! String {
  self.expect('"')!!
  let out: Array<Codepoint> := []
  for _ in forever() {
    let char := self.peek() ?? error ParseError.new("not JSON - a string that never ends")
    set self.at += 1
    if char == '"' then { return String.fromCodepoints(out) }
    if char != '\\' then { out.push(char); continue _ }
    let escaped := self.peek() ?? ' '
    set self.at += 1
    match escaped {
      case 'u' then {
        let code := self.hex()!!
        if code >= 0xD800 and code <= 0xDBFF and self.peek() == '\\' then {
          set self.at += 2
          set code := 0x10000 + (code - 0xD800) * 0x400 + (self.hex()!! - 0xDC00)
        }
        out.push(Codepoint.of(code)!!)
      }
      case 'b' then { out.push('\u{8}') }
      case 'f' then { out.push('\u{C}') }
      case 'n' then { out.push('\n') }
      case 'r' then { out.push('\r') }
      case 't' then { out.push('\t') }
      case '"' | '\\' | '/' then { out.push(escaped) }
      case _ then { error ParseError.new("not JSON - '\\" ++ escaped.toString() ++ "' isn't an escape") }
    }
  }
}

local method hex for JsonReader(self: JsonReader): ParseError ! U32 {
  let digits := String.fromCodepoints(self.text[self.at..<self.at + 4])
  set self.at += 4
  return digits.toInteger(16) !? error ParseError.new("not JSON - a \\u escape is four hex digits")
}

method equals(self: Response, other: Response): Boolean {
  return self.status == other.status and self.headers == other.headers and self.body == other.body
}

/// "404 no todo 7" - its status, and a String body
method toString(self: Response): String {
  match self.body {
    case String as text then {
      return self.status.toString() ++ " " ++ text
    }
    case _ then {
      return self.status.toString()
    }
  }
}

method clone(self: Response): Response {
  return Response{self.status, self.headers.clone(), self.body}
}

@require(&http)
global method send for HttpRequest(self: HttpRequest): Promise<IOError ! Response> {
  return &http.send(self)
}

method equals(self: HttpRequest, other: HttpRequest): Boolean {
  return self.method == other.method and self.url == other.url and self.headers == other.headers and self.body == other.body
    and self.followRedirects == other.followRedirects and self.timeout == other.timeout
}

/// "POST https://api.example.com/todos"
method toString(self: HttpRequest): String {
  return self.method ++ " " ++ self.url
}

method clone(self: HttpRequest): HttpRequest {
  return HttpRequest{self.method, self.url, self.headers.clone(), self.body, self.followRedirects, self.timeout}
}

/// where Error.new was called from, when the program was built with locations kept
local function callSite for Error(): String? {
  return #comptime.callSite()
}

global function new for Error(message: String, cause: Error? := undefined): Error {
  return Self{text := message, wrapped := cause, createdAt := Self.callSite(), frames := []}
}

global method message for Error(self: Error): String {
  return self.text
}

global method cause for Error(self: Error): Error? {
  return self.wrapped
}

global method chain for Error(self: Error): Array<Error> {
  let result: Array<Error> := [self]
  for _ in forever() while result.last()?.cause() != undefined {
    result.push(result.last()?.cause() ?? self)
  }
  return result
}

global method root for Error(self: Error): Error {
  return self.chain().last() ?? self
}

global method typeOf for Error(self: Error): Type {
  return Type.of(self)
}

global method is for Error<Target: Error>(self: Error): Boolean {
  return self.chain().any(λ(e) Target.isAssignableFrom(e.typeOf()))
}

global method find for Error<Target: Error>(self: Error): Target? {
  return self.chain().find(λ(e) Target.isAssignableFrom(e.typeOf())) as Target?
}

global method wrap for Error(self: Error, message: String): Error {
  return Error.new(message, self)
}

global method location for Error(self: Error): String? {
  return self.createdAt
}

global method trace for Error(self: Error): Array<String> {
  return self.frames.clone()
}

/// the same kind of error, saying the same thing, for the same reason
method equals(self: Error, other: Error): Boolean {
  return self.typeOf() == other.typeOf() and self.text == other.text and self.wrapped == other.wrapped
}

/// "IndexError: index 5 is past the end - caused by ..."
method toString(self: Error): String {
  return self.chain().map(λ(e) e.typeOf().name() ++ ": " ++ e.message()).join(" - caused by ")
}

method clone(self: Error): Error {
  return Self{text := self.text, wrapped := self.wrapped?.clone(), createdAt := self.createdAt, frames := self.frames.clone()}
}

global method isDefined for Optional<Type>(self: Type?): Boolean {
  return self != undefined
}

global method isUndefined for Optional<Type>(self: Type?): Boolean {
  return self == undefined
}

global method orElse for Optional<Type>(self: Type?, fallback: Type): Type {
  return self == undefined ? fallback : self
}

global method orElseGet for Optional<Type>(self: Type?, fallback: Lambda<(), Type>): Type {
  return self == undefined ? fallback() : self
}

global method orError for Optional<Type, E: Error>(self: Type?, error: E): E ! Type {
  if self == undefined then { error error }
  return self
}

global method map for Optional<Type, Result>(self: Type?, f: Lambda<Type, Result>): Result? {
  return self == undefined ? undefined : f(self)
}

global method flatMap for Optional<Type, Result>(self: Type?, f: Lambda<Type, Result?>): Result? {
  return self == undefined ? undefined : f(self)
}

global method filter for Optional<Type>(self: Type?, keep: Lambda<Type, Boolean>): Type? {
  return self != undefined and keep(self) ? self : undefined
}

global method ifDefined for Optional<Type>(self: Type?, f: Lambda<Type, Undefined>): Undefined {
  if self != undefined then { f(self) }
}

global method expect for Optional<Type>(self: Type?, message: String): Type {
  return self == undefined ? abort(Error.new(message)) : self
}

global method toArray for Optional<Type>(self: Type?): Array<Type> {
  return self == undefined ? [] : [self]
}

method equals(self: Type?, other: Type?): Boolean {
  if self == undefined or other == undefined then { return self == undefined and other == undefined }
  return (self as Type).equals(other as Type)
}

method hash(self: Type?): U64 {
  return self == undefined ? &hashSeed : hashCombine(&hashSeed + 1, (self as Type).hash())
}

method compare(self: Type?, other: Type?): Ordering {
  if self == undefined then { return other == undefined ? Ordering.Equal : Ordering.Less }
  if other == undefined then { return Ordering.Greater }
  return (self as Type).compare(other as Type)
}

method toString(self: Type?): String {
  return self == undefined ? "undefined" : (self as Type).toString()
}

method clone(self: Type?): Type? {
  return self == undefined ? undefined : (self as Type).clone()
}

function default(): Type? {
  return undefined
}

global method isEmpty for Iterable<Type>(self: Iterable<Type>): Boolean {
  return self.iterator().peek() == undefined
}

global method count for Iterable<Type>(self: Iterable<Type>, where: Lambda<Type, Boolean>): U64 {
  let total: U64 := 0
  for item in self if where(item) {
    set total += 1
  }
  return total
}

global method contains for Iterable<Type>(self: Iterable<Type>, item: Type): Boolean {
  return self.any(λ(x) x == item)
}

global method any for Iterable<Type>(self: Iterable<Type>, where: Lambda<Type, Boolean>): Boolean {
  for item in self if where(item) {
    return true
  }
  return false
}

global method all for Iterable<Type>(self: Iterable<Type>, where: Lambda<Type, Boolean>): Boolean {
  return not self.any(λ(x) not where(x))
}

global method none for Iterable<Type>(self: Iterable<Type>, where: Lambda<Type, Boolean>): Boolean {
  return not self.any(where)
}

global method find for Iterable<Type>(self: Iterable<Type>, where: Lambda<Type, Boolean>): Type? {
  for item in self if where(item) {
    return item
  }
  return undefined
}

global method forEach for Iterable<Type>(self: Iterable<Type>, f: Lambda<Type, Undefined>): Undefined {
  for item in self {
    f(item)
  }
}

global method reduce for Iterable<Type, Result>(self: Iterable<Type>, initial: Result, f: Lambda<(Result, Type), Result>): Result {
  let result := initial
  for item in self {
    set result := f(result, item)
  }
  return result
}

/// reduce, starting from the first item instead of a given value
global method fold for Iterable<Type>(self: Iterable<Type>, f: Lambda<(Type, Type), Type>): EmptyError ! Type {
  let items := self.iterator()
  let first := items.next()
  if first == undefined then { error EmptyError.new("fold needs at least one item") }
  return items.reduce(first, f)
}

/// Type: Comparable - the first of several equal ones
global method min for Iterable<Type>(self: Iterable<Type>): EmptyError ! Type {
  return self.fold(λ(a, b) b < a ? b : a)
}

global method max for Iterable<Type>(self: Iterable<Type>): EmptyError ! Type {
  return self.fold(λ(a, b) b > a ? b : a)
}

global method minBy for Iterable<Type, Key: Comparable>(self: Iterable<Type>, key: Lambda<Type, Key>): EmptyError ! Type {
  return self.fold(λ(a, b) key(b) < key(a) ? b : a)
}

global method maxBy for Iterable<Type, Key: Comparable>(self: Iterable<Type>, key: Lambda<Type, Key>): EmptyError ! Type {
  return self.fold(λ(a, b) key(b) > key(a) ? b : a)
}

/// Type: Numeric
global method sum for Iterable<Type>(self: Iterable<Type>): Type {
  return self.reduce(Type.zero(), λ(total, item) total + item)
}

global method product for Iterable<Type>(self: Iterable<Type>): Type {
  return self.reduce(Type.one(), λ(total, item) total * item)
}

global method average for Iterable<Type>(self: Iterable<Type>): EmptyError ! Float {
  let (total, n) := self.reduce((0.0, 0 as U64), λ(acc, item) (acc[0] + (item as Float), acc[1] + 1))
  if n == 0 then { error EmptyError.new("average needs at least one item") }
  return total / (n as Float)
}

global method groupBy for Iterable<Type, Key: Hashable>(self: Iterable<Type>, key: Lambda<Type, Key>): Map<Key, Array<Type>> {
  let groups: Map<Key, Array<Type>> := Map.of()
  for item in self {
    groups.getOrInsert(key(item), λ []).push(item)
  }
  return groups
}

global method partition for Iterable<Type>(self: Iterable<Type>, where: Lambda<Type, Boolean>): (Array<Type>, Array<Type>) {
  let (kept, rest): (Array<Type>, Array<Type>) := ([], [])
  for item in self {
    (where(item) ? kept : rest).push(item)
  }
  return (kept, rest)
}

/// Type: ToString
global method join for Iterable<Type>(self: Iterable<Type>, separator: String := ""): String {
  return separator.join(self.iterator().map(λ(item) item.toString()))
}

global method toArray for Iterable<Type>(self: Iterable<Type>): Array<Type> {
  let result: Array<Type> := []
  for item in self {
    result.push(item)
  }
  return result
}

/// Type: Hashable
global method toSet for Iterable<Type>(self: Iterable<Type>): Set<Type> {
  return Set.fromIterable(self)
}

global method toMap for Iterable<Type, Key, Value>(self: Iterable<Type>, entry: Lambda<Type, (Key, Value)>): Map<Key, Value> {
  return Map.fromIterable(self.iterator().map(entry))
}

/// each collection empties itself its own way
global method clear for Iterable<Type>(self: Iterable<Type>): Undefined

/// how many times each element occurs, in the order each first did
global method frequencies for Iterable<Type: Hashable>(self: Iterable<Type>): Map<Type, U64> {
  let counts: Map<Type, U64> := Map.of()
  for x in self {
    counts.set(x, counts.getOr(x, 0) + 1)
  }
  return counts
}

/// every element as an F64, sorted - an EmptyError for none
local function sortedFloats for Iterable<Type: Numeric>(items: Iterable<Type>, what: String): EmptyError ! Array<F64> {
  let values := items.map(λ(x) x as F64).sorted()
  if values.isEmpty() then {
    error EmptyError.new(what ++ " of an empty sequence")
  }
  return values
}

/// p percent of the way through the sorted values - between two of them when it falls between
local function percentileOf for Iterable(values: Array<F64>, p: F64): F64 {
  let position := p.clamp(0.0..=100.0) / 100.0 * (values.size() - 1) as F64
  let below := position.floor()
  let low := values[below as U64]!!
  let high := values[below as U64 + 1] ?? low
  return low + (high - low) * (position - below)
}

global method median for Iterable<Type: Numeric>(self: Iterable<Type>): EmptyError ! F64 {
  return percentileOf(sortedFloats(self, "median")!!, 50.0)
}

global method percentile for Iterable<Type: Numeric>(self: Iterable<Type>, p: F64): EmptyError ! F64 {
  return percentileOf(sortedFloats(self, "percentile")!!, p)
}

/// of the whole population - divided by the count, not the count less one
global method variance for Iterable<Type: Numeric>(self: Iterable<Type>): EmptyError ! F64 {
  let values := self.map(λ(x) x as F64).toArray()
  let mean := values.average() !? (error EmptyError.new("variance of an empty sequence"))
  return values.map(λ(x) (x - mean) * (x - mean)).sum() / values.size() as F64
}

global method standardDeviation for Iterable<Type: Numeric>(self: Iterable<Type>): EmptyError ! F64 {
  return self.variance()!!.sqrt()
}

local method load for Array<Type>(self: Array<Type>, index: U64): Type {
  return self.memory.offset(index as S64).read()
}

local method store for Array<Type>(self: Array<Type>, index: U64, value: Type): Undefined {
  self.memory.offset(index as S64).write(value)
}

local method outOfRange for Array<Type>(self: Array<Type>, index: U64): IndexError {
  return IndexError.new("index " ++ index.toString() ++ " is past the end of " ++ self.used.toString() ++ " items")
}

/// makes room for at least needed items, moving them to a bigger allocation when there isn't
local method reserve for Array<Type>(self: Array<Type>, needed: U64): Undefined {
  if needed <= self.capacity then { return }
  let bigger := self.capacity.max(4)
  for _ in forever() while bigger < needed {
    set bigger *= 2
  }
  let moved := allocate<Type>(bigger)
  for i in 0..<self.used {
    moved.offset(i as S64).write(self.load(i))
  }
  if self.capacity > 0 then { self.memory.free() }
  set self.memory := moved
  set self.capacity := bigger
}

local function empty for Array<Type>(capacity: U64 := 0): Array<Type> {
  return Array<Type>{memory := allocate<Type>(capacity), used := 0, capacity := capacity}
}

global function filled for Array<Type>(size: U64, fill: Type): Array<Type> {
  return Array.generate(size, λ(_) fill)
}

global function generate for Array<Type>(size: U64, f: Lambda<U64, Type>): Array<Type> {
  let result := Self.empty(size)
  for i in 0..<size {
    result.push(f(i))
  }
  return result
}

global function of for Array<Type>(items: ..Type): Array<Type> {
  return items.toArray()
}

global method first for Array<Type>(self: Array<Type>): Type? {
  return self.used > 0 ? self.load(0) : undefined
}

global method last for Array<Type>(self: Array<Type>): Type? {
  return self.used > 0 ? self.load(self.used - 1) : undefined
}

global method at for Array<Type>(self: Array<Type>, index: S64): Type? {
  let resolved := index < 0 ? (self.used as S64) + index : index
  return resolved >= 0 and resolved < self.used as S64 ? self.load(resolved as U64) : undefined
}

global method indexOf for Array<Type>(self: Array<Type>, item: Type): U64? {
  return self.findIndex(λ(x) x == item)
}

global method lastIndexOf for Array<Type>(self: Array<Type>, item: Type): U64? {
  for i in (0..<self.used).reverse() if self.load(i) == item {
    return i
  }
  return undefined
}

global method findIndex for Array<Type>(self: Array<Type>, where: Lambda<Type, Boolean>): U64? {
  for i in 0..<self.used if where(self.load(i)) {
    return i
  }
  return undefined
}

global method slice for Array<Type>(self: Array<Type>, range: Range<U64>): IndexError ! Array<Type> {
  let (start, end) := bounds(range)
  if end > self.used or start > end then { error self.outOfRange(end) }
  return Array.generate(end - start, λ(i) self.load(start + i))
}

global method push for Array<Type>(self: Array<Type>, item: Type): Undefined {
  self.reserve(self.used + 1)
  self.store(self.used, item)
  set self.used += 1
}

global method pop for Array<Type>(self: Array<Type>): Type? {
  if self.used == 0 then { return undefined }
  set self.used -= 1
  return self.load(self.used)
}

global method pushFront for Array<Type>(self: Array<Type>, item: Type): Undefined {
  self.insert(0, item) !? undefined
}

global method popFront for Array<Type>(self: Array<Type>): Type? {
  return self.used == 0 ? undefined : self.removeAt(0) !? undefined
}

/// shifts everything from index on one place toward the end
global method insert for Array<Type>(self: Array<Type>, index: U64, item: Type): IndexError ! Undefined {
  if index > self.used then { error self.outOfRange(index) }
  self.reserve(self.used + 1)
  for i in (index..<self.used).reverse() {
    self.store(i + 1, self.load(i))
  }
  self.store(index, item)
  set self.used += 1
}

global method removeAt for Array<Type>(self: Array<Type>, index: U64): IndexError ! Type {
  if index >= self.used then { error self.outOfRange(index) }
  let removed := self.load(index)
  for i in (index + 1)..<self.used {
    self.store(i - 1, self.load(i))
  }
  set self.used -= 1
  return removed
}

global method remove for Array<Type>(self: Array<Type>, item: Type): Boolean {
  let index := self.indexOf(item)
  if index == undefined then { return false }
  self.removeAt(index) !? undefined
  return true
}

/// one pass - the kept items slide down over the removed ones
global method removeWhere for Array<Type>(self: Array<Type>, where: Lambda<Type, Boolean>): U64 {
  let kept: U64 := 0
  for i in 0..<self.used {
    let item := self.load(i)
    if not where(item) then {
      self.store(kept, item)
      set kept += 1
    }
  }
  let removed := self.used - kept
  set self.used := kept
  return removed
}

global method pushAll for Array<Type>(self: Array<Type>, items: Iterable<Type>): Undefined {
  for item in items {
    self.push(item)
  }
}

global method swap for Array<Type>(self: Array<Type>, i: U64, j: U64): IndexError ! Undefined {
  if i >= self.used or j >= self.used then { error self.outOfRange(i.max(j)) }
  let held := self.load(i)
  self.store(i, self.load(j))
  self.store(j, held)
}

global method fill for Array<Type>(self: Array<Type>, value: Type): Undefined {
  for i in 0..<self.used {
    self.store(i, value)
  }
}

global method resize for Array<Type>(self: Array<Type>, size: U64, fill: Type): Undefined {
  if size < self.used then {
    self.truncate(size)
  } else {
    self.reserve(size)
    for i in self.used..<size {
      self.store(i, fill)
    }
    set self.used := size
  }
}

global method truncate for Array<Type>(self: Array<Type>, size: U64): Undefined {
  set self.used := self.used.min(size)
}

global method clear for Array<Type>(self: Array<Type>): Undefined {
  set self.used := 0
}

global method map for Array<Type, Result>(self: Array<Type>, f: Lambda<Type, Result>): Array<Result> {
  return Array.generate(self.used, λ(i) f(self.load(i)))
}

global method mapIndexed for Array<Type, Result>(self: Array<Type>, f: Lambda<(U64, Type), Result>): Array<Result> {
  return Array.generate(self.used, λ(i) f(i, self.load(i)))
}

global method flatMap for Array<Type, Result>(self: Array<Type>, f: Lambda<Type, Iterable<Result>>): Array<Result> {
  let result: Array<Result> := []
  for item in self {
    set result ++= f(item)
  }
  return result
}

global method filter for Array<Type>(self: Array<Type>, keep: Lambda<Type, Boolean>): Array<Type> {
  let result: Array<Type> := []
  for item in self if keep(item) {
    result.push(item)
  }
  return result
}

global method filterMap for Array<Type, Result>(self: Array<Type>, f: Lambda<Type, Result?>): Array<Result> {
  let result: Array<Result> := []
  for item in self {
    let mapped := f(item)
    if mapped != undefined then { result.push(mapped) }
  }
  return result
}

/// Type is Iterable<Inner>
global method flatten for Array<Type, Inner>(self: Array<Type>): Array<Inner> {
  return self.flatMap(λ(inner) inner)
}

/// as long as the shorter side
global method zip for Array<Type, Other>(self: Array<Type>, other: Iterable<Other>): Array<(Type, Other)> {
  return self.iterator().zip(other).collect()
}

global method enumerate for Array<Type>(self: Array<Type>): Array<(U64, Type)> {
  return self.mapIndexed(λ(i, item) (i, item))
}

global method take for Array<Type>(self: Array<Type>, count: U64): Array<Type> {
  return self.slice(0..<count.min(self.used)) !? []
}

global method drop for Array<Type>(self: Array<Type>, count: U64): Array<Type> {
  return self.slice(count.min(self.used)..<self.used) !? []
}

global method takeWhile for Array<Type>(self: Array<Type>, where: Lambda<Type, Boolean>): Array<Type> {
  return self.take(self.findIndex(λ(x) not where(x)) ?? self.used)
}

global method dropWhile for Array<Type>(self: Array<Type>, where: Lambda<Type, Boolean>): Array<Type> {
  return self.drop(self.findIndex(λ(x) not where(x)) ?? self.used)
}

/// the last chunk is shorter when size doesn't divide the length
global method chunks for Array<Type>(self: Array<Type>, size: U64): Array<Array<Type>> {
  let n := size.max(1)
  return Array.generate((self.used + n - 1) / n, λ(k) self.slice((k * n)..<((k + 1) * n).min(self.used)) !? [])
}

global method windows for Array<Type>(self: Array<Type>, size: U64): Iterator<Window<Type>> {
  for start in 0..<(self.used + 1) while size > 0 and start + size <= self.used {
    yield Window<Type>{source := self, offset := start, width := size, position := start}
  }
}

/// Type: Hashable - keeps the first of each
global method distinct for Array<Type>(self: Array<Type>): Array<Type> {
  let seen: Set<Type> := Set.of()
  return self.filter(λ(item) seen.add(item))
}

global method reverse for Array<Type>(self: Array<Type>): Array<Type> {
  return Array.generate(self.used, λ(i) self.load(self.used - 1 - i))
}

/// positive count moves items toward the front: [1, 2, 3].rotate(1) is [2, 3, 1]
global method rotate for Array<Type>(self: Array<Type>, count: S64): Array<Type> {
  if self.used == 0 then { return [] }
  let shift := (count.modulo(self.used as S64)) as U64
  return Array.generate(self.used, λ(i) self.load((i + shift) % self.used))
}

global method sort for Array<Type>(self: Array<Type>): Undefined {
  self.sortWith(λ(a, b) a.compare(b))
}

global method sortBy for Array<Type, Key: Comparable>(self: Array<Type>, key: Lambda<Type, Key>): Undefined {
  self.sortWith(λ(a, b) key(a).compare(key(b)))
}

/// merge sort - stable, and n log n whatever the input; runs of width 1, 2, 4, ... merged bottom-up
/// through a scratch array
global method sortWith for Array<Type>(self: Array<Type>, compare: Lambda<(Type, Type), Ordering>): Undefined {
  let scratch := self.clone()
  let width: U64 := 1
  for _ in forever() while width < self.used {
    for left in (0..<self.used).step(2 * width) {
      let middle := (left + width).min(self.used)
      let right := (left + 2 * width).min(self.used)
      let (i, j) := (left, middle)
      for k in left..<right {
        if i < middle and (j >= right or compare(self.load(j), self.load(i)) != Ordering.Less) then {
          scratch.store(k, self.load(i))
          set i += 1
        } else {
          scratch.store(k, self.load(j))
          set j += 1
        }
      }
    }
    for k in 0..<self.used {
      self.store(k, scratch.load(k))
    }
    set width *= 2
  }
}

global method sorted for Array<Type>(self: Array<Type>): Array<Type> {
  let copy := self.clone()
  copy.sort()
  return copy
}

global method sortedBy for Array<Type, Key: Comparable>(self: Array<Type>, key: Lambda<Type, Key>): Array<Type> {
  let copy := self.clone()
  copy.sortBy(key)
  return copy
}

global method sortedWith for Array<Type>(self: Array<Type>, compare: Lambda<(Type, Type), Ordering>): Array<Type> {
  let copy := self.clone()
  copy.sortWith(compare)
  return copy
}

global method isSorted for Array<Type>(self: Array<Type>): Boolean {
  return (1..<self.used.max(1)).all(λ(i) self.load(i - 1) <= self.load(i))
}

/// on a sorted array - the error carries where item would be inserted to keep it sorted
global method binarySearch for Array<Type>(self: Array<Type>, item: Type): U64 ! U64 {
  let (low, high) := (0 as U64, self.used)
  for _ in forever() while low < high {
    let middle := low + (high - low) / 2
    match self.load(middle).compare(item) {
      case Ordering.Less then { set low := middle + 1 }
      case Ordering.Greater then { set high := middle }
      case _ then { return middle }
    }
  }
  error low
}

/// Fisher-Yates - every order equally likely, given a uniform &random
global method shuffle for Array<Type>(self: Array<Type>): Undefined {
  for i in (1..<self.used).reverse() {
    self.swap(i, &random.between(0..=(i as Integer)) as U64) !? undefined
  }
}

global method sample for Array<Type>(self: Array<Type>): Type? {
  return self.used == 0 ? undefined : self.load(&random.between(0..<(self.used as Integer)) as U64)
}

global method cursor for Array<Type>(self: Array<Type>): Cursor<Type> {
  return Cursor.over(self)
}

global method toStack for Array<Type>(self: Array<Type>): Stack<Type> {
  return Stack.fromIterable(self)
}

global method toQueue for Array<Type>(self: Array<Type>): Queue<Type> {
  return Queue.fromIterable(self)
}

global method toDeque for Array<Type>(self: Array<Type>): Deque<Type> {
  return Deque.fromIterable(self)
}

method iterator(self: Array<Type>): Iterator<Type> {
  for i in 0..<self.used {
    yield self.load(i)
  }
}

function fromIterable(items: Iterable<Type>): Array<Type> {
  let result := Self.empty()
  set result ++= items
  return result
}

method contains(self: Array<Type>, item: Type): Boolean {
  return self.indexOf(item) != undefined
}

method size(self: Array<Type>): U64 {
  return self.used
}

method isEmpty(self: Array<Type>): Boolean {
  return self.used == 0
}

method get(self: Array<Type>, key: U64): Type? {
  return key < self.used ? self.load(key) : undefined
}

method set(self: Array<Type>, key: U64, value: Type): Error ! Undefined {
  if key >= self.used then { error self.outOfRange(key) }
  self.store(key, value)
}

method equals(self: Array<Type>, other: Array<Type>): Boolean {
  return self.used == other.used and (0..<self.used).all(λ(i) self.load(i) == other.load(i))
}

method hash(self: Array<Type>): U64 {
  return self.reduce(hashCombine(&hashSeed, self.used), λ(hash, item) hashCombine(hash, item.hash()))
}

method compare(self: Array<Type>, other: Array<Type>): Ordering {
  for i in 0..<self.used.min(other.used) {
    let order := self.load(i).compare(other.load(i))
    if order != Ordering.Equal then { return order }
  }
  return self.used.compare(other.used)
}

/// "[1, 2, 3]"
method toString(self: Array<Type>): String {
  return "[" ++ self.join(", ") ++ "]"
}

/// extend, not ++= - that's this function
method concat(self: Array<Type>, other: Iterable<Type>): Array<Type> {
  let result := self.clone()
  result.pushAll(other)
  return result
}

function default(): Array<Type> {
  return Self.empty()
}

method clone(self: Array<Type>): Array<Type> {
  return Array.generate(self.used, λ(i) self.load(i))
}

global method push for Stack<Type>(self: Stack<Type>, item: Type): Undefined {
  self.items.push(item)
}

global method pop for Stack<Type>(self: Stack<Type>): Type? {
  return self.items.pop()
}

global method peek for Stack<Type>(self: Stack<Type>): Type? {
  return self.items.last()
}

global method pushAll for Stack<Type>(self: Stack<Type>, items: Iterable<Type>): Undefined {
  set self.items ++= items
}

global method drain for Stack<Type>(self: Stack<Type>): Iterator<Type> {
  for _ in forever() while not self.items.isEmpty() {
    yield self.items.pop() ?? undefined
  }
}

global method clear for Stack<Type>(self: Stack<Type>): Undefined {
  self.items.clear()
}

/// top to bottom - the order pop() would give them
method iterator(self: Stack<Type>): Iterator<Type> {
  return self.items.reverse().iterator()
}

/// pushed in order, so the last item ends up on top
function fromIterable(items: Iterable<Type>): Stack<Type> {
  return Stack<Type>{items := items.toArray()}
}

method contains(self: Stack<Type>, item: Type): Boolean {
  return self.items.contains(item)
}

method size(self: Stack<Type>): U64 {
  return self.items.size()
}

method isEmpty(self: Stack<Type>): Boolean {
  return self.items.isEmpty()
}

method equals(self: Stack<Type>, other: Stack<Type>): Boolean {
  return self.items == other.items
}

method hash(self: Stack<Type>): U64 {
  return self.items.hash()
}

method toString(self: Stack<Type>): String {
  return "Stack" ++ self.items.toString()
}

method concat(self: Stack<Type>, other: Stack<Type>): Stack<Type> {
  return Stack<Type>{items := self.items ++ other.items}
}

function default(): Stack<Type> {
  return Stack<Type>{items := []}
}

method clone(self: Stack<Type>): Stack<Type> {
  return Stack<Type>{items := self.items.clone()}
}

global method enqueue for Queue<Type>(self: Queue<Type>, item: Type): Undefined {
  self.items.pushBack(item)
  for handler in self.handlers {
    handler(item)
  }
  if self.clearsAfterHandlers and not self.handlers.isEmpty() then {
    self.clear()
  }
}

global method setClearsAfterHandlers for Queue<Type>(self: Queue<Type>, clears: Boolean): Undefined {
  set self.clearsAfterHandlers := clears
}

/// in the order they were given - a handler that enqueues runs the handlers again, for that item
global method onAdd for Queue<Type>(self: Queue<Type>, handler: Lambda<Type, Undefined>): Undefined {
  self.handlers.push(handler)
}

global method dequeue for Queue<Type>(self: Queue<Type>): Type? {
  return self.items.popFront()
}

global method peek for Queue<Type>(self: Queue<Type>): Type? {
  return self.items.peekFront()
}

global method enqueueAll for Queue<Type>(self: Queue<Type>, items: Iterable<Type>): Undefined {
  for item in items {
    self.enqueue(item)
  }
}

global method drain for Queue<Type>(self: Queue<Type>): Iterator<Type> {
  for _ in forever() while not self.items.isEmpty() {
    yield self.items.popFront() ?? undefined
  }
}

global method clear for Queue<Type>(self: Queue<Type>): Undefined {
  self.items.clear()
}

/// front to back - the order dequeue() would give them
method iterator(self: Queue<Type>): Iterator<Type> {
  return self.items.iterator()
}

function fromIterable(items: Iterable<Type>): Queue<Type> {
  return Queue<Type>{items := Deque.fromIterable(items), handlers := [], clearsAfterHandlers := false}
}

method contains(self: Queue<Type>, item: Type): Boolean {
  return self.items.contains(item)
}

method size(self: Queue<Type>): U64 {
  return self.items.size()
}

method isEmpty(self: Queue<Type>): Boolean {
  return self.items.isEmpty()
}

method equals(self: Queue<Type>, other: Queue<Type>): Boolean {
  return self.items == other.items
}

method hash(self: Queue<Type>): U64 {
  return self.items.hash()
}

method toString(self: Queue<Type>): String {
  return "Queue[" ++ self.join(", ") ++ "]"
}

method concat(self: Queue<Type>, other: Queue<Type>): Queue<Type> {
  return Queue<Type>{items := self.items ++ other.items, handlers := [], clearsAfterHandlers := false}
}

function default(): Queue<Type> {
  return Queue<Type>{items := Deque.default(), handlers := [], clearsAfterHandlers := false}
}

method clone(self: Queue<Type>): Queue<Type> {
  return Queue<Type>{items := self.items.clone(), handlers := [], clearsAfterHandlers := false}
}

/// where the index-th item from the front lives
local method slot for Deque<Type>(self: Deque<Type>, index: U64): Pointer<Type> {
  return self.memory.offset(((self.head + index) % self.capacity) as S64)
}

/// grows by doubling, unwrapping the items to start at 0 in the new allocation
local method reserve for Deque<Type>(self: Deque<Type>, needed: U64): Undefined {
  if needed <= self.capacity then { return }
  let bigger := self.capacity.max(4)
  for _ in forever() while bigger < needed {
    set bigger *= 2
  }
  let moved := allocate<Type>(bigger)
  for i in 0..<self.used {
    moved.offset(i as S64).write(self.slot(i).read())
  }
  if self.capacity > 0 then { self.memory.free() }
  set self.memory := moved
  set self.head := 0
  set self.capacity := bigger
}

global method pushFront for Deque<Type>(self: Deque<Type>, item: Type): Undefined {
  self.reserve(self.used + 1)
  set self.head := (self.head + self.capacity - 1) % self.capacity
  self.slot(0).write(item)
  set self.used += 1
  self.added(item)
}

global method pushBack for Deque<Type>(self: Deque<Type>, item: Type): Undefined {
  self.reserve(self.used + 1)
  self.slot(self.used).write(item)
  set self.used += 1
  self.added(item)
}

/// in the order they were given - a handler that pushes runs the handlers again, for that item
global method onAdd for Deque<Type>(self: Deque<Type>, handler: Lambda<Type, Undefined>): Undefined {
  self.handlers.push(handler)
}

global method setClearsAfterHandlers for Deque<Type>(self: Deque<Type>, clears: Boolean): Undefined {
  set self.clearsAfterHandlers := clears
}

local method added for Deque<Type>(self: Deque<Type>, item: Type): Undefined {
  for handler in self.handlers {
    handler(item)
  }
  if self.clearsAfterHandlers and not self.handlers.isEmpty() then {
    self.clear()
  }
}

global method popFront for Deque<Type>(self: Deque<Type>): Type? {
  if self.used == 0 then { return undefined }
  let item := self.slot(0).read()
  set self.head := (self.head + 1) % self.capacity
  set self.used -= 1
  return item
}

global method popBack for Deque<Type>(self: Deque<Type>): Type? {
  if self.used == 0 then { return undefined }
  set self.used -= 1
  return self.slot(self.used).read()
}

global method peekFront for Deque<Type>(self: Deque<Type>): Type? {
  return self.used == 0 ? undefined : self.slot(0).read()
}

global method peekBack for Deque<Type>(self: Deque<Type>): Type? {
  return self.used == 0 ? undefined : self.slot(self.used - 1).read()
}

/// positive count moves items from the front to the back, like Array.rotate - nothing is added, so no handler runs
global method rotate for Deque<Type>(self: Deque<Type>, count: S64): Undefined {
  if self.used == 0 then { return }
  for _ in 0..<(count.modulo(self.used as S64) as U64) {
    let item := self.popFront() ?? undefined
    self.slot(self.used).write(item)
    set self.used += 1
  }
}

global method toArray for Deque<Type>(self: Deque<Type>): Array<Type> {
  return Array.generate(self.used, λ(i) self.slot(i).read())
}

global method clear for Deque<Type>(self: Deque<Type>): Undefined {
  set self.head := 0
  set self.used := 0
}

method iterator(self: Deque<Type>): Iterator<Type> {
  for i in 0..<self.used {
    yield self.slot(i).read()
  }
}

function fromIterable(items: Iterable<Type>): Deque<Type> {
  let result := Deque<Type>.default()
  for item in items {
    result.pushBack(item)
  }
  return result
}

method contains(self: Deque<Type>, item: Type): Boolean {
  return self.iterator().any(λ(x) x == item)
}

method size(self: Deque<Type>): U64 {
  return self.used
}

method isEmpty(self: Deque<Type>): Boolean {
  return self.used == 0
}

method get(self: Deque<Type>, key: U64): Type? {
  return key < self.used ? self.slot(key).read() : undefined
}

method set(self: Deque<Type>, key: U64, value: Type): Error ! Undefined {
  if key >= self.used then { error IndexError.new("index " ++ key.toString() ++ " is past the end of " ++ self.used.toString() ++ " items") }
  self.slot(key).write(value)
}

method equals(self: Deque<Type>, other: Deque<Type>): Boolean {
  return self.toArray() == other.toArray()
}

method hash(self: Deque<Type>): U64 {
  return self.toArray().hash()
}

method toString(self: Deque<Type>): String {
  return "Deque" ++ self.toArray().toString()
}

method concat(self: Deque<Type>, other: Deque<Type>): Deque<Type> {
  let result := self.clone()
  for item in other {
    result.pushBack(item)
  }
  return result
}

function default(): Deque<Type> {
  return Deque<Type>{memory := allocate<Type>(0), head := 0, used := 0, capacity := 0, handlers := [], clearsAfterHandlers := false}
}

method clone(self: Deque<Type>): Deque<Type> {
  return Deque.fromIterable(self)
}

global function of for Set<Type>(items: ..Type): Set<Type> {
  return Set.fromIterable(items)
}

global method add for Set<Type>(self: Set<Type>, item: Type): Boolean {
  if self.members.has(item) then { return false }
  self.members.set(item, true)
  return true
}

global method remove for Set<Type>(self: Set<Type>, item: Type): Boolean {
  return self.members.remove(item) != undefined
}

global method addAll for Set<Type>(self: Set<Type>, items: Iterable<Type>): Undefined {
  for item in items {
    self.add(item)
  }
}

global method removeAll for Set<Type>(self: Set<Type>, items: Iterable<Type>): Undefined {
  for item in items {
    self.remove(item)
  }
}

global method retain for Set<Type>(self: Set<Type>, where: Lambda<Type, Boolean>): Undefined {
  for item in self.toArray() if not where(item) {
    self.remove(item)
  }
}

global method intersection for Set<Type>(self: Set<Type>, other: Set<Type>): Set<Type> {
  return self.filter(λ(item) other.has(item))
}

global method difference for Set<Type>(self: Set<Type>, other: Set<Type>): Set<Type> {
  return self.filter(λ(item) not other.has(item))
}

global method symmetricDifference for Set<Type>(self: Set<Type>, other: Set<Type>): Set<Type> {
  return self.difference(other) ++ other.difference(self)
}

global method isSubsetOf for Set<Type>(self: Set<Type>, other: Set<Type>): Boolean {
  return self.all(λ(item) other.has(item))
}

global method isSupersetOf for Set<Type>(self: Set<Type>, other: Set<Type>): Boolean {
  return other.isSubsetOf(self)
}

global method isDisjointFrom for Set<Type>(self: Set<Type>, other: Set<Type>): Boolean {
  return self.none(λ(item) other.has(item))
}

global method map for Set<Type, Result: Hashable>(self: Set<Type>, f: Lambda<Type, Result>): Set<Result> {
  return Set.fromIterable(self.iterator().map(f))
}

global method filter for Set<Type>(self: Set<Type>, keep: Lambda<Type, Boolean>): Set<Type> {
  return Set.fromIterable(self.iterator().filter(keep))
}

global method clear for Set<Type>(self: Set<Type>): Undefined {
  self.members.clear()
}

/// in the order the items were first added
method iterator(self: Set<Type>): Iterator<Type> {
  return self.members.keys()
}

function fromIterable(items: Iterable<Type>): Set<Type> {
  let result := Set<Type>{members := Map.of()}
  result.addAll(items)
  return result
}

method contains(self: Set<Type>, item: Type): Boolean {
  return self.members.has(item)
}

method size(self: Set<Type>): U64 {
  return self.members.size()
}

method isEmpty(self: Set<Type>): Boolean {
  return self.members.isEmpty()
}

method equals(self: Set<Type>, other: Set<Type>): Boolean {
  return self.size() == other.size() and self.isSubsetOf(other)
}

method hash(self: Set<Type>): U64 {
  return self.reduce(&hashSeed, λ(total, item) total.wrappingAdd(item.hash()))
}