8. Bit arrays

8.1 GrammarCopy Anchor Link

BitArray        = "<<" [ Segment { "," Segment } [ "," ] ] ">>" .
BitArrayPattern = "<<" [ PatSegment { "," PatSegment } [ "," ] ] ">>" .
Segment         = Expr [ ":" Format ] .
PatSegment      = Pattern [ ":" Format ] .
Format          = name [ "(" Expr ")" ] .

The format names are fixed words of the bit array syntax. They are not names of values. In a segment, : always starts the format, and the format gives the type, so the pattern of a segment may not be a type test x : T.

8.2 FormatsCopy Anchor Link

• A segment with no format is u8.
• u is unsigned and i is signed (two’s complement). be is big-endian and le is little-endian. An integer format with no ending puts the highest bit first, so u(16) is the same as u16be.
• The expression in brackets has the type Int and may be any expression. A dynamic width is nonnegative; zero is allowed for u(n), i(n), bits(n) and bytes(n). An integer segment of width zero encodes no bits and decodes as integer zero, for both signed and unsigned formats. No sign bit is read in that case.
• Any other format name is a compile error.

8.3 Making bit arraysCopy Anchor Link

<<s1, …, sn>> puts the bits of the segments one after the other:

• For an integer, the lowest N bits of the value are used. Negative numbers use two’s complement.
• A float is rounded to the nearest value of the format. If the result is not finite, the program stops.
• bits(n) takes the first n bits of the value, and bytes(n) the first 8 × n bits. If the value is too short, the program stops. For bytes, if the length of the value is not a multiple of 8, the program stops.
• If a length is negative, the program stops.
• Strings and codepoints are encoded in the given format.

8.4 Matching bit arraysCopy Anchor Link

A bit array pattern matches the segments in order from the start. It matches only when all the bits are used. A negative length or too few remaining bits makes that pattern fail; it does not stop the program. Zero lengths use the format rule of §8.2 and consume no bits. An error or stop while computing a length propagates normally; it is not a failed match. Construction has the separate failure rule of §8.3.

• An integer segment reads N bits, signed or unsigned, and matches them with its pattern.
• A float segment reads its bits. It matches only when they are a finite number.
• bits and bytes with no length take all the bits that are left, so they may only be the last segment. For bytes, the number of bits left must be a multiple of 8.
• A string format in a pattern needs a string literal, which gives the bits to match. A _codepoint format matches one correctly encoded codepoint.
• A length may use names bound by earlier segments of the same pattern.
• If there are not enough bits, the pattern does not match. The program does not stop.