CBuffer[optional A: Integer[A] val]¶

[Source]

class ref CBuffer[optional A: Integer[A] val]

Constructors¶

create¶

[Source]

Allocate a buffer of size bytes, zero-filled. CBuffer explicitly does not support resize. To grow, construct a new CBuffer and copy.

The type parameter A selects the numeric type backing written_size. It defaults to ISize so the negative-sentinel idiom remains available; callers wanting an unsigned width (e.g. CBuffer[U32]) can override.

new ref create(
  size: USize val,
  bzero: Bool val = true)
: CBuffer[A] ref^

Parameters¶

size: USize val
bzero: Bool val = true

Returns¶

CBuffer[A] ref^

Public Functions¶

allocated¶

[Source]

Returns allocated capacity in bytes.

fun box allocated()
: USize val

Returns¶

USize val

reset¶

[Source]

Zero-fill the buffer and reset written_size to 0.

fun ref reset()
: None val

Returns¶

None val

ptr¶

[Source]

Base pointer for FFI calls.

fun ref ptr()
: Pointer[U8 val] ref

Returns¶

Pointer[U8 val] ref

get_written_size¶

[Source]

Most recent filled length, in bytes. When A is signed, callers may use negative values as out-of-band sentinels.

fun box get_written_size()
: A

Returns¶

A

set_written_size¶

[Source]

Set written_size from Pony code. Useful when a caller wants to mark the buffer with a sentinel without going through C.

fun ref set_written_size(
  n: A)
: None val

Parameters¶

n: A

Returns¶

None val

written_size_ptr¶

[Source]

Address of the written_size field, for C functions that report the filled length through an out-parameter.

fun ref written_size_ptr()
: CBox[A] ref

Returns¶

CBox[A] ref

write¶

[Source]

Copy str into the buffer and set written_size to its length. Returns false (leaving the buffer unchanged) if str exceeds capacity.

Refuses truncation rather than silently dropping bytes.

bzero can be disabled for performance reasons if dealing with massive allocations in hot-paths. You probably shouldn't unless you're certain you know what you're doing.

fun ref write(
  str: String val,
  bzero: Bool val = true)
: Bool val

Parameters¶

str: String val
bzero: Bool val = true

Returns¶

Bool val

write_array¶

[Source]

Copy arr into the buffer and set written_size to its length. Returns false (leaving the buffer unchanged) if the buffer is not allocated or arr exceeds capacity.

Refuses truncation rather than silently dropping bytes.

bzero can be disabled for performance reasons if dealing with massive allocations in hot-paths. You probably shouldn't unless you're certain you know what you're doing.

fun ref write_array(
  arr: Array[U8 val] val,
  bzero: Bool val = true)
: Bool val

Parameters¶

arr: Array[U8 val] val
bzero: Bool val = true

Returns¶

Bool val

copy_string_truncated¶

[Source]

Copy the filled region out as a String. Errors if the buffer is not allocated or written_size is negative. If written_size exceeds cap() (e.g. a C caller reporting truncation), the result is clamped to cap() rather than walking off the end of the allocation.

fun ref copy_string_truncated()
: String iso^ ?

Returns¶

String iso^ ?

copy_array_truncated¶

[Source]

Copy the filled region out as an Array[U8]. Same error and clamp semantics as copy_string_truncated().

fun box copy_array_truncated()
: Array[U8 val] iso^ ?

Returns¶

Array[U8 val] iso^ ?

copy_string¶

[Source]

Copy the filled region out as a String. Errors if the buffer is not allocated or written_size is negative, or if written_size is greater than the allocated space.

fun ref copy_string()
: String iso^ ?

Returns¶

String iso^ ?

copy_array¶

[Source]

Copy the filled region out as an Array[U8]. Same error semantics as copy_string().

fun box copy_array()
: Array[U8 val] iso^ ?

Returns¶

Array[U8 val] iso^ ?