@spec binary(binary(), pos_integer() | nil) :: {:ok, {binary(), binary()}} | :error

Extracts a binary value from a binary.

• data is the binary to extract the binary from.
• size is the size of the binary in bytes. If nil, the entire binary is extracted.

The function returns {:ok, {value, rest}} if the binary was successfully extracted. The value is the extracted binary and rest is the remaining binary.

Examples

iex> ArtNet.Decoder.binary(<<1, 2, 3, 4>>, nil)
{:ok, {<<1, 2, 3, 4>>, <<>>}}

iex> ArtNet.Decoder.binary(<<1, 2, 3, 4>>, 2)
{:ok, {<<1, 2>>, <<3, 4>>}}

iex> ArtNet.Decoder.binary(<<1, 2, 3, 4>>, 5)
:error

@spec bit_field(binary(), module()) :: {:ok, {struct(), binary()}} | :error

Extracts a bit field from a binary.

• data is the binary to extract the bit field from.
• module is the module that defines the bit field.

The function returns {:ok, {struct, rest}} if the bit field was successfully extracted. The struct is the extracted struct and rest is the remaining binary.

If the bit field could not be extracted, the function returns :error.

Examples

iex> ArtNet.Decoder.bit_field(<<0b00110, 0b0001>>, ArtNet.Packet.BitField.TalkToMe)
{:ok,
  {%ArtNet.Packet.BitField.TalkToMe{
      reply_on_change: true,
      diagnostics: true,
      diag_unicast: false,
      vlc: false
    }, <<0x01>>}}

@spec decode(binary(), ArtNet.Packet.Schema.format(), Keyword.t()) ::
  {:ok, {any(), binary()}} | :error

Decodes one value from data using a schema field format.

The format argument is one of the formats documented in ArtNet.Packet.Schema. For list formats, opts[:length] may limit the number of decoded elements.

@spec decode_list(binary(), ArtNet.Packet.Schema.format(), Keyword.t()) ::
  {:ok, {list(), binary()}} | :error

Decodes a list of values from a binary.

• data is the binary to decode the values from.
• format is the format of the values.
• opts is a keyword of format options.
  • length is the number of values to decode. If nil, all values are decoded until the binary is exhausted.

The function returns {:ok, {list, binary}} if the values were successfully decoded. The list is the decoded list of values and binary is the remaining binary.

If the values could not be decoded, the function returns :error.

Examples

iex> ArtNet.Decoder.decode_list(<<1, 2, 3>>, {:integer, 8}, [])
{:ok, {[1, 2, 3], <<>>}}

iex> ArtNet.Decoder.decode_list(<<1, 2, 3>>, {:integer, 16}, [])
:error

iex> ArtNet.Decoder.decode_list(<<0, 1, 1, 1>>, {:integer, 16}, [])
{:ok, {[1, 0x0101], <<>>}}

iex> ArtNet.Decoder.decode_list(<<0, 1, 1>>, {:integer, 8}, [length: 2])
{:ok, {[0, 1], <<1>>}}

@spec enum_table(binary(), module()) :: {:ok, {atom(), binary()}} | :error

Decodes an enum table value from a binary.

• data is the binary to enumerate the table from.
• module is the module that defines the enum.

The function returns {:ok, {atom, rest}} if the table was successfully enumerated. The atom is the enumerated atom and rest is the remaining binary.

If the table could not be enumerated, the function returns :error.

Examples

iex> ArtNet.Decoder.enum_table(<<0x00, 0x00>>, ArtNet.Packet.EnumTable.Priority)
{:ok, {:dp_all, <<0x00>>}}

iex> ArtNet.Decoder.enum_table(<<0x80, 0x10>>, ArtNet.Packet.EnumTable.Priority)
{:ok, {:dp_high, <<0x10>>}}

iex> ArtNet.Decoder.enum_table(<<0x01, 0x00>>, ArtNet.Packet.EnumTable.Priority)
:error

@spec integer(binary(), pos_integer()) ::
  {:ok, {non_neg_integer(), binary()}} | :error

Extracts an integer value from a binary.

• data is the binary to extract the integer from.
• size is the size of the integer in bits.

The function returns {:ok, {value, rest}} if the integer was successfully extracted. The value is the extracted integer and rest is the remaining binary.

If the integer could not be extracted, the function returns :error.

Examples

iex> ArtNet.Decoder.integer(<<1, 2, 3, 4>>, 16)
{:ok, {0x0102, <<3, 4>>}}

iex> ArtNet.Decoder.integer(<<1, 2, 3, 4>>, 32)
{:ok, {0x01020304, <<>>}}

iex> ArtNet.Decoder.integer(<<1, 2, 3, 4>>, 5)
:error

iex> ArtNet.Decoder.integer(<<1, 2, 3>>, 32)
:error

@spec little_integer(binary(), pos_integer()) ::
  {:ok, {non_neg_integer(), binary()}} | :error

Extracts a little-endian integer value from a binary.

The value is read as an unsigned integer.

Examples

iex> ArtNet.Decoder.little_integer(<<1, 2, 3, 4>>, 16)
{:ok, {0x0201, <<3, 4>>}}

iex> ArtNet.Decoder.little_integer(<<1, 2, 3, 4>>, 32)
{:ok, {0x04030201, <<>>}}

iex> ArtNet.Decoder.little_integer(<<1, 2, 3, 4>>, 5)
:error

iex> ArtNet.Decoder.little_integer(<<1, 2, 3>>, 32)
:error

@spec string(binary(), pos_integer() | nil) :: {:ok, {String.t(), binary()}} | :error

Extracts a string value from a binary.

• data is the binary to extract the string from.
• size is the size of the string in bytes. If nil, the entire binary is extracted.

The function returns {:ok, {value, rest}} if the string was successfully extracted. The value is the extracted string and rest is the remaining binary.

The function trims trailing null bytes from the string.

Examples

iex> ArtNet.Decoder.string(<<65, 66, 67, 0, 0>>, nil)
{:ok, {"ABC", <<>>}}

iex> ArtNet.Decoder.string(<<65, 66, 67, 0, 0>>, 2)
{:ok, {"AB", <<67, 0, 0>>}}

iex> ArtNet.Decoder.string(<<65, 66, 67, 0, 0>>, 4)
{:ok, {"ABC", <<0>>}}

iex> ArtNet.Decoder.string(<<65, 66, 0, 67, 0, 0>>, 5)
{:ok, {"ABC", <<0>>}}

iex> ArtNet.Decoder.string(<<65, 66, 67, 255, 0>>, 4)
{:ok, {<<65, 66, 67, 255>>, <<0>>}}

iex ArtNet.Decoder.string(<<65, 66, 67, 0, 0>>, 6)
:error