ToonEx.Btoon (toon_ex v1.3.1)

Copy Markdown View Source

BTOON — a compact binary codec for the TOON data model.

BTOON is the binary transport encoding of the TOON data model (see the BTOON specification in btoon_spec/spec.md). Unlike TOON's text form it is optimized for CPU cost first and wire size second:

  • a fixed 8-byte envelope ("BTON" magic, version, flags) with an optional per-message string table, optional embedded schema and an 8-byte-aligned body;
  • inline SmallInt values and fixed-width little-endian integers and floats (never varints);
  • strings deduplicated against a session dictionary and per-message string table via StringRef;
  • homogeneous numeric lists as TypedArray and homogeneous object lists as columnar ObjectTable, both padded so decoders can expose zero-copy views;
  • optional schema mode that drops keys and tags entirely.

Every input maps to exactly one byte sequence (deterministic encoding).

Quick start

iex> bin = ToonEx.Btoon.encode!(%{"name" => "Alice", "age" => 30})
iex> ToonEx.Btoon.decode!(bin)
%{"name" => "Alice", "age" => 30}

Encodable values

nil, booleans, integers, floats, strings (binaries), ToonEx.Btoon.Binary blobs, ToonEx.Btoon.TypedArray, ToonEx.Btoon.ObjectTable, lists and maps with string keys. Map keys are sorted during encoding, so field order is deterministic but not preserved.

Options

See ToonEx.Btoon.Encode.Options and ToonEx.Btoon.Decode.Options for the accepted encode/decode options.

Summary

Functions

decode(binary, opts \\ [])

Decodes a BTOON binary.

decode!(binary, opts \\ [])

Decodes a BTOON binary, raising Btoon.DecodeError on error.

encode(data, opts \\ [])

Encodes data to the BTOON binary format.

encode!(data, opts \\ [])

Encodes data to the BTOON binary format, raising Btoon.EncodeError on error.

encode_to_iodata!(data, opts \\ [])

Encodes data to BTOON iodata without flattening to a single binary, raising Btoon.EncodeError on error.

Functions

decode(binary, opts \\ [])

@spec decode(
  binary(),
  keyword()
) :: {:ok, term()} | {:error, ToonEx.Btoon.DecodeError.t()}

Decodes a BTOON binary.

Returns {:ok, value} or {:error, Btoon.DecodeError.t()}.

decode!(binary, opts \\ [])

@spec decode!(
  binary(),
  keyword()
) :: term()

Decodes a BTOON binary, raising Btoon.DecodeError on error.

encode(data, opts \\ [])

@spec encode(
  ToonEx.Btoon.Types.encodable(),
  keyword()
) :: {:ok, binary()} | {:error, ToonEx.Btoon.EncodeError.t()}

Encodes data to the BTOON binary format.

Returns {:ok, binary} or {:error, Btoon.EncodeError.t()}.

encode!(data, opts \\ [])

@spec encode!(
  ToonEx.Btoon.Types.encodable(),
  keyword()
) :: binary()

Encodes data to the BTOON binary format, raising Btoon.EncodeError on error.

encode_to_iodata!(data, opts \\ [])

@spec encode_to_iodata!(
  ToonEx.Btoon.Types.encodable(),
  keyword()
) :: iodata()

Encodes data to BTOON iodata without flattening to a single binary, raising Btoon.EncodeError on error.

Returns an iodata structure suitable for passing directly to IO functions or IO.iodata_to_binary/1. This avoids an intermediate flattening step when the caller intends to write the result to a socket or file.

Examples

iex> iodata = Btoon.encode_to_iodata!(%{"a" => [1, 2]})
iex> IO.iodata_to_binary(iodata) == Btoon.encode!(%{"a" => [1, 2]})
true