ModBoss.Encoding (modboss v0.1.1)
View SourceBuilt-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.
For example, to use the built-in ASCII translation, specify 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 integer value
(s) representing ASCII characters to text
Interpret 1
as true
and 0
as false
Decode value
to a signed integer.
Decode value
to an unsigned integer.
Encode text
to integers representing ASCII characters.
Encode true
as 1
and false
as 0
Encode value
as a signed integer.
Encode value
as an unsigned integer.
Functions
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!"}
Interpret 1
as true
and 0
as false
Examples
iex> decode_boolean(0)
{:ok, false}
iex> decode_boolean(1)
{:ok, true}
Decode value
to a signed integer.
Examples
iex> decode_signed_int(77)
{:ok, 77}
iex> decode_signed_int(65_535)
{:ok, -1}
Decode value
to an unsigned integer.
Examples
iex> decode_unsigned_int(65_535)
{:ok, 65_535}
@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{address_count: 3})
{:ok, [18537, 8448, 0]}
iex> {:error, _too_many_characters} = encode_ascii("Hi!", %ModBoss.Mapping{address_count: 1})
@spec encode_boolean(boolean(), ModBoss.Mapping.t()) :: {:ok, integer()} | {:error, binary()}
Encode true
as 1
and false
as 0
Examples
iex> encode_boolean(true, %{})
{:ok, 1}
iex> encode_boolean(false, %{})
{:ok, 0}
@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, %{})
@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, %{})