envzn
0.8 · beta · not released

Library / Strings / Bytes / ByteBufferView

CLASSIMPLEMENTS View, Viewable

ByteBufferView

A non-owning, bounded window over a ByteBuffer's binary[] storage. The byte-side mirror of StringView: it holds the one canonical binary scan (find / contains / count) that ByteBuffer — and, via a ByteBuffer snapshot, DynamicByteBuffer — forward into. Like StringView it is ByteBuffer-free: it knows only binary[], so it introduces no dependency cycle with the owning buffer types.

Constructors 1

INIT(REFERENCE binary[] source, int64 start, int64 length)

Construct a bounded view over [start, start+length) in source. Raises a PANIC (via the C-string helper) if start < 0 or length < 0 or start + length > source.length(). A zero length is allowed.

Methods 15

METHOD length() RETURNS int64
reads

Byte count of this view.

METHOD size() RETURNS int64
reads

Countable — View EXTENDS Countable, so the view owes size() and isEmpty() as well as its own length(). All three are the same number here: the count of octets the window spans.

METHOD isEmpty() RETURNS boolean
reads
METHOD __op_index__(int64 i) RETURNS binary
reads

Byte at index i within this view. bv[i] is the only read syntax. Raises a PANIC (C-string helper) if i is out of [0, view.length).

METHOD find(REFERENCE binary[] needle) RETURNS | int64
reads

First occurrence of needle's bytes within this view's whole range. Pipe-XOR: SUCCESS yields the view-relative index of the match; FAILURE means no match. To search a sub-range, narrow with view(start, length) first.

METHOD startsWith(REFERENCE binary[] needle) RETURNS boolean
reads

True iff this view begins with needle. An empty needle returns TRUE; a needle longer than the view returns FALSE.

METHOD endsWith(REFERENCE binary[] needle) RETURNS boolean
reads

True iff this view ends with needle. An empty needle returns TRUE; a needle longer than the view returns FALSE.

METHOD lastIndexOf(REFERENCE binary[] needle) RETURNS | int64
reads

Last occurrence of needle within this view. Pipe-XOR: SUCCESS yields the view-relative index of the final match; FAILURE means no match. An empty needle yields the view length. Scans backward from the last candidate window, so the first hit found is the last occurrence.

METHOD contains(REFERENCE binary[] needle) RETURNS boolean
reads

True iff needle occurs at least once in this view.

METHOD count(REFERENCE binary[] needle) RETURNS int64
reads

Non-overlapping occurrence count of needle. Empty needle returns 0.

METHOD find_first_of(REFERENCE binary[] set) RETURNS | int64
reads

B1: index of the first byte that IS a member of set. Pipe-XOR: SUCCESS = the index; FAILURE = no byte in this view is in set.

METHOD find_first_not_of(REFERENCE binary[] set) RETURNS | int64
reads

B1: index of the first byte that is NOT a member of set.

METHOD view(int64 start, int64 length) RETURNS ByteBufferView
reads

Narrow to a sub-window [start, start+length) relative to THIS view (composition — a sub-window of a window is a window). Bounds are checked against this view's length, so a sub-view can never escape its parent. Satisfies Viewable.

METHOD copy() RETURNS binary[]
reads

Materialise this window's bytes into a fresh binary[] (the "keep this slice" escape hatch — the view itself never escapes). Wrap with CREATE ByteBuffer(view->copy()) for an owned ByteBuffer.

METHOD iterator() RETURNS ValueIterator[binary]
reads

Walk this window's bytes in order. Mirrors StringView.iterator(), which the byte axis had no counterpart to until now.

The window is materialised and GIVEN to the iterator. It cannot be lent: .source is a REFERENCE field — a pointer — and does not bind to a REFERENCE binary[] parameter, so the only array this view can offer is a local snapshot, and lending a local returns an iterator over freed storage. The owning constructor takes the array, so the referent lives exactly as long as the iterator does.