Bristle

bristle.text

2026-08-25T22:28:57.485307746Z

Index

starts_with ends_with find split_once trim Cursor Utf8Error

Functions

`starts_with`

starts_with(s: []const u8, prefix: []const u8) -> bool

Answers whether s begins with prefix.

An empty prefix is present in every string, so starts_with(s, "") answers true for every s — including an empty one.

Parameter	Type	Description
`s`	`[]const u8`	the bytes to test
`prefix`	`[]const u8`	the prefix to look for

Returns bool — true when s begins with prefix.

`ends_with`

ends_with(s: []const u8, suffix: []const u8) -> bool

Answers whether s ends with suffix. The mirror of starts_with, and it treats an empty suffix the same way.

Parameter	Type	Description
`s`	`[]const u8`	the bytes to test
`suffix`	`[]const u8`	the suffix to look for

Returns bool — true when s ends with suffix.

`find`

find(haystack: []const u8, needle: []const u8) -> Option[usize]

Answers the byte offset of the first occurrence of needle in haystack.

The offset is in bytes, not characters — a needle found after a three-byte character is at offset 3. Nothing here decodes UTF-8, which is what lets the module make no allocation and ask for no capability.

Parameter	Type	Description
`haystack`	`[]const u8`	the bytes to search
`needle`	`[]const u8`	the bytes to search for

Returns Option[usize] — Some(i) where i is the offset of the first occurrence, or None when needle does not occur. An empty needle occurs at offset 0.

`split_once`

split_once(s: []const u8, sep: []const u8) -> Option[([]const u8, []const u8)]

Splits s at the first occurrence of sep and answers the two halves, neither of which contains the separator.

Both halves are slices of s, so they live exactly as long as it does and cost nothing to produce. Splitting "key=value=more" on "=" answers ("key", "value=more") — the separator is found once, not greedily.

Parameter	Type	Description
`s`	`[]const u8`	the bytes to split
`sep`	`[]const u8`	the separator to split at

Returns Option[([]const u8, []const u8)] — the two halves, or None when sep does not occur in s.

`trim`

trim(s: []const u8) -> []const u8

Answers s without leading or trailing ASCII whitespace.

Whitespace here is space, tab, carriage return, line feed, form feed and vertical tab — the set C’s isspace uses in the C locale. Unicode whitespace is deliberately not recognised, for the same reason find does not decode: it would make the module need a table.

Note

A string that is entirely whitespace trims to an empty slice, not to None.

Parameter	Type	Description
`s`	`[]const u8`	the bytes to trim

Returns []const u8 — a sub-slice of s.

Types

`Cursor`

struct Cursor
    src: []const u8
    pos: usize

A position within a byte slice, for walking one token at a time.

A cursor borrows its source rather than owning it, so it must not outlive the slice it was made from. Reading past the end is not an error — the reading members answer None instead.

Field	Type	Description
`src`	`[]const u8`	the bytes being walked
`pos`	`usize`	the current offset, in bytes, from the start of `src`

`Utf8Error`

enum Utf8Error
    Truncated(at: usize)
    Invalid(at: usize)

What went wrong while decoding, and where.

Both variants carry the byte offset at which the problem was found, so a caller can report the position without walking the input a second time.

Variant	Payload	Description
`Truncated`	`at: usize`	the input ended part-way through a character
`Invalid`	`at: usize`	the byte at this offset can begin no character

Traits

`Scan`

trait Scan
    type Item
    next(self) -> Option[Self::Item]

What a thing that yields items one at a time has to provide.

Implemented by Cursor, and by anything else that walks a source without owning it. The associated Item is what settles what a walk yields, so one trait covers a cursor over bytes and a cursor over lines.

Members

Member	Signature	Description
`Item`	associated type	what each step yields
`next`	`(self) -> Option[Self::Item]`	the next item, or `None` at the end

bristle.buf

2026-08-25T22:28:57.485307746Z

Index

buf with_capacity push extend as_slice clear Buf Full

Functions

`buf`

buf() -> Buf

Answers an empty buffer that has allocated nothing yet.

The first push allocates. A buffer that is built and dropped without ever being written to therefore costs no allocation at all, which is why this rather than a capacity is the default constructor.

Returns Buf — an empty buffer with a capacity of zero.

`with_capacity`

with_capacity(n: usize) -> Buf

Answers an empty buffer with room for n bytes already reserved.

Reach for this when the size is known — building a line of known width, or encoding a value whose bound the caller can compute. It turns a run of doubling reallocations into one.

Parameter	Type	Description
`n`	`usize`	how many bytes to reserve

Returns Buf — an empty buffer whose capacity is at least n.

`push`

push(self, b: u8) -> Result[unit, Full]

Appends one byte, growing the buffer if it is full.

Parameter	Type	Description
`self`	`&Buf`	the buffer to append to
`b`	`u8`	the byte to append

Returns Result[unit, Full] — Ok(()), or Err(Full) when the allocator refused. A refused push leaves the buffer exactly as it was.

`extend`

extend(self, bytes: []const u8) -> Result[unit, Full]

Warning

A failed extend is not atomic — the bytes that fit are kept. Read the length back if you need to know how far it got.

Appends every byte of bytes, growing once rather than once per byte.

Parameter	Type	Description
`self`	`&Buf`	the buffer to append to
`bytes`	`[]const u8`	the bytes to append

Returns Result[unit, Full] — Ok(()), or Err(Full) when the allocator refused part-way.

`as_slice`

as_slice(self) -> []const u8

Answers the written bytes as a slice, without copying them.

The slice borrows the buffer’s storage, so it is invalidated by the next push, extend or clear. Hand it to a reader that finishes with it before the buffer is touched again.

Parameter	Type	Description
`self`	`&Buf`	the buffer to read

Returns []const u8 — the bytes written so far, in order.

`clear`

clear(self)

Forgets the written bytes and keeps the storage.

The capacity is unchanged, which is the point: a buffer cleared between iterations of a loop allocates once for the whole loop rather than once per pass.

Parameter	Type	Description
`self`	`&Buf`	the buffer to clear

Types

`Buf`

struct Buf
    ptr: *u8
    len: usize
    cap: usize

A growable byte buffer.

The fields are private to the module; they are listed because a reader working out the cost of an operation needs to know there are three of them and that none is a length prefix stored with the data.

Field	Type	Description
`ptr`	`*u8`	the allocated storage, or null at capacity zero
`len`	`usize`	how many bytes have been written
`cap`	`usize`	how many bytes `ptr` has room for

`Full`

struct Full
end Full

The allocator refused to grow the buffer.

It carries nothing: there is one way for an append to fail and no detail a caller could act on. A program that wants to distinguish out of memory from over a configured ceiling wants two allocators, not two errors.