ModBoss.Encoding (modboss v0.1.0)

Built-in encoding/decoding functions to get you started.

To make use of these functions, use the :as option in your ModBoss.Schema but leave off the encode_ or decode_ prefix.

In other words, to use the built-in ASCII translation, specifiy as: :ascii in your schema.

Note about that extra arg…

Note that for built-in encode_* functions, we pass not just the value but also the mapping itself. That's why you'll see an extra argument passed to these encoders!

We do this in order to provide more generic and helpful functions out the box (like encoding of ASCII, which requires knowledge of how many registers we're encoding for). However, when providing your own encode_* functions, you'll only be passed the value to be encoded (and not the mapping).

Summary

Functions

decode_ascii(value)

Decode integer value(s) representing ASCII characters to text

decode_boolean(int)

Interpret 1 as true and 0 as false

decode_signed_int(value)

Decode value to a signed integer.

decode_unsigned_int(value)

Decode value to an unsigned integer.

encode_ascii(text, mapping)

Encode text to integers representing ASCII characters.

encode_boolean(bool, mapping)

Encode true as 1 and false as 0

encode_signed_int(value, mapping)

Encode value as a signed integer.

encode_unsigned_int(value, mapping)

Encode value as an unsigned integer.

Functions

decode_ascii(value)

@spec decode_ascii(integer() | [integer()]) :: {:ok, binary()}

Decode integer value(s) representing ASCII characters to text

  • Up to 2 ASCII characters are stored per register.
  • 0 is interpreted as a terminator.

Examples

iex> decode_ascii(18537)
{:ok, "Hi"}

iex> decode_ascii([18537, 8448, 0])
{:ok, "Hi!"}

decode_boolean(int)

@spec decode_boolean(integer()) :: {:ok, boolean()} | {:error, binary()}

Interpret 1 as true and 0 as false

decode_signed_int(value)

@spec decode_signed_int(integer()) :: {:ok, integer()}

Decode value to a signed integer.

Examples

iex> decode_signed_int(77)
{:ok, 77}

iex> decode_signed_int(65_535)
{:ok, -1}

decode_unsigned_int(value)

@spec decode_unsigned_int(integer()) :: {:ok, integer()}

Decode value to an unsigned integer.

Examples

iex> decode_unsigned_int(65_535)
{:ok, 65_535}

encode_ascii(text, mapping)

@spec encode_ascii(binary(), ModBoss.Mapping.t()) ::
  {:ok, [integer()]} | {:error, binary()}

Encode text to integers representing ASCII characters.

  • Prepares zero or more characters to be stored in contiguous registers.
  • Up to 2 ASCII characters can be stored per register.
  • 0 is used as a terminator if fewer than the maximum characters are encoded.
  • The ModBoss.Mapping is required in order to determine how many characters are supported.

Examples

iex> encode_ascii("Hi!", %ModBoss.Mapping{register_count: 3})
{:ok, [18537, 8448, 0]}

iex> {:error, _too_many_characters} = encode_ascii("Hi!", %ModBoss.Mapping{register_count: 1})

encode_boolean(bool, mapping)

@spec encode_boolean(boolean(), ModBoss.Mapping.t()) ::
  {:ok, integer()} | {:error, binary()}

Encode true as 1 and false as 0

encode_signed_int(value, mapping)

@spec encode_signed_int(integer(), ModBoss.Mapping.t()) ::
  {:ok, integer()} | {:error, binary()}

Encode value as a signed integer.

Valid values are -32,768 to 32,767.

This function assumes the expected output is a regular Elixir integer. It simply provides a guard against overly large values, then returns the provided value.

Examples

iex> {:ok, -32_768} = encode_signed_int(-32_768, %{})
iex> {:error, _too_large} = encode_signed_int(32_768, %{})

encode_unsigned_int(value, mapping)

@spec encode_unsigned_int(integer(), ModBoss.Mapping.t()) ::
  {:ok, integer()} | {:error, binary()}

Encode value as an unsigned integer.

Valid values are 0 to 65,535.

This function assumes the expected output is a regular Elixir integer. It simply provides a guard against overly large values, then returns the provided value.

Examples

iex> {:ok, 65_535} = encode_unsigned_int(65_535, %{})
iex> {:error, _too_large} = encode_unsigned_int(65_536, %{})