Binary matching
A match can destructure strings, binaries, and bitstrings directly.
Like in Erlang’s bit syntax, binaries are matched in segments. A binary pattern only matches if every segment matches, and the whole value is consumed.
pub fn main() {
let payload = <<1, 17, 42, 99>>;
match payload {
<<prefix: int(16), tag: int(8), rest @ ..>> =>
println!("prefix = {}, tag = {}, rest = {:?}", prefix, tag, rest),
_ => println!("did not match"),
}
}
Like all match patterns, binary patterns can bind values to names, ignore parts with _, and be
combined with guards when you need extra checks after destructuring.
Segments
There can be zero or more segments in a binary match arm. Each segment can have a type
annotation describing how it is matched. An example segment is of the form
var: int(size=^x, signed, little, unit=8), where:
-
the segment’s type follows a colon: one of
int,float,char,str,binorbits -
sizecan be 0 or more, and can be given through a pinned variable, likesize=^x- including a variable bound by a previous segment of the pattern -
unithas to be a constant in range1..=256 -
all parameters are optional
sizeandunitdefault to:- for
ints,unit=1, size=8 - for
floats,unit=1, size=64; if set,sizemust be a literal16,32or64 - for
bits,unit=1;sizeexpands to consume the whole unclaimed space - for
bins,unit=8and must be a multiple of8;sizeexpands as above - for
str,unit=8and cannot be set;sizeexpands as above - for
chars, neither can be set: the size depends on the character and its encoding
- for
- signedness is
unsignedby default (can besignedorunsigned) - endianness is
bigby default (can bebig,little, ornative) - the encoding of a
charisutf8by default (can beutf8,utf16, orutf32); endianness only applies toutf16andutf32 - a string literal can be encoded the same way, e.g.
"łącko": str(utf16, little); otherstrvalues are always UTF-8
-
the
size=prefix is optional;int(size=64)is more commonly written asint(64) -
only the last segment can be unsized, and
unitspecifies its granularity, e.g.rest: bits(unit=4)matches a rest whose size is a multiple of 4 bits- most of the time, you’ll match the rest with
rest @ ..instead
- most of the time, you’ll match the rest with
-
there are no alignment rules: segments of any size can follow each other
Short form
If the only parameter you want to set is a fixed size, you can use a shortform syntax x:16,
with an integer literal. For matched variables, the type defaults to int.
When the size is provided by a variable, it needs the full form, e.g. x: int(^len).
// For matched variables, the type is assumed to be `int`.
// This line is equivalent to `<<x: int(16)>>`.
if let <<x:16>> = data {
println!("data is a two-byte integer {}", x);
}
// The shorthand syntax comes in handy to match data with standard layout.
if let <<unix_ts_ms:48, ver:4, rand_a:12, var:2, rand_b:62>> = uuidv7_id {
println!("{} {} {} {} {}", unix_ts_ms, ver, rand_a, var, rand_b);
}
If the type is omitted altogether, the size defaults to 8 as per the list above.
In that case <<x>> is equivalent to <<x: int()>> is equivalent to <<x: int(8)>>.
The rest
The last segment of the matched binary can be rest @ .. (which binds whatever is left
of the value), or just .. (which ignores it). The rest needs no type annotation;
it gets the narrowest type it is guaranteed to have:
- a
str, when matching astr, and every segment before it is valid UTF-8 - a
bin, when matching astror abinand the segments before it add up to whole bytes - a
bitsotherwise
An explicit type can still be given. On a bits, rest: bin() acts as an additional check
and only matches when the rest is a whole number of bytes.
Example
pub fn main() {
let bin = <<16, 5, 6, 7>>;
match bin {
// Bind `len`, then use it as the size of `payload`
<<kind:8, len: int(8), payload: bin(^len), rest @ ..>> =>
println!("kind = {}, payload = {:?}, rest = {:?}", kind, payload, rest),
// The size can also be a guard expression
<<kind:8, len: int(8), payload: bin(len / 2), rest @ ..>> =>
println!("kind = {}, payload = {:?}, rest = {:?}", kind, payload, rest),
_ => println!("invalid packet"),
}
let packet: bits = <<3:4, 5:4, 7:3>>;
match packet {
// The tail expands to match the whole rest of the binary.
// Only the last segment can be unsized.
// After an 8-bit header, the rest of a `bits` is a `bits`.
<<header: int(8), tail @ ..>> =>
println!("header = {}, tail = {:?}", header, tail),
_ => println!("did not match"),
}
}
Literals
Literal segments can also be mixed directly into a binary pattern, whatever kind of value you are
matching. str and b"…" literals match their bytes, char literals are encoded as UTF-8 (unless
overridden), and integer and float literals are matched like int and float segments.
A literal that doesn’t fit its segment, like 256:8, can never match, and gets a compiler warning.
pub fn main() {
let text: str = "Patina!";
let bytes: bin = <<b"PNG", '!', "rest">>;
// For literals, types are optional unless you want to override a default.
// Like with bindings, you set the type after a colon.
let packet: bits = <<b"PT", '!', "ok", 5: int(3)>>;
match text {
// Every segment before the rest is valid UTF-8, so `rest` is a `str`.
<<"Pa", 't', rest @ ..>> => println!("text rest {:?}", rest),
_ => println!("unknown text"),
}
match bytes {
<<b"PNG", '!', rest @ ..>> => println!("png data {:?}", rest),
_ => println!("unknown binary"),
}
match packet {
// The shorthand form can also be used with literals.
<<b"PT", '!', "ok", 5:3, rest @ ..>> =>
println!("packet tail {:?}", rest),
_ => println!("unknown packet"),
}
}
Bound variables
You can match against already bound variables’ values using the pin operator ^.
pub fn main() {
let png_prefix = "PNG";
let jpg_prefix = "JPG";
match "PNG!rest" {
<<^png_prefix, rest @ ..>> => println!("png data {:?}", rest),
<<^jpg_prefix, rest @ ..>> => println!("jpg data {:?}", rest),
_ => println!("unknown data"),
}
let bit_prefix = 7;
match <<119>> {
// Like with literals, you can give the segment a type.
<<^bit_prefix: int(16, little), rest @ ..>> => println!("expected {:?}", rest),
// Or use the shorthand syntax.
<<^bit_prefix:4, rest @ ..>> => println!("expected {:?}", rest),
_ => println!("unexpected prefix"),
}
}
Building binaries
The same syntax as above can be used to build the binaries. Each segment is an expression, with an optional type and spec. Without one, the type of the segment is determined by the type of its value:
ints become 8-bit integersfloats become 64-bit floatschars andstrs are encoded as UTF-8binandbitsare copied whole
Arithmetic in a segment needs parentheses, like (len + 1):16.
A built binary gets the narrowest type it is guaranteed to have:
strif every segment is valid UTF-8 on its ownbinif its size is a whole number of bytesbitsotherwise.
pub fn main() {
let name = "Patina";
let version = 3;
// Every segment is valid UTF-8, so this is a `str`.
let greeting: str = <<"Hello, ", name, '!'>>;
// The size is a whole number of bytes, so this is a `bin`.
let header: bin = <<b"PT", version:16, 1.5: float(32), 'é': char(utf16)>>;
// Anything else is a `bits`.
let flags: bits = <<1:1, 0:1, (version + 1): int(3)>>;
println!("{:?} {:?} {:?}", greeting, header, flags);
}
See also:
match, Guards, and Primitives