Mah
DocsStdlibBlogChangelog
GitHub
Menu
DocsStdlibBlogChangelog GitHub

  • std:math
  • std:random
  • std:collections
  • std:time

  • std:path
  • std:json
  • std:csv
  • std:regex
  • std:bytes
  • std:url

  • std:async
  • std:fs
  • std:process
  • std:thread

  • std:socket
  • std:http

  • std:reflect
  • std:test

Standard library / Text & data

std:bytes

Constructors and decoders for Bytes, Mah’s binary data type: a growable sequence of byte values (whole Numbers 0 to 255). Bytes are what binary files (std:fs), sockets (std:socket) and HTTP bodies (std:http) read and write.

import bytes from "std:bytes"

let header = bytes.from_hex("89504e47")        # PNG magic number
let blank = bytes.new(4)                       # four zero bytes
let packet = bytes.concat([header, blank])
print(packet, packet.len())                    # Bytes[89 50 4e 47 00 00 00 00] 8

The Bytes type itself is built in: its methods (to_hex(), to_base64(), to_text(), push, slicing, …) need no import. This module only adds ways to make one. The type is covered in full under Collections; here’s the short version.

Bytes in brief

let b = "hi".to_bytes()                  # a String's UTF-8 encoding
print(b, b[0], b.len())                  # Bytes[68 69] 104 2
b.push(33)
b[0] = 72
print(b.to_text(), b.to_hex(), b.to_base64())   # some(Hi!) 486921 SGkh
print(b[1..], b == "Hi!".to_bytes())     # Bytes[69 21] true
  • Indexed and sliced like a Vector (b[i] is a Number; a slice is a new Bytes), mutable, passed by reference.
  • == compares contents (unlike Vectors). a + b concatenates.
  • to_text() is some(String) only if the bytes are valid UTF-8; to_text_lossy() always gives a String, replacing invalid sequences with U+FFFD.

Making Bytes

import bytes from "std:bytes"

print(bytes.new(3, 255))                  # Bytes[ff ff ff]
print(bytes.from_vector([1, 2, 254]))     # Bytes[01 02 fe]
print(bytes.from_hex("CAFE"), bytes.from_base64("SGkh").to_text())   # Bytes[ca fe] some(Hi!)

Decoding untrusted text

from_hex and from_base64 throw bytes.BytesError for malformed input, so wrap them when the text comes from outside:

import bytes from "std:bytes"

fn decode(s: String) -> Bytes {
    try {
        return bytes.from_base64(s)
    } catch {
        e: bytes.BytesError => {
            print(e.kind)                     # invalid_base64
            return bytes.new()
        }
    }
}
print(decode("SGkh").to_text_lossy())         # Hi!
print(decode("not base64!").len())            # 0

A bad byte value or size passed to new, from_vector, push or b[i] = n (say, 300) is a programming mistake, so it’s a runtime error rather than a BytesError.

Example: a checksum

Bytes iterate over their Numbers, so ordinary loops and reduce work:

fn checksum(data: Bytes) -> Number {
    let sum = 0
    for let x in data { sum = (sum + x) % 256 }
    sum
}
print(checksum("hello".to_bytes()))      # 20

Reference

Function
new(size = 0, fill = 0)size bytes, each fill
from_vector(items)from a Vector of Numbers 0 to 255
from_hex(text)an even number of hex digits, either case
from_base64(text)standard alphabet, = padded, no whitespace
concat(parts)a Vector of Bytes joined into one new Bytes
Bytes method
len()the number of bytes
push(n), pop()append a byte / remove the last (none if empty)
extend(other)append another Bytes
copy()a new Bytes with the same contents
index_of(needle)some(i) of the first occurrence of a Bytes, or none
to_vector()a Vector of Numbers
to_text(), to_text_lossy()as UTF-8: Option<String> / String
to_hex(), to_base64()lowercase hex / padded standard base64

bytes.BytesError { kind, description } has kind "invalid_hex" or "invalid_base64". Programs using Bytes need bytecode 1.17.

Previous std:regex Next std:url

Mah — ماه, "moon" in Persian. Built from scratch, pure Python (plus a Rust runtime).

Docs Stdlib Blog Changelog RSS GitHub