Elixir binary pattern conventions

binary_patterns.md

See the Elixir binary pattern docs

Goals

1. Consistency between code bases
2. Conciseness of patterns

Conventions for integer and float fields

1. All integers are specified with the fields in <endian>-<signed>-<size>-<unit> order
2. Defaults are not specified (big, unsigned, size(8), unit(1))
3. For constant sizes, the size is appended to the end like -4 or -16. No size(4) or size(16)
4. Do not use unit() for constant sizes less than 64-bits. E.g., -32 instead of -4-bytes or -4-unit(8) or -size(4)-unit(8)
5. Do not use computations in bit sizes. E.g., -32 instead of -4*8.
6. When using size(n) for <= 64 bit fields where n is not a constant, stay with the default unit size of 1.
7. When using size(n) for larger bit fields and it's possible to use bytes, specify the size in bytes and append -unit(8). An exception is when working with algorithms that prefer bit sizes like cryptographic ones (SHA-256, AES-512, etc.)
8. Avoid using unit(n) where n is not 8.

Conventions for binary fields

1. When using ASCII strings, do not include any specifiers. If the field is UTF-8, be explicit by appending ::utf8
2. Use n-bytes when matching fixed length binary fields and n is a constant integer.
3. Use binary-size(n) when matching fixed length binary fields and n is a variable.

Rationale

Not using unit/1 for 64-bit integer sizes and less

This is based on it being more common to talk about those sizes in bits rather than bytes. For example, 32-bit integers instead of 4-byte integers. Other programming languages use bits for these sizes as well. E.g., int32_t in C.

Once the number of bits gets to be too large, it's frequently more natural to use bytes. This is allowed, but isn't required due to notable exceptions when working with cryptographic algorithms.