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));
};

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.

Rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#nishunsafe-unchecked-access-and-defined-wrapping

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
returnsi32

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

returnsstring

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

returnsT

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

returnsT

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

vTrequired

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

returnsT

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

An i32 or i64.

bTrequired

The same type as a.

returnsT

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

An i32 or i64.

bTrequired

The same type as a.

returnsT

The difference, wrapped to the operands' width.