silk/bytes

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

Owned arbitrary bytes for file contents, process output, and other encoding-neutral data.

When to use

Use Bytes when every octet must round-trip unchanged. Use silk.string.String instead when the value is known to be valid UTF-8 and callers need text operations.

make creates an empty value without allocating, while zeroed, copy, and append may require an Allocator. Shared and exclusive views borrow only the initialized prefix; later appends can reallocate, so do not retain a view across a mutation.

Examples

Copy, append, and update bytes

import silk.bytes { Bytes }

import silk.allocator { Allocator, OutOfMemoryError }

import silk.effect { Effect }

import silk.u8

effect fn build() -> i32
! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let source = b"AB"
  let copying = Bytes.copy(&source)
    |> Effect.provideMut<Allocator>(&mut allocator)
  let mut bytes = run copying
  let suffix = b"C"
  let appending = Bytes.append(&mut bytes, &suffix)
    |> Effect.provideMut<Allocator>(&mut allocator)
  let appended = run appending
  let mut writable = Bytes.asMutSlice(&mut bytes)
  writable[1] = u8.toU8(48)
  let readable = Bytes.asSlice(&bytes)
  return u8.toI32(readable[0]) - u8.toI32(readable[1]) + u8.toI32(readable[2]) - 42
}

effect fn recover(error: OutOfMemoryError) -> i32 {
  return 0
}

pub fn main() -> i32 {
  return run Effect.catchAll(build(), recover)
}

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

Public declarations: 1.

`Bytes`

pub struct Bytes

An owned encoding-neutral sequence of arbitrary octets.

Details

A value owns its initialized bytes and releases their storage on drop. Its length can grow with append, and its capacity is not part of the public contract.

Associated function `Bytes.make`

pub fn make() -> Bytes

Creates an empty Bytes value without allocating storage.

Associated function `Bytes.zeroed`

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

Allocates an owned initialized byte buffer of exactly length zero octets.

Details

A zero length returns an empty value without an allocation.

Method `Bytes.length`

pub fn length<'life0>(self: &'life0 Bytes) -> usize

Returns the initialized byte count.

Associated function `Bytes.copy`

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

Copies a complete borrowed byte sequence into independently owned storage.

Details

Empty input does not allocate. Nonempty input uses one allocation sized to its byte length.

Method `Bytes.reserveExact`

pub effect<'life0> fn reserveExact<'life0>(self: &'life0 mut Bytes, additional: usize) -> () ! OutOfMemoryError ? &mut Allocator

Reserves storage for additional bytes without changing the initialized length.

Details

Sufficient capacity is reused. Otherwise, one allocation provides the current length plus additional bytes of capacity. Size overflow or allocation failure leaves the value unchanged.

Method `Bytes.clear`

pub fn clear<'life0>(self: &'life0 mut Bytes) -> ()

Removes all initialized bytes and keeps the allocation for reuse.

Method `Bytes.truncate`

pub fn truncate<'life0>(self: &'life0 mut Bytes, length: usize) -> ()

Removes bytes after length and keeps the allocation for reuse.

Details

A length greater than or equal to the current length leaves the value unchanged.

Method `Bytes.append`

pub effect<'env> fn append<'life0: 'env, 'life1: 'env, 'env>(self: &'life0 mut Bytes, values: &'life1 [u8]) -> () ! OutOfMemoryError ? &mut Allocator

Appends a complete borrowed byte sequence in source order.

Details

If growth fails, the original bytes and their length remain unchanged.

Method `Bytes.asSlice`

pub fn asSlice<'life0>(self: &'life0 Bytes) -> &'life0 [u8]

Borrows all initialized octets as one shared lexical slice.

Method `Bytes.asMutSlice`

pub fn asMutSlice<'life0>(self: &'life0 mut Bytes) -> &'life0 mut [u8]

Borrows all initialized octets as one exclusive lexical slice.

Gotchas

Do not retain this slice across append, because an append can replace the allocation.

On this page