nomen-lang 0.0.16 → 0.0.18

package/core/System/Array.nm

@@ -160,6 +160,26 @@ pub struct Array<T>: Viewable {
 		```
 	}
 
+	// Bounds-checked accessors — the runtime-checked escape hatch for
+	// indices the constraint checker can't prove (see PERF.md gap 5). Unlike
+	// every other Array method these have Nomen-level bodies: the method-call
+	// receiver conventions for Array receivers (first-element pointer on
+	// aarch64, struct Array_<T>* on C) are passed through unchanged, and the
+	// bodies read self.length / self.at through them.
+	pub func at_or = (self, int index, T fallback, out T) {
+		if index >= 0 && index < self.length {
+			return self.at(index)
+		}
+		return fallback
+	}
+
+	pub func at_or_panic = (self, int index, out T) {
+		if index >= 0 && index < self.length {
+			return self.at(index)
+		}
+		panic("index out of range")
+	}
+
 	pub func at_end = (self, out T) {
 		```
 		#arch: c

package/core/System/Buffer.nm

@@ -356,7 +356,11 @@ pub struct Buffer<T> {
 		```
 	}
 
-	func load_T = (self, int i: i >= 0 && i < self.cap, out T) {
+	// `inline` splices the (width-folded at monomorphization) raw body at
+	// call sites — the load/store pair behind every container `.at`/`set` is
+	// the hottest path in data-heavy code, and the naked-inline path keeps it
+	// to a handful of instructions with no call overhead.
+	inline func load_T = (self, int i: i >= 0 && i < self.cap, out T) {
 		```
 		#arch: c
 		return ((T*)(unsigned long long)self->data)[i];
@@ -399,7 +403,7 @@ pub struct Buffer<T> {
 		```
 	}
 
-	func store_T = (ref self, int i: i >= 0 && i < self.cap, T val) {
+	inline func store_T = (ref self, int i: i >= 0 && i < self.cap, T val) {
 		```
 		#arch: c
 		((T*)(unsigned long long)self->data)[i] = val;
@@ -549,6 +553,78 @@ pub struct Buffer<T> {
 		```
 	}
 
+	// Move slot src into slot dst: overwrite dst with src's bytes and zero
+	// src, so exactly ONE slot owns the value afterwards. The
+	// ownership-transferring primitive behind backward-shift deletion
+	// (Map/Set.remove) — unlike store_T, which gives the slot its own deep
+	// copy and leaves the source slot intact, a shift transfers the source's
+	// heap pointers wholesale. For owning elements (string / value structs
+	// with string fields) the build replaces this body with a specialized
+	// version that also reclaims dst's previous value first (see
+	// owning_buffer_specialize.ts); this raw form is correct for
+	// trivially-destructible elements only.
+	inline func shift_T = (ref self, int dst: dst >= 0 && dst < self.cap, int src: src >= 0 && src < self.cap) {
+		```
+		#arch: c
+		T* _slots = (T*)(unsigned long long)self->data;
+		if (dst != src) {
+			_slots[dst] = _slots[src];
+			memset((void*)&_slots[src], 0, T_SIZE);
+		}
+		```
+		```
+		#arch: aarch64
+		// x19 = self, x1 = dst, x2 = src
+		ldr x4, [x19, #8]
+		mov x3, #T_SIZE
+		madd x5, x1, x3, x4
+		madd x6, x2, x3, x4
+		cmp x5, x6
+		b.eq .Lbuffer_shift_T_end
+		cmp x3, #8
+		b.gt .Lbuffer_shift_T_copy
+		// Width-matched move: an 8-byte access on a sub-8 element would
+		// clobber the following slot (and run past the slab's end).
+		cmp x3, #1
+		b.eq .Lbuffer_shift_T_1
+		cmp x3, #2
+		b.eq .Lbuffer_shift_T_2
+		cmp x3, #4
+		b.eq .Lbuffer_shift_T_4
+		ldr x7, [x6]
+		str x7, [x5]
+		str xzr, [x6]
+		b .Lbuffer_shift_T_end
+		.Lbuffer_shift_T_1:
+		ldrb w7, [x6]
+		strb w7, [x5]
+		strb wzr, [x6]
+		b .Lbuffer_shift_T_end
+		.Lbuffer_shift_T_2:
+		ldrh w7, [x6]
+		strh w7, [x5]
+		strh wzr, [x6]
+		b .Lbuffer_shift_T_end
+		.Lbuffer_shift_T_4:
+		ldr w7, [x6]
+		str w7, [x5]
+		str wzr, [x6]
+		b .Lbuffer_shift_T_end
+		.Lbuffer_shift_T_copy:
+		mov x0, x5
+		mov x1, x6
+		mov x2, x3
+		stp x5, x6, [sp, #-16]!
+		bl _memcpy
+		ldp x5, x6, [sp], #16
+		mov x0, x6
+		mov x1, #0
+		mov x2, x3
+		bl _memset
+		.Lbuffer_shift_T_end:
+		```
+	}
+
 	// A non-owning (ptr, len) slice [start, end) over this buffer's element
 	// storage, returned as a `view T`. It borrows from self: it may not outlive
 	// self's scope and is invalidated if self is reassigned. This is the single

package/core/System/ClassBuffer.nm

@@ -299,6 +299,51 @@ pub struct ClassBuffer<T> {
 		```
 	}
 
+	// Move slot src into slot dst: reclaim dst's previous instance (destroy +
+	// free), take over src's pointer, and zero src — exactly one slot owns the
+	// instance afterwards. The class-buffer counterpart of Buffer.shift_T,
+	// used by Map/Set.remove's backward-shift so shifting entries neither
+	// duplicates nor orphans owned instances.
+	func shift_T = (ref self, int dst: dst >= 0 && dst < self.cap, int src: src >= 0 && src < self.cap) {
+		```
+		#arch: c
+		long *slots = (long*)(unsigned long long)self->data;
+		if (dst != src) {
+			if (slots[dst]) {
+				T_destroy((void*)slots[dst]);
+				free((void*)slots[dst]);
+			}
+			slots[dst] = slots[src];
+			slots[src] = 0;
+		}
+		```
+		```
+		#arch: aarch64
+		stp x20, x21, [sp, #-16]!
+		str x22, [sp, #-16]!
+		ldr x9, [x19, #8]
+		lsl x3, x1, #3
+		add x20, x9, x3
+		lsl x3, x2, #3
+		add x21, x9, x3
+		cmp x20, x21
+		b.eq .Lcb_shift_T_done
+		ldr x0, [x20]
+		cbz x0, .Lcb_shift_T_move
+		mov x22, x0
+		bl T_destroy
+		mov x0, x22
+		bl _free
+		.Lcb_shift_T_move:
+		ldr x9, [x21]
+		str x9, [x20]
+		str xzr, [x21]
+		.Lcb_shift_T_done:
+		ldr x22, [sp], #16
+		ldp x20, x21, [sp], #16
+		```
+	}
+
 	// A non-owning (ptr, len) slice [start, end) over this buffer's class
 	// pointers, returned as a `view T` (T is a class, so each element is an
 	// 8-byte pointer). Borrows from self — invalidated on reassignment. Mirrors

package/core/System/LinkedList.nm

@@ -57,6 +57,22 @@ pub struct LinkedList<T>: Enumerable {
 		return self.values.load_T(idx)
 	}
 
+	// Bounds-checked access: `fallback` when idx is outside [0, self.count).
+	pub func at_or = (self, int idx, T fallback, out T) {
+		if idx >= 0 && idx < self.count {
+			return self.at(idx)
+		}
+		return fallback
+	}
+
+	// Bounds-checked access that traps when idx is outside [0, self.count).
+	pub func at_or_panic = (self, int idx, out T) {
+		if idx >= 0 && idx < self.count {
+			return self.at(idx)
+		}
+		panic("index out of range")
+	}
+
 	pub func length = (self, out int) {
 		return self.count
 	}

package/core/System/List.nm

@@ -27,10 +27,30 @@ pub struct List<T>: Viewable {
 		return self.items.move_T(idx)
 	}
 
-	pub func at = (self, int i: i >= 0 && i < self.length, out T) {
+	pub inline func at = (self, int i: i >= 0 && i < self.length, out T) {
 		return self.items.load_T(i)
 	}
 
+	// Bounds-checked access: `fallback` when i is outside [0, self.length) —
+	// for indices that can't be proven at compile time and out-of-range is an
+	// expected case.
+	pub func at_or = (self, int i, T fallback, out T) {
+		if i >= 0 && i < self.length {
+			return self.at(i)
+		}
+		return fallback
+	}
+
+	// Bounds-checked access that traps when i is outside [0, self.length) —
+	// for indices that can't be proven at compile time and out-of-range is a
+	// bug, not a case.
+	pub func at_or_panic = (self, int i, out T) {
+		if i >= 0 && i < self.length {
+			return self.at(i)
+		}
+		panic("index out of range")
+	}
+
 	// A non-owning `view T` over [start, end). Delegates to the backing Buffer's
 	// #arch slice primitive — no #arch code here. Borrows from self.
 	pub func slice = (self, int start: start >= 0, int end: end >= start, out view T) {

package/core/System/Map.nm

@@ -1,7 +1,12 @@
 /**
- * An ordered key-value map with `set`/`get`/`has`/`remove`. Keys must be
+ * An ordered key-value map with `set`/`get`/`get_or`/`has`/`remove`. Keys must be
  * `Hashable` (hashed to a `uint` via `key.hash()`) and `Equatable` (compared
  * with `==`); values may be any type.
+ *
+ * The capacity is always a power of two (initial 8, doubling on rehash), so
+ * bucket indexing is a mask (`hash & (cap - 1)`) instead of a division — and
+ * it is correct for negative hashes too: two's-complement `&` already lands
+ * in `[0, cap)`, which is why no negative adjustment is needed.
  **/
 pub struct Map<TK: Hashable + Equatable, TV> {
 	var length = 0
@@ -53,6 +58,34 @@ pub struct Map<TK: Hashable + Equatable, TV> {
 		return self.values.load_T(idx)
 	}
 
+	// Fused lookup-with-fallback: one probe instead of the `has` + `get`
+	// pair (which probes twice) for the common "default when missing" shape.
+	pub func get_or = (self, TK key, TV fallback, out TV) {
+		var int cap = self.keys.cap
+		if cap == 0 {
+			return fallback
+		}
+		var int idx = self.find_slot(key, cap)
+		if self.used.load(idx) == 0 {
+			return fallback
+		}
+		return self.values.load_T(idx)
+	}
+
+	// Lookup that traps when the key is absent — for when a missing key is
+	// a bug, not a case (and `get`'s 0-for-missing would be ambiguous).
+	pub func get_or_panic = (self, TK key, out TV) {
+		var int cap = self.keys.cap
+		if cap == 0 {
+			panic("key not found")
+		}
+		var int idx = self.find_slot(key, cap)
+		if self.used.load(idx) == 0 {
+			panic("key not found")
+		}
+		return self.values.load_T(idx)
+	}
+
 	pub func has = (self, TK key, out bool) {
 		var int cap = self.keys.cap
 		if cap == 0 {
@@ -91,10 +124,7 @@ pub struct Map<TK: Hashable + Equatable, TV> {
 			if self.used.load(k) == 0 {
 				break
 			}
-			var int home = (self.keys.load_T(k).hash() as int) % cap
-			if home < 0 {
-				home = home + cap
-			}
+			var int home = (self.keys.load_T(k).hash() as int) & (cap - 1)
 			var int dgap = gap - home
 			if dgap < 0 {
 				dgap = dgap + cap
@@ -104,8 +134,13 @@ pub struct Map<TK: Hashable + Equatable, TV> {
 				dk = dk + cap
 			}
 			if dgap < dk {
-				self.keys.store_T(gap, self.keys.load_T(k))
-				self.values.store_T(gap, self.values.load_T(k))
+				// shift_T (not store_T): transfers the entry's owned pointers
+				// wholesale and reclaims the displaced slot's value. store_T
+				// would strdup a fresh copy into gap while leaving the source
+				// slot's pointer stranded at the vacated slot — leaked once
+				// used.store marks it empty (the buffer destroy skips it).
+				self.keys.shift_T(gap, k)
+				self.values.shift_T(gap, k)
 				self.used.store(gap, 1)
 				gap = k
 			}
@@ -115,10 +150,9 @@ pub struct Map<TK: Hashable + Equatable, TV> {
 	}
 
 	func find_slot = (self, TK key, int cap, out int: out >= 0 && out < cap) {
-		var int idx = (key.hash() as int) % cap
-		if idx < 0 {
-			idx = idx + cap
-		}
+		// cap is a power of two, so this is `hash mod cap` via a mask —
+		// non-negative for any hash (two's complement), no adjustment.
+		var int idx = (key.hash() as int) & (cap - 1)
 		while self.used.load(idx) != 0 {
 			if self.keys.load_T(idx) == key {
 				return idx

package/core/System/Set.nm

@@ -2,6 +2,10 @@
  * An ordered set of unique values (`add`/`has`/`get`/`remove`). Elements must
  * be `Hashable` (hashed to a `uint` via `value.hash()`) and `Equatable`
  * (compared with `==`).
+ *
+ * The capacity is always a power of two (initial 8, doubling on rehash), so
+ * slot indexing is a mask (`hash & (cap - 1)`) — correct for negative hashes
+ * too (two's-complement `&` already lands in `[0, cap)`).
  **/
 pub struct Set<T: Hashable + Equatable> {
 	var length = 0
@@ -47,6 +51,33 @@ pub struct Set<T: Hashable + Equatable> {
 		return self.slots.load_T(idx)
 	}
 
+	// Membership lookup with a fallback value: `fallback` when the value is
+	// not in the set (one probe instead of the `has` + `get` pair).
+	pub func get_or = (self, T key, T fallback, out T) {
+		var int cap = self.slots.cap
+		if cap == 0 {
+			return fallback
+		}
+		var int idx = self.find_slot(key, cap)
+		if self.used.load(idx) == 0 {
+			return fallback
+		}
+		return self.slots.load_T(idx)
+	}
+
+	// Membership lookup that traps when the value is not in the set.
+	pub func get_or_panic = (self, T key, out T) {
+		var int cap = self.slots.cap
+		if cap == 0 {
+			panic("value not found in set")
+		}
+		var int idx = self.find_slot(key, cap)
+		if self.used.load(idx) == 0 {
+			panic("value not found in set")
+		}
+		return self.slots.load_T(idx)
+	}
+
 	pub func remove = (ref self, T value) {
 		var int cap = self.slots.cap
 		if cap == 0 {
@@ -76,10 +107,7 @@ pub struct Set<T: Hashable + Equatable> {
 			if self.used.load(k) == 0 {
 				break
 			}
-			var int home = (self.slots.load_T(k).hash() as int) % cap
-			if home < 0 {
-				home = home + cap
-			}
+			var int home = (self.slots.load_T(k).hash() as int) & (cap - 1)
 			var int dgap = gap - home
 			if dgap < 0 {
 				dgap = dgap + cap
@@ -89,7 +117,12 @@ pub struct Set<T: Hashable + Equatable> {
 				dk = dk + cap
 			}
 			if dgap < dk {
-				self.slots.store_T(gap, self.slots.load_T(k))
+				// shift_T (not store_T): transfers the entry wholesale and
+				// reclaims the displaced slot's value — store_T would strdup a
+				// fresh copy into gap while stranding the source slot's
+				// pointer at the vacated slot (leaked once used.store marks it
+				// empty; the buffer destroy skips unused slots).
+				self.slots.shift_T(gap, k)
 				self.used.store(gap, 1)
 				gap = k
 			}
@@ -99,10 +132,9 @@ pub struct Set<T: Hashable + Equatable> {
 	}
 
 	func find_slot = (self, T value, int cap, out int: out >= 0 && out < cap) {
-		var int idx = (value.hash() as int) % cap
-		if idx < 0 {
-			idx = idx + cap
-		}
+		// cap is a power of two: `hash mod cap` via a mask, non-negative
+		// for any hash — no adjustment needed.
+		var int idx = (value.hash() as int) & (cap - 1)
 		while self.used.load(idx) != 0 {
 			if self.slots.load_T(idx) == value {
 				return idx

package/core/System/String.nm

@@ -51,6 +51,24 @@ pub struct string: Stringable, Hashable, Equatable {
 		```
 	}
 
+	// Bounds-checked access: `fallback` when index is outside
+	// [0, self.length).
+	pub func at_or = (self, int index, char fallback, out char) {
+		if index >= 0 && index < self.length {
+			return self.at(index)
+		}
+		return fallback
+	}
+
+	// Bounds-checked access that traps when index is outside
+	// [0, self.length) — out-of-range is a bug, not a case.
+	pub func at_or_panic = (self, int index, out char) {
+		if index >= 0 && index < self.length {
+			return self.at(index)
+		}
+		panic("index out of range")
+	}
+
 	// A non-owning slice [start, end) into self's buffer. Returns a `view
 	// string` (ptr, len) that borrows from self: it may not outlive self's
 	// scope and is invalidated if self is reassigned. Use .to_string() to

package/core/docs/System/Array.md

@@ -7,6 +7,8 @@ A fixed-length array of values, created with a literal (`[1, 2, 3]`) and address
 **Members:**
 
 - `at(int index) -> T`
+- `at_or(int index, T fallback) -> T`
+- `at_or_panic(int index) -> T`
 - `first() -> T`
 - `set(int index, T value)`
 - `at_end() -> T`