Core Library

Convert text to numbers, handle missing values, and choose byte operations for your file format. Start with the text example, then use the tables to find a helper.

Install Topaz through First Program. Save each example in its own .tpz file and run it from that folder.

Parse and transform values

Save this as core-everyday.tpz.

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}")

Run topaz run core-everyday.tpz.

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

toInt converts "1" and "3" successfully. It returns None for "x", so map keeps that missing value in the result. Change "x" to "2" to get Some(2) in the middle.

"토파즈" contains three Unicode scalar values. A scalar is one Unicode code point outside the surrogate range. scalars() returns an array of these values as strings. Its length counts scalars, which can differ from bytes or visible characters.

print takes a string. Interpolation inside {...} converts the values to text before printing.

Choose the everyday helper

input() returns the same complete text on each call during a run. The environment must provide input and output support for input and print.

toFloat takes an int. For text containing an integer, parse with toInt first. Use interpolation to turn values into text and .length on an array to count elements. The free names toString, len, println, and type_of are unavailable.

Transform Option and Result

Some and None construct Option. Ok and Err construct Result. If the compiler cannot infer all type arguments, add a type annotation. This can happen with None, Ok, Err, or an empty collection.

The map and flatMap methods preserve None or Err without calling f. Free functions map, filter, and reduce work on the language's iterable types, such as arrays. None of these helpers catches a runtime error (fault).

Assemble bytes in place

Save this as core-byte-buffer.tpz.

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())

Run topaz run core-byte-buffer.tpz.

000089ffffffffffffff0000

row holds eight bytes. fill sets them to 255, and set replaces the first with 137. copy puts those eight bytes into frame, starting at index 2. The remaining bytes stay zero.

ByteBuffer.allocate(length, value = 0) creates a fixed-length buffer. set, fill, and copy need a receiver declared with let mut. They check all ranges and byte values before writing. Invalid arguments cause a fault and leave the target unchanged.

Assignment shares the same buffer. ByteBuffer.fromBytes makes a copy, and toBytes() creates an immutable snapshot. A ByteBuffer cannot be compared, used as a Map key or Set element, rendered as text or JSON, or passed through a Web export.

Compute a CRC-32 integrity field

Save this as core-crc32.tpz.

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

Run topaz run core-crc32.tpz.

3421780262

Hash.crc32(data) returns a CRC-32/ISO-HDLC checksum as an int in 0..4294967295. std.hash.crc32 provides the same operation. Use this checksum for file-format integrity fields. It does not authenticate data or protect against deliberate tampering.

Produce fixed DEFLATE

Save this as core-deflate.tpz.

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

Run topaz run core-deflate.tpz.

cb48cdc9c90700

Codec.deflateFixedCompress produces one raw DEFLATE block using fixed Huffman codes. The same input produces the same bytes. The output has no zlib or gzip header or checksum. Input above 256 MiB returns Err.

Produce fixed zlib

Save this as core-zlib.tpz.

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

Run topaz run core-zlib.tpz.

7801cb48cdc9c90700062c0215

Codec.zlibFixedCompress adds a 78 01 header and an Adler-32 checksum to the fixed-Huffman compressed data. The same input produces the same bytes. Input above 256 MiB returns Err.

This function has no decompression, compression-level, dictionary, or streaming options. It does not expose a separate Adler-32 calculation.

Add Reed–Solomon protection bytes

Save this as core-reed-solomon.tpz.

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

Run topaz run core-reed-solomon.tpz.

255

The function splits input into 223-byte blocks and adds 32 parity bytes to each block, producing RS(255,223) codewords. It fills the final short block with zeros. Keep the original input length separately to distinguish data from padding.

Empty input or input requiring more than 65,535 blocks returns Err. The function generates protection bytes. Detecting or repairing damaged data needs a decoder.

Related operations

Typed JSON calls need one explicit, fully known target type. A data error returns a path beginning with $. The free assert function requires the test profile.

Use Collection Operations for iterable values and Null, Option, Result & Faults for error handling. Runtime Behavior explains numeric results. Standard Library Overview lists other tasks.