Core Library

The core library handles the operations that appear in most small programs: printing text, converting values, inspecting Unicode, representing absence or failure, and transforming collections. Start here before reaching for a specialized namespace.

Choose the everyday helper

Some, None, Ok, and Err are constructors in the prelude. A bare None, Ok, Err, or empty collection needs an expected type when inference cannot determine every type argument.

Parse and transform values

This program keeps each failed parse as None and counts Korean text by Unicode scalar rather than byte.

function parseAll(values: Array<string>) -> Array<Option<int>> {
    return map(values, value => toInt(value))
}

let scalars = "토파즈".scalars()
let parsed = parseAll(["1", "x", "3"])
print("{scalars.length}:{parsed}")

3:[Some(1), None, Some(3)]

print accepts a string, so interpolation makes the conversion visible. toInt returns None for "x"; map does not turn that ordinary absence into a fault. Use a match when the caller needs to turn absence into a descriptive Result.

Common correction: toFloat converts an int; it does not parse a string. There is no general free toString, len, println, or type_of function. Use interpolation, the exact type member such as .length, and the documented conversion helper.

Public surface

Use these exact everyday names:

• print(string) -> () writes one line. input() -> string returns the complete host-provided text payload for that run; it is not a line reader.
• toInt(string) -> Option<int> and toIntRadix(string, int) -> Option<int> parse integers.
• toFloat(int) -> float converts an integer; it is not a text parser.
• fromCodePoint(int) -> Option<string> constructs one valid Unicode scalar.
• text.scalars() -> Array<string> exposes a string as Unicode scalars.
• Some and None construct Option; Ok and Err construct Result.
• option.okOr(error: E) -> Result<T, E> evaluates the error eagerly. option.okOrElse(f: () -> E) -> Result<T, E> calls f only for None.
• option.map(f: (T) -> U) -> Option<U> transforms Some; option.flatMap(f: (T) -> Option<U>) -> Option<U> avoids a nested Option. Both preserve None without calling f.
• result.map(f: (T) -> U) -> Result<U, E> transforms Ok; result.flatMap(f: (T) -> Result<U, E>) -> Result<U, E> avoids a nested Result. Both preserve Err without calling f.
• Free map, filter, and reduce transform iterable values. They are distinct from the receiver helpers above, and none of these helpers catches a fault.

The Bytes, ByteBuffer, Hash, and Codec sections below demonstrate a selected bounded surface, not an exhaustive inventory. Claim only the members shown there; a similarly named helper inside one runtime or generated target is not an additional Topaz API.

Assemble bytes in place

Use ByteBuffer.allocate(length, value = 0) when an algorithm must write many bytes into one contiguous fixed-length value. set, fill, and copy require a let mut receiver root. Every range and byte value is checked before the first write, so a fault cannot leave a partially changed target.

let mut row = ByteBuffer.allocate(8)
row.fill(0, 8, 255)
row.set(0, 137)

let mut frame = ByteBuffer.allocate(12)
frame.copy(row, 0, 2, 8)
let payload = frame.toBytes()
print(payload.toHex())

000089ffffffffffffff0000

Assignment shares a ByteBuffer's mutable identity. ByteBuffer.fromBytes copies into a new buffer, and toBytes() returns an immutable snapshot. A ByteBuffer cannot cross a Web export, participate in equality or ordering, serve as a Map/Set key, enter text or JSON, or be used after an invalid range is silently repaired.

Compute a CRC-32 integrity field

Hash.crc32(data) returns the unsigned CRC-32/ISO-HDLC value. It is useful for file-format integrity fields, not for authentication or adversarial tamper resistance.

let checksum = Hash.crc32(Bytes.encodeUtf8("123456789"))
print("{checksum}")

3421780262

std.hash.crc32 exposes the same operation through the fixed standard-module surface.

Produce deterministic fixed DEFLATE

Use Codec.deflateFixedCompress(bytes) for one canonical raw fixed-Huffman DEFLATE block without zlib or gzip framing.

match Codec.deflateFixedCompress(Bytes.encodeUtf8("hello")) {
  case Ok(compressed) => print(compressed.toHex())
  case Err(error) => print(error)
}

cb48cdc9c90700

Search and memory are bounded, and input above 256 MiB returns Err. Generated Python does not expose this Codec member and declines before writing an artifact.

Produce deterministic fixed zlib

Use Codec.zlibFixedCompress(bytes) when the format needs a complete zlib stream: the fixed 78 01 header, fixed-Huffman payload, and Adler-32 trailer.

match Codec.zlibFixedCompress(Bytes.encodeUtf8("hello")) {
  case Ok(compressed) => print(compressed.toHex())
  case Err(error) => print(error)
}

7801cb48cdc9c90700062c0215

Input above 256 MiB returns Err. Generated Python does not expose this Codec member and declines before artifact creation. This operation does not add decompression, levels, dictionaries, streaming, or a general Adler-32 API.

Add Reed–Solomon protection bytes

Codec.reedSolomon255223Protect(bytes) emits systematic RS(255,223) codewords. Each 223-byte data shard is followed by 32 parity bytes, and the final data shard is zero-padded.

match Codec.reedSolomon255223Protect(Bytes.encodeUtf8("hello")) {
  case Ok(protected) => print("{protected.length()}")
  case Err(error) => print(error)
}

255

The caller retains the original logical length. Input must be non-empty and may use at most 65,535 shards. The function creates protection bytes; it does not detect or repair corruption. Generated Python does not expose this Codec member and declines before artifact creation.

Exact boundaries

• String operations use scalar positions unless their name explicitly says bytes.
• Option.map preserves ordinary absence; Result.map does not catch faults.
• map, filter, and reduce accept only the fixed iterable families.
• Typed JSON needs one written, fully known target and returns a $-rooted error path for data failure.
• input and print require an environment that provides their host capability.
• assert is a function only in the test profile, never a language keyword.

Continue with Standard Library Overview, Null, Option, Result & Faults, or Runtime Behavior.