Binary v0.0.4 Binary

Functions to operate on binaries.

Wrappers of erlang’s :binary, functions that try to mimic String behaviour but on bytes, and some very simple functions that are here just to make piping operations on binaries easier.

Summary

Functions

Append binary or a byte to another binary

Returns byte at given position. Numbering starts with 0

Create a binary with the binary content repeated n times

Drops first N bytes from the binary

Returns the first byte of the binary as an integer

Returns binary from the hex representation

Returns binary representation of the provided integer. Second option decides endianness which defaults to :big

Convert list of bytes into binary

Returns the last byte of the binary as an integer

Returns the length of the longest common prefix in the provided list of binaries

Returns the length of the longest common prefix in the provided list of binaries

Pad with the provided byte at the beginning of the binary until provided length is achieved

Pad end of the binary with the provided byte until provided length is achieved

Exctracts part of the binarty starting at given position with given length

Prepend binary or a byte to another binary

Replace binary pattern inside the binary with the replacement

Reverse bytes order in the binary

Split binary into list of binaries based on pattern

Splits a binary into two at the specified position. Returns a tuple

Takes the first N bytes from the binary

Returns hex representation of the provided binary

Interpret binary as an unsigned integer representation. Second option decides endianness which defaults to :big

Converts binary to a list of bytes

Removes all spcefied leading bytes from the binary

Removes all specified trailing bytes from the the binary

Functions

append(left, right)
append(binary, binary | byte) :: binary

Append binary or a byte to another binary.

Handy for pipping. With binary argument it’s exactly the same as Kernel.<>/2

at(binary, postion)
at(binary, integer) :: byte

Returns byte at given position. Numbering starts with 0.

Position can be negative to make it relative to the end of the binary.

Returns nil if position is outside the binary (following Enum and String behavior)

Examples

iex> <<1, 2, 3>> |> Binary.at(1)
2
iex> <<1, 2, 3>> |> Binary.at(3)
nil
iex> <<1, 2, 3>> |> Binary.at(-1)
3
copy(bin, n)
copy(binary, non_neg_integer) :: binary

Create a binary with the binary content repeated n times.

drop(binary, count)
drop(binary, integer) :: binary

Drops first N bytes from the binary.

If provided count is negative, it drops N bytes from the end. In case where count > byte_size, it will return <<>>

first(bin)
first(binary) :: byte

Returns the first byte of the binary as an integer.

from_hex(binary)
from_hex(binary) :: binary

Returns binary from the hex representation.

iex> "ff01" |> Binary.from_hex
<<255, 1>>

Just a shorthand for:

Base.decode16!(binary, case: :mixed)
from_integer(int, endianness \\ :big)
from_integer(non_neg_integer, :big | :little) :: binary

Returns binary representation of the provided integer. Second option decides endianness which defaults to :big.

Uses :binary.encode_unsigned/1

Examples

iex> 1234 |> Binary.from_integer
<<4, 210>>
iex> 1234 |> Binary.from_integer(:little)
<<210, 4>>
from_list(list)
from_list(list) :: binary

Convert list of bytes into binary.

last(bin)
last(binary) :: byte

Returns the last byte of the binary as an integer.

longest_common_prefix(binaries)
longest_common_prefix([binary]) :: non_neg_integer

Returns the length of the longest common prefix in the provided list of binaries.

Uses :binary.longest_common_prefix/1

iex> ["moo", "monad", "mojo"] |> Binary.longest_common_prefix
2
longest_common_suffix(binaries)
longest_common_suffix([binary]) :: non_neg_integer

Returns the length of the longest common prefix in the provided list of binaries

Uses :binary.longest_common_suffix/1

pad_leading(binary, len, byte \\ 0)
pad_leading(binary, non_neg_integer, byte) :: binary

Pad with the provided byte at the beginning of the binary until provided length is achieved.

pad_trailing(binary, len, byte \\ 0)
pad_trailing(binary, non_neg_integer, byte) :: binary

Pad end of the binary with the provided byte until provided length is achieved.

Examples

