Skip to content
velt/ffi exports

velt/ffi

API reference

The 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.

import { Ptr, StrBytes, byteLength, CString, Out, OutPtr, readBytes, readUtf8, readCString } from "velt/ffi";

Exports

function

byteLength

#std/ffi/str_bytes.velt:20

Re-exported from velt/ffi/str_bytes

function byteLength(s: string): usize

The number of UTF-8 bytes a StrBytes argument passes for s: what C's length parameter takes next to it. O(1).

function

readBytes

#std/ffi/read.velt:13

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.

function

readCString

#std/ffi/read.velt:38

Re-exported from velt/ffi/read

function readCString(p: Ptr<u8>): string

The 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.

function

readUtf8

#std/ffi/read.velt:29

Re-exported from velt/ffi/read

function readUtf8(p: Ptr<u8>, len: usize): string

The 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 yet
toString(): string

The 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 yet
constructor(value: T)No doc comment yet

Re-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> | null

The 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.

static unsafe at<T>(address: usize): Ptr<T>

A pointer to address. Unsafe: nothing checks that a T is there, and C will read or write it.

static addressOf<T>(p: Ptr<T>): usize

The address p holds.

Re-exported from velt/ffi/str_bytes

type StrBytes = string

A 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.