std.bytes

std.bytes provides explicit borrowed read-only byte views for common standard-library values. Bytes is the boundary between text and arbitrary bytes: byte views do not promise UTF-8 validity and may contain NUL bytes.

How It Works

Borrowed views do not allocate. They remain valid while the source value is alive and is not mutated in a way that changes its storage. Bytes.at(index) and Bytes.slice(start, length) use byte offsets and may split a UTF-8 sequence; use std.unicode.utf8.text for a checked source-region text view, or the lower-level decoder when processing an arbitrary byte stream.

Borrowed Views

Bytes is a borrowed read-only byte view. Its only public constructors are the explicit safe forms bytes.Bytes(text) and bytes.Bytes(data), where text is a str and data is a [u8]. Public callers can read and slice a view, or pass ptr() plus length to low-level read-only sinks. There is no implicit conversion from text or byte slices to Bytes, and there is no public raw- pointer constructor.

import std.bytes;
import std.mem.{ AllocError };

fn main() {
	let literal = bytes.Bytes("hello");
	assert literal.length == 5 as usize;
	assert literal.at(0) == 104 as u8;
	assert literal.length != 0 as usize;

	let text = try ("world").clone();
	let view = bytes.Bytes(text);
	assert view.at(0) == 119 as u8;
	assert text == "world";

	let tail = literal.slice(1, 4);
	assert tail.at(0) == 101 as u8;
}

Streams

MemoryStream owns mutable buffered storage in std.io. To borrow its current contents as bytes, request a slice from the stream and adapt that slice.

import std.bytes;
import std.io;
import std.mem.{ AllocError };

fn main() {
	var stream = io.MemoryStream();
	try stream.write(bytes.Bytes("ok"));

	let view = stream.bytes();
	assert view.length == 2 as usize;
	assert view.at(0) == 111 as u8;
	assert view.at(1) == 107 as u8;
}

Ownership, Allocation, Errors, And Unspecified Behavior

Bytes is a region-typed Copy view over storage owned elsewhere. Its inferred region is tied to the checked source passed to a public constructor and is preserved by slice(), so the view cannot escape that source. Constructing, copying, slicing, and reading a view do not allocate and do not throw. at and slice assert their bounds; callers must pass indexes within the view.

ptr() returns a read-only *u8. Obtaining that pointer is safe, but raw pointer dereference and every operation that relies on its validity remain an explicit unsafe responsibility. Code that starts from initialized raw storage, including standard-library internals, first calls std.mem.view(ptr, length, anchor) with a real owner/source anchor and then passes the resulting checked [u8] to Bytes(data). The lower compiler bridge used to implement mem.view is not separately nameable. There is no direct public Bytes(ptr, length) boundary.

The view's shared loan prevents ordinary safe mutation, reallocation, or drop of its source while the Bytes value is live. Mutation through raw or foreign access that violates that loan is outside the documented contract. Byte views also do not validate text and do not choose a character encoding.

Use std.unicode for validation and transcoding, and std.io for owned byte buffers and streams.

API Reference

Types

Type	Kind	Public fields	Methods	Description
Bytes	region-typed struct: Copy	length	at, slice, ptr	Borrowed read-only byte view.

Constructors

Name	Signature	Parameters	Returns	Description
Bytes	Bytes(data: str) -> Bytes	data: borrowed text	Bytes	Returns a borrowed read-only view over a str's UTF-8 bytes.
Bytes	Bytes(data: [u8]) -> Bytes	data: byte slice	Bytes	Returns a borrowed byte view over the slice without validating it as text.

Bytes Methods

Method	Signature	Parameters	Returns	Description
at	at(index: usize) -> u8	index: byte index	u8	Returns the byte at index.
slice	slice<region L>(self in L, start: usize, length: usize) -> Bytes in L	start: first byte, length: byte count	Bytes	Returns a bounded sub-view tied to the receiver.
ptr	ptr() -> *u8	None	*u8	Borrows a read-only pointer to the first byte.

Status

RFC 0046 defines the accepted target. The checked-in implementation remains transitional until the empty and raw constructors, View, is_empty, and the identity Bytes.bytes() method are removed. For the full surface inventory, see Standard Library Inventory.