iex> <<3, 7>> |> Binary.pad_trailing(5)
<<3, 7, 0, 0, 0>>
part(binary, position, len)

Exctracts part of the binarty starting at given position with given length.

Based on Kernel.binary_part/3, but:

  • it also accepts negative position, interpreting it as position relative to the end of the binary.
  • length is allowed to be outside binary size i.e. it is max number of fetched bytes

Examples

iex> x = <<1, 2, 3, 4, 5>>
<<1, 2, 3, 4, 5>>
iex> x |> Binary.part(1, 2)
<<2, 3>>
iex> x |> Binary.part(-2, 1)
<<4>>
iex> x |> Binary.part(-2, -1)
<<3>>
iex> x |> Binary.part(-1, 10)
<<5>>
prepend(left, right)
prepend(binary, binary | byte) :: binary

Prepend binary or a byte to another binary.

replace(binary, pattern, replacement, opts \\ [])
replace(binary, binary, binary, Keyword.t) :: binary

Replace binary pattern inside the binary with the replacement.

For readability examples are presented on strings, but do note we are operating on bytes, not codepoints.

iex> "a-b-c" |> Binary.replace("-", "..")
"a..b..c"

By default it replaces all occurrences. If you only want to replace the first occurence,

iex> "a-b-c" |> Binary.replace("-", "..", global: false)
"a..b-c"
reverse(binary)
reverse(binary) :: binary

Reverse bytes order in the binary.

split(binary, pattern, opts \\ [])
split(binary, binary | byte, Keyword.t) :: [binary]

Split binary into list of binaries based on pattern.

pattern can be a binary, or a byte.

It mimics erlang’s :binary.split/3split behavior rather than String.split/3, and only splits once by default.

global: true option can be provided to split on all occurences.

iex> <<1, 2, 3, 2, 3>> |> Binary.split(<<3, 2>>)
[<<1, 2>>, <<3>>]
iex> <<1, 2, 3, 2, 3>> |> Binary.split(2)
[<<1>>, <<3, 2, 3>>]
iex> <<1, 2, 3, 2, 3>> |> Binary.split(2, global: true)
[<<1>>, <<3>>, <<3>>]
split_at(binary, position)
split_at(binary, integer) :: byte

Splits a binary into two at the specified position. Returns a tuple.

When position is negative it’s counted from the end of the binary.

Examples

iex> <<1, 2, 3>> |> Binary.split_at(1)
{<<1>>, <<2, 3>>}
iex> <<1, 2, 3, 4>> |> Binary.split_at(-1)
{<<1, 2, 3>>, <<4>>}
iex> <<1, 2, 3>> |> Binary.split_at(10)
{<<1, 2, 3>>, <<>>}
take(binary, count)
take(binary, integer) :: binary

Takes the first N bytes from the binary.

When negative count is given, last N bytes are returned. In case when count > byte_size, it will return the full binary.

to_hex(binary)
to_hex(binary) :: binary

Returns hex representation of the provided binary.

iex> <<190,239>> |> Binary.to_hex
"beef"

Just a shorthand for:

Base.encode16(binary, case: :lower)
to_integer(binary, endianness \\ :big)
to_integer(binary, :big | :little) :: non_neg_integer

Interpret binary as an unsigned integer representation. Second option decides endianness which defaults to :big.

Uses :binary.decode_unsigned/1

Examples

iex> <<1, 2>> |> Binary.to_integer
258
iex> <<1, 2>> |> Binary.to_integer(:little)
513
to_list(bin)
to_list(binary) :: list

Converts binary to a list of bytes.

trim_leading(binary, byte \\ 0)
trim_leading(binary, byte) :: binary

Removes all spcefied leading bytes from the binary.

trim_trailing(binary, byte \\ 0)
trim_trailing(binary, byte) :: binary

Removes all specified trailing bytes from the the binary.

Examples

iex> <<0, 1, 2, 0, 0>> |> Binary.trim_trailing
<<0, 1, 2>>
iex> <<1, 2>> |> Binary.trim_trailing(2)
<<1>>