nish:unsafe
Element access with no bounds check, signed arithmetic that wraps, a C string or struct read through a pointer nothing proves, and the errno a C call left.
import {
cErrno,
readCString,
readStruct,
uncheckedGet,
uncheckedSet,
wrappingAdd,
wrappingMul,
wrappingSub,
} from "nish:unsafe";
import { uncheckedGet, uncheckedSet, wrappingAdd } from "nish:unsafe";
export const mix = (h: i32[], i: i32, x: i32): void => {
uncheckedSet(h, i, wrappingAdd(uncheckedGet(h, i), x));
};
cErrno
The errno the most recent declare function call on this thread left: a program that names cErrno zeroes errno just before every foreign call and saves it just after, before any result marshalling.
readCString
The NUL-terminated bytes at p, copied into a new string by @nish.ffi.str, the scan-and-copy a string result of a declare function uses, after a NULL test that panics with ffi-null.
readStruct
A copy of the C struct at p in a new instance of the declare class the call's context names (const lc: Lconv = readStruct(localeconv())), so C may free or overwrite its struct straight after.
uncheckedGet
xs[i] with no bounds check: the same GEP and load, with no len load, no compare and no branch to the bounds panic.
uncheckedSet
xs[i] = v with no bounds check; a statement.
wrappingAdd
a + b as add with no nsw and no check: the two's-complement wrap, defined for every pair (wrappingAdd(2147483647, 1) is -2147483648).
wrappingMul
a * b as mul with no nsw and no check, wrapping (wrappingMul(INT64_MAX, 2) is -2).
wrappingSub
a - b as sub with no nsw and no check, wrapping.
Each function gives up one check the language otherwise always makes, at
one site. A program reaches them only through an import, so every module
that gives up a check or defines a wrap says so at its top, and every site
is a call a reader can find. --emit-checked prints an unsafe import line
for each name imported and an unsafe call line for each site.
The global spelling is refused (NL2456): the eight are called only through an
import of nish:unsafe. An index outside [0, xs.length) is undefined
behaviour, which is the whole of the trade. There is no flag that turns the
checks off: --unchecked-indexing and --wrapping are gone, and the CLI
refuses each with exit 2. readCString, readStruct and cErrno have no Node form,
because their CPtr or errno comes only from a declare function, which Node
cannot call.
Under Node
runtime/nish.mjs answers the import: the get and set are
xs[i] and xs[i] = v, the wrapping three are (a + b) | 0,
(a - b) | 0 and Math.imul on an i32 and BigInt.asIntN(64, …) on an
i64. A program that stays in range prints the same as natively.
The no-panic scope
Under --deny-panics or "nish".noPanic,
uncheckedGet and uncheckedSet are allowed unchecked sites, because
the import has already said that an index out of range is the author's to
rule out. readCString and readStruct are not: each tests its pointer and
panics with ffi-null on NULL, a site no proof removes, so the scope
refuses them. The wrapping three are not sites at all: they are defined for
every pair.
Functions
cErrno
The errno the most recent declare function call on this thread left:
a program that names cErrno zeroes errno just before every foreign
call and saves it just after, before any result marshalling. Native and
--profile wasi only.
const cErrno: () => i32
returnsi32The saved errno; 0 before any foreign call, and 0 after one that did not set it.
readCString
The NUL-terminated bytes at p, copied into a new string by
@nish.ffi.str, the scan-and-copy a string result of a
declare function uses, after a NULL test that panics with
ffi-null. It reads and allocates, and is native only.
const readCString: (p: CPtr) => string
pCPtrrequired
A pointer from a declare function; NULL panics. Undefined
behaviour unless it points at a live C string.
returnsstringA copy of the bytes before the NUL; C keeps its buffer.
readStruct
A copy of the C struct at p in a new instance of the declare class the
call's context names (const lc: Lconv = readStruct(localeconv())), so C
may free or overwrite its struct straight after. It reads and allocates,
and is native only.
const readStruct: <T>(p: CPtr) => T
pCPtrrequired
A pointer from a declare function. Undefined behaviour unless
it points at the layout's size of readable bytes.
returnsTA copy of the struct; C keeps its own.
uncheckedGet
xs[i] with no bounds check: the same GEP and load, with no len load,
no compare and no branch to the bounds panic. A call moves no length, so
an index proven before it stays proven after; it records no passed check
of its own.
const uncheckedGet: <T extends number>(
xs: readonly T[],
i: i32,
) => T
xsreadonly T[]required
An array of numbers: i32, i64, u8, u16, u32, u64,
f32 or f64 elements (NL2455 otherwise). A readonly array may be
read.
ii32required
The index, an i32. Undefined behaviour outside
[0, xs.length).
returnsTThe element at i.
uncheckedSet
xs[i] = v with no bounds check; a statement. It is a write of xs for
every rule that asks, the parallel-body rule included.
const uncheckedSet: <T extends number>(
xs: T[],
i: i32,
v: T,
) => void
xsT[]required
An array of numbers, as uncheckedGet takes, and not
readonly. An array field handed in is a value and is not stored
inline.
ii32required
The index, an i32. Undefined behaviour outside
[0, xs.length).
vTrequiredThe value to store, of the element type.
wrappingAdd
a + b as add with no nsw and no check: the two's-complement wrap,
defined for every pair (wrappingAdd(2147483647, 1) is -2147483648).
In a module constant's initialiser the call folds, wrapping.
const wrappingAdd: <T extends i32 | i64>(a: T, b: T) => T
aTrequired
An i32 or i64 (NL2454 otherwise; an unsigned operator
already wraps).
bTrequired
The same type as a (NL2400 otherwise). A bare literal takes
the other operand's type.
returnsTThe sum, wrapped to the operands' width.
wrappingMul
a * b as mul with no nsw and no check, wrapping
(wrappingMul(INT64_MAX, 2) is -2).
const wrappingMul: <T extends i32 | i64>(a: T, b: T) => T
aTrequiredAn i32 or i64.
bTrequiredThe same type as a.
returnsTThe product, wrapped to the operands' width.
wrappingSub
a - b as sub with no nsw and no check, wrapping.
const wrappingSub: <T extends i32 | i64>(a: T, b: T) => T
aTrequiredAn i32 or i64.
bTrequiredThe same type as a.
returnsTThe difference, wrapped to the operands' width.

