silk.collections.bytes.

When to use#

Use Bytes when each byte must stay unchanged and the data is not necessarily text. Use silk.text.string.String when the data is valid UTF-8 and the code needs text operations. Use silk.collections.list.List<u8> when the code appends many single bytes.

Details#

Bytes.make does not allocate. Bytes.makeWithCapacity, Bytes.zeroed, Bytes.copy, Bytes.append, Bytes.reserve, and Bytes.reserveExact can allocate and need an Allocator. Bytes.clear and Bytes.truncate keep the storage for reuse, and Bytes.clearAndFree releases it. Bytes.asSlice and Bytes.asMutSlice borrow the bytes. Dropping a Bytes value releases its storage.

Examples#

Copy, append, and change bytes#

import silk.collections.bytes { Bytes }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let mut bytes = run Bytes.copy(b"AB") |> Effect.provideMut<Allocator>(&mut allocator)
  run Bytes.append(&mut bytes, b"C") |> Effect.provideMut<Allocator>(&mut allocator)
  let mut writable = Bytes.asMutSlice(&mut bytes)
  writable[1] = 48
  drop writable

  // The bytes are now "A0C".
  let readable = Bytes.asSlice(&bytes)
  if readable.length != 3 || readable[1] != 48 || readable[2] != 67 {
    return 1
  }
  return 0
}

Import as Bytes with import silk.collections.bytes { Bytes }.

Public declarations: 1.

Bytes#

pub struct Bytes

An owned sequence of bytes. Dropping it releases its storage.

Details#

The length is the number of bytes in the value. The length grows with Bytes.append. The capacity is the number of bytes that fit before the next allocation. Bytes.clear and Bytes.truncate keep the capacity, so a buffer cleared and filled again in a loop reuses its storage. Bytes.clearAndFree releases the storage.

Implementation Debug for Bytes#

impl Debug for Bytes

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes each byte as a number, as [104, 105], like a &[u8].

Implementation Bytes#

impl Bytes

Associated function make#

pub fn make() -> Bytes

Returns an empty Bytes value. This function does not allocate.

Associated function makeWithCapacity#

pub effect fn makeWithCapacity(capacity: usize) -> Bytes ! OutOfMemoryError ? &mut Allocator

Returns an empty Bytes value with storage for exactly capacity bytes.

When to use#

Use makeWithCapacity when the number of bytes is known or can be estimated before the appends, so that the value allocates once.

Details#

The length is 0 and the capacity is capacity. A capacity of 0 does not allocate.

Errors#

• OutOfMemoryError if the Allocator cannot supply the storage.

Associated function zeroed#

pub effect fn zeroed(length: usize) -> Bytes ! OutOfMemoryError ? &mut Allocator

Returns a Bytes value of length zero bytes.

When to use#

Use zeroed to make a buffer that code then fills through Bytes.asMutSlice, such as the destination of a read.

Details#

A length of 0 returns an empty value and does not allocate.

Errors#

• OutOfMemoryError if the Allocator cannot supply the storage.

Method length#

pub fn length(self: &Self) -> usize

Returns the number of bytes.

Associated function copy#

pub effect fn copy(values: &[u8]) -> Bytes ! OutOfMemoryError ? &mut Allocator

Returns a new Bytes value that holds a copy of values.

Details#

An empty values does not allocate. Otherwise, the function makes one allocation of exactly values.length bytes.

Errors#

• OutOfMemoryError if the Allocator cannot supply the storage.

Method reserveExact#

pub effect fn reserveExact(self: &mut Self, additional: usize) -> ()
  ! OutOfMemoryError
  ? &mut Allocator

Makes sure that at least additional more bytes fit without another allocation. The length does not change.

Details#

If the capacity is already sufficient, this function does nothing. Otherwise, it makes one allocation for exactly length + additional bytes.

Errors#

• OutOfMemoryError if length + additional overflows usize, or the Allocator cannot supply the storage. The value does not change.

Method reserve#

pub effect fn reserve(self: &mut Self, additional: usize) -> ()
  ! OutOfMemoryError
  ? &mut Allocator

Makes sure that at least additional more bytes fit without another allocation, with room to spare for later appends. The length does not change.

When to use#

Use reserve before a run of appends whose total is not known. Use Bytes.reserveExact when the final length is known.

Details#

If the capacity is already sufficient, this function does nothing. Otherwise, it grows the capacity by doubling until the bytes fit.

Errors#

• OutOfMemoryError if length + additional overflows usize, or the Allocator cannot supply the storage. The value does not change.

Method shrinkToFit#

pub effect fn shrinkToFit(self: &mut Self) -> () ! OutOfMemoryError ? &mut Allocator

Releases the capacity beyond the length.

Details#

If the capacity equals the length, this function does nothing. If the value is empty, it releases the storage. Otherwise, it moves the bytes into storage for exactly the length.

Errors#

• OutOfMemoryError if the Allocator cannot supply the new storage. The value does not change. An empty value never fails.

Method capacity#

pub fn capacity(self: &Self) -> usize

Returns the number of bytes the storage holds before the next append allocates.

Method clear#

pub fn clear(self: &mut Self) -> ()

Removes all bytes. The storage stays allocated for reuse.

Details#

Later appends up to the old capacity do not allocate. Use Bytes.clearAndFree to also release the storage.

Method clearAndFree#

pub fn clearAndFree(self: &mut Self) -> ()

Removes all bytes and releases the storage. The length and the capacity become 0.

Details#

This function does not allocate and does not need an Allocator. Use Bytes.clear to keep the storage for reuse.

Method truncate#

pub fn truncate(self: &mut Self, length: usize) -> ()

Removes the bytes from position length to the end. The storage stays allocated for reuse.

Details#

If length is more than or equal to the current length, this function does nothing.

Method append#

pub effect fn append(self: &mut Self, values: &[u8]) -> () ! OutOfMemoryError ? &mut Allocator

Adds a copy of values at the end, in order.

Errors#

• OutOfMemoryError if the Allocator cannot supply the storage. The value does not change.

Method asSlice#

pub fn asSlice(self: &Self) -> &[u8]

Returns a shared borrow of all bytes as a slice.

Method asMutSlice#

pub fn asMutSlice(self: &mut Self) -> &mut [u8]

Returns an exclusive borrow of all bytes as a slice.

Details#

Use the slice to change bytes in place. The slice cannot change the length. The compiler rejects other uses of the value, such as Bytes.append, while the slice is live.

Category: Collections.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.