/// Immutable binary data (`Bytes`, a prelude type; ADR 0012). /// /// let data = bytes.from_string("héllo") /// bytes.length(data) // 6 /// bytes.get(data, 0) // Some(104) /// bytes.to_string(bytes.slice(data, 0, 2)) // Error("invalid UTF-8 at byte 1") /// /// Every operation returns new `Bytes` (slices are copies). `==`, `<` and /// `debug` work on `Bytes`. To build `Bytes` from many pieces, append them /// to a `Builder`: appending does not copy what was appended before. /// The empty byte string. pub fn empty :: -> Bytes { from_list [] } /// The number of bytes. @extern c "tl_bytes_length" pub fn length :: b: Bytes -> Int /// The byte (0 to 255) at `index`, if it is in range. pub fn get :: b: Bytes index: Int -> Option { let byte = byte_at b index if byte < 0 { None } else { Some(byte) } } @extern c "tl_bytes_at" fn byte_at :: b: Bytes index: Int -> Int /// The byte (0 to 255) at `index`, or -1 when `index` is out of range: /// `get` without the `Option`, for decoders that check bounds themselves. pub fn read_u8 :: b: Bytes index: Int -> Int { byte_at b index } /// The unsigned big-endian 16-bit integer at `off`, or -1 when /// `off..off + 2` is out of range. Reading allocates nothing. @extern c "tl_bytes_read_u16be" pub fn read_u16be :: b: Bytes off: Int -> Int /// The unsigned big-endian 32-bit integer at `off`, or -1 when /// `off..off + 4` is out of range. Reading allocates nothing. @extern c "tl_bytes_read_u32be" pub fn read_u32be :: b: Bytes off: Int -> Int /// The unsigned big-endian 64-bit integer at `off` (a big integer above /// 2^62), or -1 when `off..off + 8` is out of range. @extern c "tl_bytes_read_u64be" pub fn read_u64be :: b: Bytes off: Int -> Int /// The bytes from `start` up to `end` (excluded). Both are clamped to /// `0..length(b)`; the result is empty when `end <= start`. @extern c "tl_bytes_slice" pub fn slice :: b: Bytes start: Int end: Int -> Bytes /// `a` followed by `b`. @extern c "tl_bytes_concat" pub fn concat :: a: Bytes b: Bytes -> Bytes /// All of `parts`, in order (one copy). @extern c "tl_bytes_concat_all" pub fn concat_all :: parts: List -> Bytes /// The UTF-8 encoding of `s`. @extern c "tl_bytes_from_string" pub fn from_string :: s: String -> Bytes /// The text `b` encodes, or an error naming the first byte that is not /// valid UTF-8. @extern c "tl_bytes_to_string" pub fn to_string :: b: Bytes -> Result /// `to_string` of `slice(b, off, off + len)` without the intermediate /// `Bytes`: the bounds are clamped the same way, and the error names the /// first invalid byte of the range. @extern c "tl_bytes_to_string_range" pub fn to_string_range :: b: Bytes off: Int len: Int -> Result /// The text `b` encodes, with each invalid sequence replaced by U+FFFD. @extern c "tl_bytes_to_string_lossy" pub fn to_string_lossy :: b: Bytes -> String /// Bytes from Ints in `0..=255` (panics on any other Int). @extern c "tl_bytes_from_list" pub fn from_list :: items: List -> Bytes /// The bytes as Ints. @extern c "tl_bytes_to_list" pub fn to_list :: b: Bytes -> List /// A growable buffer: append pieces, then `build` the `Bytes` once. /// Appending copies only the piece: a builder that is unique (no other /// reference to it remains, as with `bytes.append(acc, piece)` in a loop) /// grows in place, so building is linear in the total size, and `build` /// hands its buffer over without copying it. A builder is still a value: /// appending to one builder twice gives two independent builders (the /// second append copies it). @builtin pub type Builder pub fn builder :: -> Builder { builder_with_capacity 0 } /// An empty builder with room for `capacity` bytes before it grows. @extern c "tl_bytes_builder" pub fn builder_with_capacity :: capacity: Int -> Builder @extern c "tl_bytes_append" owned pub fn append :: b: Builder data: Bytes -> Builder /// Append the UTF-8 encoding of `s`. @extern c "tl_bytes_append_string" owned pub fn append_string :: b: Builder s: String -> Builder /// Append one byte (`0..=255`; panics on any other Int). @extern c "tl_bytes_append_byte" owned pub fn append_byte :: b: Builder byte: Int -> Builder /// Everything appended, in order. @extern c "tl_bytes_build" owned pub fn build :: b: Builder -> Bytes /// Everything appended, in order, as text. Panics if the bytes are not /// valid UTF-8 (the message names the first invalid byte, as /// `to_string`'s error does). Like `build`, a unique builder hands its /// buffer over without copying it. @extern c "tl_bytes_build_string" owned pub fn build_string :: b: Builder -> String