Iconvex.Packed (iconvex v0.1.1)

Packed transports for codecs that expose one fixed-width unit per octet.

pack/2 returns an exact MSB-first Elixir bitstring. pack_lsb/2 returns a byte-backed stream plus its exact bit length because LSB-first padding lives in the high bits of the final octet and cannot be represented by an Elixir bitstring without changing wire order.

Summary

Types

error_result()

width()

Functions

decode_to_utf8(input, encoding, width)

MSB-first unpacks units, then converts them from the named codec to UTF-8.

decode_to_utf8_lsb(input, encoding)

Unpacks an LSB stream, then converts its units from the named codec to UTF-8.

encode_from_utf8(input, encoding, width)

Converts UTF-8 through an octet-backed codec, then MSB-first packs its units.

encode_from_utf8_lsb(input, encoding, width)

Converts UTF-8 through an octet-backed codec, then LSB-first packs its units.

pack(units, width)

Packs one byte-backed unit at a time into an exact MSB-first bitstring.

pack_lsb(units, width)

Packs units LSB-first and returns byte data plus its exact meaningful bit count.

unpack(input, width)

Unpacks an exact MSB-first bitstring into one unit per byte.

unpack_lsb(data, bit_size, width)

Unpacks validated LSB-first byte data using an explicit meaningful bit count.

Types

error_result()

@type error_result() ::
  {:error, :invalid_unit_bits | :invalid_bit_size | :nonzero_padding_bits}
  | {:error, :bit_order_mismatch}
  | {:error, :incomplete_unit, non_neg_integer(),
     bitstring() | non_neg_integer()}
  | {:error, :unit_out_of_range, non_neg_integer(), byte()}

width()

@type width() :: 1..8

Functions

decode_to_utf8(input, encoding, width)

@spec decode_to_utf8(bitstring(), Iconvex.encoding(), width()) ::
  {:ok, binary()} | {:error, term()}

MSB-first unpacks units, then converts them from the named codec to UTF-8.

Semantic conversion failures use physical bit offsets. Their sequence is the exact MSB-first packed bitstring occupied by the failing units.

decode_to_utf8_lsb(input, encoding)

@spec decode_to_utf8_lsb(Iconvex.Packed.LSB.t(), Iconvex.encoding()) ::
  {:ok, binary()} | {:error, term()}

Unpacks an LSB stream, then converts its units from the named codec to UTF-8.

Semantic conversion failures use physical bit offsets. Their sequence is a self-describing Iconvex.Packed.LSB fragment so its wire order and exact meaningful bit length survive error reporting.

encode_from_utf8(input, encoding, width)

@spec encode_from_utf8(binary(), Iconvex.encoding(), width()) ::
  {:ok, bitstring()} | {:error, term()}

Converts UTF-8 through an octet-backed codec, then MSB-first packs its units.

encode_from_utf8_lsb(input, encoding, width)

@spec encode_from_utf8_lsb(binary(), Iconvex.encoding(), width()) ::
  {:ok, Iconvex.Packed.LSB.t()} | {:error, term()}

Converts UTF-8 through an octet-backed codec, then LSB-first packs its units.

pack(units, width)

@spec pack(binary(), width()) :: {:ok, bitstring()} | error_result()

Packs one byte-backed unit at a time into an exact MSB-first bitstring.

pack_lsb(units, width)

@spec pack_lsb(binary(), width()) :: {:ok, Iconvex.Packed.LSB.t()} | error_result()

Packs units LSB-first and returns byte data plus its exact meaningful bit count.

unpack(input, width)

@spec unpack(bitstring(), width()) :: {:ok, binary()} | error_result()

Unpacks an exact MSB-first bitstring into one unit per byte.

unpack_lsb(data, bit_size, width)

@spec unpack_lsb(binary(), non_neg_integer(), width()) ::
  {:ok, binary()} | error_result()

Unpacks validated LSB-first byte data using an explicit meaningful bit count.