velt/ffi
API referenceThe types that cross to C functions declared with declare c: pointers, strings, out-parameters, and copies of C memory. Programs use them only through a binding's safe API; a package with native code uses them to write that API. For a walkthrough, read the guide.
Exports
StrBytes argument passes for s: what C's length parameter takes next to it.readBytesA copy of the len bytes at p.readCStringThe text of the NUL-terminated UTF-8 string at p, copied; an invalid sequence becomes U+FFFD.readUtf8The text of the len bytes of UTF-8 at p, copied; an invalid sequence becomes U+FFFD.CStringA NUL-terminated copy of a string's UTF-8, which a C function declared to take CString reads as const char *.OutA number (or bool) a C function writes through a pointer parameter declared Out<T> (int *out, size_t *len): C gets the address of value, and value holds what it wrote once the call returned.OutPtrA pointer a C function writes through a pointer parameter declared OutPtr<T> (T **out, as sqlite3_open_v2 returns its database): C gets the address of the pointer it holds, and value is what it wrote once the call returned (null for NULL).PtrThe address of a T in C memory (docs/internals/design/c-ffi.md): what a C function declared with declare c returns as Ptr<T>, and passes to C when given as an argument.StrBytesA string passed to a C function as its UTF-8 bytes, borrowed for the call and without a NUL: the declaration of a parameter says so (text: StrBytes), and the binding passes the length (byteLength(s)).Re-exported from velt/ffi/str_bytes
function byteLength(s: string): usizeThe number of UTF-8 bytes a StrBytes argument passes for s: what C's length parameter
takes next to it. O(1).
Re-exported from velt/ffi/read
function readBytes(p: Ptr<u8>, len: usize): u8[]A copy of the len bytes at p. Unsafe: p must point at len readable bytes, which C
doesn't change during the copy.
Re-exported from velt/ffi/read
function readCString(p: Ptr<u8>): stringThe text of the NUL-terminated UTF-8 string at p, copied; an invalid sequence becomes U+FFFD.
Unsafe: p must point at a NUL-terminated string.
Re-exported from velt/ffi/read
function readUtf8(p: Ptr<u8>, len: usize): stringThe text of the len bytes of UTF-8 at p, copied; an invalid sequence becomes U+FFFD. Unsafe:
as readBytes.
Re-exported from velt/ffi/c_string
A NUL-terminated copy of a string's UTF-8, which a C function declared to take CString
reads as const char *. Made once (one allocation) and passed to any number of calls. A string
holding a lone surrogate is copied with U+FFFD for it; a string holding a NUL is refused, since
C would stop reading there.
constructor(s: string)No doc comment yettoString(): stringThe string, without its NUL.
static bytesOf(c: CString): ReadonlyArray<u8>The bytes a C function reads: the UTF-8 and the NUL after it, read-only.
Re-exported from velt/ffi/out
class Out<T>A number (or bool) a C function writes through a pointer parameter declared Out<T>
(int *out, size_t *len): C gets the address of value, and value holds what it wrote
once the call returned.
value: TNo doc comment yetconstructor(value: T)No doc comment yetRe-exported from velt/ffi/out_ptr
class OutPtr<T>A pointer a C function writes through a pointer parameter declared OutPtr<T> (T **out,
as sqlite3_open_v2 returns its database): C gets the address of the pointer it holds, and
value is what it wrote once the call returned (null for NULL).
get value(): Ptr<T> | nullThe pointer C wrote, or null for NULL (and before any call).
Re-exported from velt/ffi/ptr
struct Ptr<T>The address of a T in C memory (docs/internals/design/c-ffi.md): what a C function declared
with declare c returns as Ptr<T>, and passes to C when given as an argument. T is a type
declared with declare c type (or a number type, for a pointer to numbers); Ptr<T> | null
is a pointer that may be NULL. Nothing in Velt reads or writes through one without unsafe
code.
Parameter ofreadBytesreadCStringreadUtf8Returned byOutPtr.value
Re-exported from velt/ffi/str_bytes
type StrBytes = stringA string passed to a C function as its UTF-8 bytes, borrowed for the call and without a
NUL: the declaration of a parameter says so (text: StrBytes), and the binding passes the
length (byteLength(s)). A string holding a lone surrogate passes a copy with U+FFFD for it,
which has the same byte length.