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.
Exports
Section titled “Exports”struct Bits
Section titled “struct 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\""
Bits.parse
Section titled “Bits.parse”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
Bits.matches
Section titled “Bits.matches”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)
Bits.field
Section titled “Bits.field”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)
Bits.width
Section titled “Bits.width”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
Bits.mask
Section titled “Bits.mask”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
Bits.value
Section titled “Bits.value”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
Bits.from_fragments
Section titled “Bits.from_fragments”impl Literal for Bits
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Bits, Error>
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.
Bits.inspect
Section titled “Bits.inspect”impl Debug for Bits
fn inspect(pattern: Bits) -> String
impl Debug.inspect
The typed literal that builds the pattern, as written.
Bits.equal
Section titled “Bits.equal”impl Equatable for Bits
fn equal(a: Bits, b: Bits) -> Bool
impl Equatable.equal
type FieldBits
Section titled “type FieldBits”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
FieldBits.try_from
Section titled “FieldBits.try_from”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
Section titled “enum Error”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
-
EmptyThe pattern has no bits: it is empty or only
_. -
CharacterThe character at
indexis none of0,1,x,_or a lowercase letter. -
SecondFieldThe letter at
indexnames a second field; a pattern has one. -
SplitFieldThe field letter at
indexcomes after other bits that follow the field’s first bits: a field’s bits are written together.
Error.to_string
Section titled “Error.to_string”impl Display for Error
fn to_string(e: Error) -> String
impl Display.to_string
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal