Skip to content

std::bytes

Immutable byte buffers and their Byte element type. Bytes is the FFI boundary for Go []byte; convert to List<Byte> only when Nomi code needs to inspect or transform individual bytes.

Bytes implements Contains<Byte>, Iter<Byte>, Add<Bytes, Bytes>, Summable, Display, Debug, Equatable, Comparable and Hashable. Byte does not implement the arithmetic operators; use Byte.to_int for numeric work, and Int.to_byte (None outside 0 to 255) to come back. It does have the bitwise operators that stay within 8 bits: &&&, |||, ^^^ and ~~~.

Import with import std::bytes.

Types

type Byte

A single byte, 0 through 255. An Int literal written where a Byte is expected is one: b: Byte = 0x81, [0x81, 0x00] as a List<Byte>.

fn to_int(b: Byte) -> NonNegativeInt

type function on Byte

Converts a Byte to its Int value.

b: Byte = 255
assert Byte.to_int(b) == 255

impl Display for Byte

fn to_string(b: Byte) -> String

impl Display.to_string

The byte’s value in decimal digits.

b: Byte = 200
assert Display.to_string(b) == "200"

impl Debug for Byte

fn inspect(b: Byte) -> String

impl Debug.inspect

The same digits as Display.

b: Byte = 200
assert Debug.inspect(b) == "200"

impl Equatable for Byte

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

impl Equatable.equal

impl Hashable for Byte

fn hash(b: Byte) -> Int

impl Hashable.hash

impl BitwiseAnd<Byte, Byte> for Byte

fn bitwise_and(lhs: Byte, rhs: Byte) -> Byte

impl BitwiseAnd.bitwise_and

Bitwise and, a &&& b.

a: Byte = 0b1100
b: Byte = 0b1010
assert a &&& b == 0b1000

impl BitwiseOr<Byte, Byte> for Byte

fn bitwise_or(lhs: Byte, rhs: Byte) -> Byte

impl BitwiseOr.bitwise_or

Bitwise or, a ||| b.

a: Byte = 0b1100
b: Byte = 0b1010
assert a ||| b == 0b1110

impl BitwiseXor<Byte, Byte> for Byte

fn bitwise_xor(lhs: Byte, rhs: Byte) -> Byte

impl BitwiseXor.bitwise_xor

Bitwise exclusive or, a ^^^ b.

a: Byte = 0b1100
b: Byte = 0b1010
assert a ^^^ b == 0b0110

impl BitwiseNot<Byte> for Byte

fn bitwise_not(value: Byte) -> Byte

impl BitwiseNot.bitwise_not

Bitwise not, ~~~b: each of the 8 bits flipped, 255 - b.

zero: Byte = 0
high: Byte = 0b1111_0000
assert ~~~zero == 255
assert ~~~high == 0b0000_1111
type Bytes

Immutable byte buffer.

fn length(data: Bytes) -> NonNegativeInt

type function on Bytes

Number of bytes in the buffer.

assert Bytes.length(Bytes.from_list([97, 98])) == 2
fn get(data: Bytes, index: Int) -> Maybe<Byte>

type function on Bytes

Returns the byte at zero-based index, or None when the index is outside the buffer. For an index that must exist, Bytes.get(data, index)! returns the byte and traps on any other index.

a: Byte = 97
b: Byte = 98
data = Bytes.from_list([a, b])
assert data |> Bytes.get(0) |> Maybe.map(Byte.to_int) == Some(97)
assert Bytes.get(data, 2) == None
assert data |> Bytes.get(1)! |> Byte.to_int() == 98
fn slice(data: Bytes, start: Int, stop: Int) -> Bytes

type function on Bytes

Returns the bytes from index start up to, not including, stop. An index outside the buffer is clamped to it, and a stop at or before start gives the empty buffer.

a: Byte = 97
b: Byte = 98
c: Byte = 99
d: Byte = 100
assert Bytes.slice(Bytes.from_list([a, b, c, d]), 1, 3) == Bytes.from_list([b, c])
assert Bytes.slice(Bytes.from_list([a, b]), 1, 99) == Bytes.from_list([b])
assert Bytes.slice(Bytes.from_list([a, b]), 1, 0) == Bytes.from_list([])
fn concat(a: Bytes, b: Bytes) -> Bytes

type function on Bytes

Concatenates two byte buffers.

a: Byte = 97
b: Byte = 98
c: Byte = 99
d: Byte = 100

assert Bytes.concat(Bytes.from_list([a, b]), Bytes.from_list([c, d]))
    == Bytes.from_list([a, b, c, d])
fn to_list(data: Bytes) -> List<Byte>

type function on Bytes

Materializes a byte buffer as a list of Byte values.

a: Byte = 97
b: Byte = 98

assert Bytes.from_list([a, b])
|> Bytes.to_list()
|> Iter.map(Byte.to_int)
|> Iter.to_list() == [97, 98]
fn from_list(items: List<Byte>) -> Bytes

type function on Bytes

Builds a byte buffer from a list of Byte values.

a: Byte = 97
b: Byte = 98
assert Bytes.from_list([a, b]) |> Bytes.to_list() == [a, b]
fn to_string(data: Bytes) -> Result<String, String>

type function on Bytes

Decodes bytes as UTF-8 text, or Err("invalid UTF-8") when they are not UTF-8.

assert Bytes.from_list([104, 195, 169]) |> Bytes.to_string() == Ok("hé")
assert Bytes.from_list([255]) |> Bytes.to_string() == Result.Err("invalid UTF-8")

impl Iter for Bytes

fn each_while(data: Bytes, yield: (Byte) -> Bool) -> Bool

impl Iter.each_while

Pushes each byte to yield, stopping when it returns False.

a: Byte = 97
b: Byte = 98

assert Bytes.from_list([a, b])
|> Iter.map(Byte.to_int)
|> Iter.to_list() == [97, 98]

impl Contains for Bytes

fn contains(c: Bytes, x: Byte) -> Bool

impl Contains.contains

True if a byte of the buffer equals x, by a linear scan.

a: Byte = 97
b: Byte = 98
z: Byte = 122
assert Bytes.contains(Bytes.from_list([a, b]), b)
refute Bytes.contains(Bytes.from_list([a, b]), z)
refute Bytes.contains(Bytes.from_list([]), a)

impl Add<Bytes, Bytes> for Bytes

fn add(lhs: Bytes, rhs: Bytes) -> Bytes

impl Add.add

Concatenates two byte buffers.

a: Byte = 97
b: Byte = 98
c: Byte = 99
d: Byte = 100
assert Bytes.from_list([a, b]) + Bytes.from_list([c, d]) == Bytes.from_list([a, b, c, d])

impl Summable for Bytes

fn empty_sum() -> Bytes

impl Summable.empty_sum

The sum of no byte buffers: the empty buffer. Summing Bytes concatenates them in order.

assert Bytes.length(Bytes.empty_sum()) == 0
a: Byte = 97
b: Byte = 98
assert Bytes.from_list([a]) + Bytes.empty_sum() == Bytes.from_list([a])
assert Iter.sum([Bytes.from_list([a]), Bytes.from_list([b])]) == Bytes.from_list([a, b])

impl Display for Bytes

fn to_string(data: Bytes) -> String

impl Display.to_string

The buffer’s length, as Bytes(2). Debug shows the bytes.

a: Byte = 97
b: Byte = 98
assert Display.to_string(Bytes.from_list([a, b])) == "Bytes(2)"

impl Debug for Bytes

fn inspect(data: Bytes) -> String

impl Debug.inspect

The bytes in decimal digits between << and >>.

a: Byte = 97
b: Byte = 98
assert Debug.inspect(Bytes.from_list([a, b])) == "<<97, 98>>"
assert Debug.inspect(Bytes.from_list([])) == "<<>>"

impl Equatable for Bytes

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

impl Equatable.equal

impl Comparable for Bytes

fn compare(a: Bytes, b: Bytes) -> Ordering

impl Comparable.compare

Orders octet by octet; a prefix sorts first. A collator’s sort keys (Collator.sort_key) compare this way.

a: Byte = 97
b: Byte = 98
assert Bytes.from_list([a, b]) < Bytes.from_list([b])
assert Bytes.from_list([a]) < Bytes.from_list([a, b])

impl Hashable for Bytes

fn hash(data: Bytes) -> Int

impl Hashable.hash

FNV-1a 64-bit hash of the octets, reinterpreted as an Int, as String’s is. Stable within one runtime process.

a: Byte = 97
assert Hashable.hash(Bytes.from_list([a])) == Hashable.hash(Bytes.from_list([a]))