lib/block.x

Checked dynamic storage for fixed-width elements.

Advanced and interop API

Block

Block.append

void Block.append(Block b, const void *source, size_t count)

Appends count elements copied from source to block. The source may be NULL for zero-filled elements; otherwise it must name count readable elements. When growth is required, an initialized range inside this Block’s reserved storage keeps its offset across relocation. Success may invalidate saved Bytes and element pointers.

Raises: <bad-arg> for a null Block, or for an internal source crossing reserved storage when growth is required; <size-limit> when the new extent cannot be represented; or <alloc-fail> when growth fails. These failures leave the Block unchanged.

Source: lib/block.x:145

Block.append_fill

void Block.append_fill(Block b, const void *element, size_t count)

Appends repeated fixed-width elements to block. A zero count is a no-op and accepts a null element. Otherwise element must point to one complete element. element may point at one complete logical element in block; its offset is preserved if growth relocates storage. Success may invalidate saved Bytes and element pointers.

Raises: <bad-arg> for a null Block, or for a null or invalid self-source element on a nonzero append; <size-limit> when the new extent cannot be represented; or <alloc-fail> when growth fails. These failures leave the Block unchanged.

Source: lib/block.x:212

Block.capacity

inline size_t Block.capacity(Block block)

Returns how many elements block can hold without growing.

Source: lib/block.x:318

Block.clear

inline void Block.clear(Block block)

Removes every element from block without releasing capacity.

Source: lib/block.x:131

Block.free

void Block.free(Block block)

Releases the Block and its backing storage, invalidating every alias.

Source: lib/block.x:287

Block.len

inline size_t Block.len(Block block)

Returns the number of elements stored in block.

Source: lib/block.x:311

Block.new

Block Block.new(size_t width)

Allocates an empty Block for elements of width bytes.

Raises: <bad-arg> when width is zero, <size-limit> when the initial allocation size cannot be represented, or <alloc-fail> when allocation fails.

Source: lib/block.x:52

Block.pop

inline void Block.pop(Block block)

Removes the final element of block when present.

Source: lib/block.x:282

Block.push

inline void Block.push(Block block, const void *source)

Appends one copied element; storage and failures follow Block.append.

Source: lib/block.x:273

Block.reserve

void Block.reserve(Block block, size_t minimum)

Ensures block can hold at least minimum elements. The Block handle and contents remain stable, but growth may replace block.bytes and invalidate saved Bytes or element pointers.

Raises: <bad-arg> when block is null, <size-limit> when the requested capacity cannot be represented, or <alloc-fail> when growth fails. These failures leave the Block unchanged.

Source: lib/block.x:90

Block.truncate

inline void Block.truncate(Block block, size_t length)

Shortens block to at most length elements.

Source: lib/block.x:126

Block.truth

int Block.truth(Block block)

Returns nonzero when block contains at least one element.

Source: lib/block.x:315

Block.try_pop

inline int Block.try_pop(Block block, void *out)

Removes the final element of block, copying it to out when present. Returns zero for a null or empty Block and leaves out unchanged. A null out still removes a present element.

Source: lib/block.x:259

Bytes

Bytes.append

inline Self Bytes.append(Self bytes, const void *source, size_t count)

Appends count elements to bytes and returns its current base pointer. Callers must use the return because growth may relocate storage. Raises: the same causes as Block.append; failure leaves the original view live .

Source: lib/block.x:194

Bytes.append_fill

inline Self Bytes.append_fill(Self bytes, const void *element, size_t count)

Appends repeated elements to bytes and returns its current base pointer. Callers must use the return because growth may relocate storage. Raises: the same causes as Block.append_fill; failure leaves the original view live.

Source: lib/block.x:249

Bytes.block

inline Block Bytes.block(Bytes bytes)

Returns the stable Block that owns the live bytes base pointer. An interior or stale pointer is invalid; NULL returns NULL.

Source: lib/block.x:77

Bytes.new

Bytes Bytes.new(size_t width)

Allocates empty byte storage for elements of width bytes. The result is the base view of a Scope-owned Block. Methods that may grow it return the current Bytes pointer, which callers must keep.

Raises: the same causes as Block.new.

Source: lib/block.x:72

Bytes.push

inline Self Bytes.push(Self bytes, const void *source)

Appends one element and returns the possibly relocated Bytes base.

Source: lib/block.x:278

Bytes.reserve

inline Self Bytes.reserve(Self bytes, size_t minimum)

Ensures bytes can hold at least minimum elements and returns its base. Growth may relocate storage, so callers must use the returned Bytes and discard earlier views. Raises: the same causes as Block.reserve; failure leaves the original view live.

Source: lib/block.x:119

Bytes.try_pop

inline int Bytes.try_pop(Bytes bytes, void *out)

Removes the final element through bytes as Block.try_pop does.

Source: lib/block.x:270

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Block

Block.move_to

void Block.move_to(Block block, Scope *scope)

Moves block and its backing allocation into scope. This preserves the Block and Bytes pointers and contents while changing which Scope ends their lifetime. Context export calls this method instead of assuming a Block is one allocation. For a nonnull Block, raises <bad-arg> for a null destination slot, or <alloc-fail> when an empty slot cannot acquire a Scope. Failure leaves ownership unchanged.

Source: lib/block.x:303

Public types

Block

typedef struct Block { Bytes bytes, size_t width, length, cap; } *Block

Holds resizable contiguous storage for fixed-width elements. The object and backing allocation belong to the Scope active at construction unless Block.move_to transfers them. The Block handle remains stable, but bytes is a borrowed base pointer that growth may replace. Valid Blocks have nonzero width and length <= cap; Block.free invalidates the handle and every Bytes view.

Source: lib/block.x:32

Design notes

Block maintains the length and capacity invariants for contiguous fixed-width storage. Bytes exposes the same allocation through its data pointer and a hidden back-pointer. Capacity growth raises where the failure is detected, leaves storage unchanged, and does not return to the call.

A self-source may name any initialized range inside reserved capacity. Growth rebases that range after reallocating the owning block.

The declared Block protocol supplies Bytes’s generated truth, pop, free, and truncate members through the Bytes.block storage view.