Erlang Binaries Cheat Sheet

A Programming › Nope cheat sheet in English by Fylke

Summarizing the syntax for handling binary data in Erlang.

14,961 views 2,705 downloads 25 Sep 2019 History

PRs

3.7 avg · 0 ratings

Overview

Erlang can match binaries just as any list of things. <<E1, E2, E3>> = Bin divides the binary Bin into three elements of type integer of one byte each. This means that Bin has to be 24 bits long, or we get a badmatch. You can also make partial matches, in a [Head | Tail] fashion, by putting /bitstring on the last element, like so: <<E1, E2, E3/bitstring>> = Bin. This is a type modifier and tells Erlang that there are two 8-bit elements, in E1 and E2 respectively, and then an undetermined amount of bits stored in E3.

Type Modifiers

Type	Size in bits	Remarks
`integer`	As many as it takes	Default size is 8 bits
`float`	64\|32\|16	Need to specify length if other than default: `<<A:16/float>>`
`binary\|bytes`	8 per chunk	Anything matched must be of size evenly divisible by 8 (this is default)
`bitstring\|bits`	1 per chunk	Will always match, use as Tail for a list
`utf8\|utf16\|utf32`	8-32, 16-32, and 32	`<<"abc"/utf8>>` is the same as `<<$a/utf8, $b/utf8, $c/utf8>>`
`signed\|unsigned`	N/A	Default is unsigned
`big\|little\|native`	N/A	Endianness - `native` is resolved at load time to whatever the CPU uses
`unit:IntLiteral`	N/A	Define a custom unit of length 1..256

Examples

Expression	Result
`<<97, 98, 99>>`	`<<"abc">>` (turn off with `shell:strings(false)`)
`<<A:2/unit:6, B:1/unit:4>> = <<7, 42>>`	`A = 114` `B = 10`
`<<A:16/float>> = <<1, 17>>`	`1.627206802368164e-5`
`<<A/signed>> = <<255>>`	`-1`
`<<A:16/big>> = <<255, 0>>`	`65280`
`<<A:16/little>> = <<255, 0>>`	`255`
`<<"pöpcörn"/utf8>>`	How Erlang handles unicode

When constructing a binary, if the size of an integer N is too large to fit inside the given segment, the most significant bits are silently discarded and only the N least significant bits kept.

Segments

Each segment in a binary has the following general syntax: Value:Size/TypeSpecifierList. The Size and TypeSpecifier can be omitted.

Value is either a literal or a variable, Size is multiplied by the unit in TypeSpecifierList, and can be any expression that evaluates to an integer¹. Think of 'Size' as the number of items of the type in the 'TypeSpecifierList'

Contrived example: <<X:4/little-signed-integer-unit:8>> has a total size of 4*8 = 32 bits, and it contains a signed integer in little endian byte order.

¹ Mostly true, see Bit Syntax Expressions in Erlang documentation for complete picture.

Binary Comprehension Example

Just like with lists, there is a notation for binary comprehension. Below is an example of how to use this to convert a 32 bit integer into a hex representation:

int_as_hex(Int) ->
    IntAsBin = <<Int:32>>,
    "0x" ++ lists:flatten([byte_to_hex(<<Byte>>) || <<Byte:8>> <= IntAsBin]).

byte_to_hex(<<Nibble1:4, Nibble2:4>>) ->
    [integer_to_list(Nibble1, 16), integer_to_list(Nibble2, 16))].

You can mix list- and binary comprehension: if the generator is a list, use <-, if it's a binary, use <=. If you want the result to be a binary, use <<>>, if you want a list, use [] around the expression.

Troubleshooting

Use the Erlang shell to trial and error you way to a correct expression. A useful tool for understanding why your binaries are badmatching is bit_size:
bit_size(<<1/integer>>). => 8 bit_size(<<<<1:1, 0:1>>/bitstring>>). => 2
bit_size(<<1.0/float>>). => 64 bit_size(<<<<1, 2>>/binary>>). => 16
A related one is byte_size:
MinBytesToEncodeNumber = byte_size(binary:encode_unsigned(Number)).

Badges

Nice Cheat Sheet

Comments

No comments yet.