Skip to content

std::bits

Bit patterns: Bits"10xx_xxxx" matches the Ints whose bits are 1, 0 and then anything, and reads a field out of them. A pattern is written most significant bit first in 0, 1, x (any bit) and one lowercase field letter, with _ between bits to group them. It is a mask and a value: an Int matches when its masked bits are the value’s, so one literal says what n &&& 0b1100_0000 == 0b1000_0000 says in two numbers:

import std::bits.{Bits, FieldBits}

once continuation: FieldBits = Bits"10aa_aaaa"

fn payload(byte: Int) -> Maybe<Int>
    Bits.field(continuation, byte)
end

A pattern has any width, since an Int has any size. Bits takes an Int; a Byte is Byte.to_int(b) first. The literal is checked when the program is checked, so a malformed one is a compile error at the literal, whose text is the Error’s: typed literal Bits"10x2" is invalid: `2` at index 3 is not a bit: ....

Import with import std::bits.

struct Bits

opaque — construction surface is private to its defining module

A bit pattern, built by the typed literal Bits"110x_aaaa": its width in bits, the mask of its 0 and 1 bits, their value, and the bits its field letter covers. Two patterns are equal when they are written alike.

utf8_lead: FieldBits = Bits"110a_aaaa"
assert Bits.matches(utf8_lead, 0b1100_0011)
assert Bits.field(utf8_lead, 0b1100_0011) == Some(3)
assert Debug.inspect(utf8_lead) == "Bits\"110a_aaaa\""
fn parse(text: String) -> Result<Bits, Error>

type function on Bits

Read a bit pattern from its text, as the literal does: Bits"10xx" is Bits.parse("10xx"). Each 0 and 1 is a bit the Int must have, each x a bit it may have either way, and each lowercase letter but x a bit of the pattern’s field, all of whose bits are one letter written together. _ groups bits and is not one.

assert Bits.width(Bits.parse("10xx_xxxx")?) == 8
assert Bits.parse("") == Err(Error.Empty)
assert Bits.parse("10x2") == Err(Error.Character{index: 3, found: "2"})
assert Bits.parse("aabb") == Err(Error.SecondField{index: 2, field: "a", found: "b"})
assert Bits.parse("a0a") == Err(Error.SplitField{index: 2, field: "a"})
assert Bits.parse("aa0a") == Err(Error.SplitField{index: 3, field: "a"})
assert Bits.width(Bits.parse("aa_aa")?) == 4
fn matches(pattern: Bits, n: Int) -> Bool

type function on Bits

Whether n’s bits fit the pattern: every 0 and 1 bit of the pattern is n’s, and n has no bit above the pattern’s width. A negative n, whose bits go on forever, matches no pattern.

lead = Bits"1xxx_xxxx"
assert Bits.matches(lead, 128)
refute Bits.matches(lead, 384)
assert Bits.matches(lead, 0b1000_0001)
refute Bits.matches(lead, 0b0000_0001)
refute Bits.matches(lead, 0b1_1000_0000)
refute Bits.matches(lead, -1)
fn field(pattern: FieldBits, n: Int) -> Maybe<Int>

type function on Bits

The bits of n under the pattern’s field letter, read as a number, when n matches the pattern, and None when it does not. The pattern is a FieldBits, one with a field letter, so Bits.field(Bits"10xx", n) is a compile error.

continuation: FieldBits = Bits"10aa_aaaa"
assert Bits.field(continuation, 0b1010_0011) == Some(0b10_0011)
assert Bits.field(continuation, 0b0010_0011) == None
assert Bits.field(Bits"1aaa_0000", 0b1101_0000) == Some(5)
fn width(pattern: Bits) -> NonNegativeInt

type function on Bits

The number of bits the pattern spells, not counting _.

assert Bits.width(Bits"10_xx") == 4
fn mask(pattern: Bits) -> Int

type function on Bits

The mask of the pattern’s 0 and 1 bits.

assert Bits.mask(Bits"10xx_aa01") == 0b1100_0011
fn value(pattern: Bits) -> Int

type function on Bits

The value the masked bits must have: the pattern’s 1 bits.

assert Bits.value(Bits"10xx_aa01") == 0b1000_0001

impl Literal for Bits

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Bits, Error>

impl Literal.from_fragments

Bits"10xx_xxxx" is the pattern Bits.parse reads from its text. A literal without slots is checked when the program is checked, so a malformed one is a compile error at the literal.

impl Debug for Bits

fn inspect(pattern: Bits) -> String

impl Debug.inspect

The typed literal that builds the pattern, as written.

impl Equatable for Bits

fn equal(a: Bits, b: Bits) -> Bool

impl Equatable.equal

subtype FieldBits Bits when fn pattern -> pattern.field_mask != 0

A bit pattern with a field letter, which Bits.field reads. A Bits"..." literal is checked when the program is compiled, so f: FieldBits = Bits"10xx" is an error; FieldBits.try_from(pattern) checks a pattern built when it runs.

subtype: FieldBits is a subtype of Bits. A literal where a FieldBits is expected is checked when the program is compiled; FieldBits.try_from(...) checks a value when it runs.

f: FieldBits = Bits"110a_aaaa"
assert Bits.field(f, 0b1100_0011) == Some(3)
assert FieldBits.try_from(Bits"10xx") == None
fn try_from(value: Bits) -> Maybe<FieldBits>

type function on FieldBits

Some of the value when it satisfies FieldBits’s rules, None when it does not.

enum Error
    Empty
    Character { index: Int, found: String }
    SecondField { index: Int, field: String, found: String }
    SplitField { index: Int, field: String }
end

Why text is not a bit pattern. index counts characters from 0.

Variants

  • Empty

    The pattern has no bits: it is empty or only _.

  • Character

    The character at index is none of 0, 1, x, _ or a lowercase letter.

  • SecondField

    The letter at index names a second field; a pattern has one.

  • SplitField

    The field letter at index comes after other bits that follow the field’s first bits: a field’s bits are written together.

impl Display for Error

fn to_string(e: Error) -> String

impl Display.to_string

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal