`nupp.util`

Small types that belong to no larger facility.

local record Damage
    amount: integer
end

const set = new nupp.util.Bitset(128)
set:set(7)

const damage = nupp.util.newPool(Damage, 64)
damage:release(damage:acquire())

const store = nupp.util.newStore()
const theme: nupp.util.Key<string> = nupp.util.newKey("app.theme")
store:set(theme, "dark")

print(nupp.util.uuid4())

Each member is one type and the few functions that hand it out, reached by the type's name rather than by a module of its own. Bitset is a set of bit positions, Store is a bag of values indexed by typed Keys, and Pool leases cleared record instances from a free list. uuid4 and uuid7 generate identifiers, and fnv1a64 hashes bytes. try and tryWith run a function protected and answer (result, reason), which is the layout the or return suffix reads and pcall's own is not.

Unlike nupp.mem, which keeps every member a module of its own, these are re-exported here. Checked source still selects members independently, so using a bitset does not retain UUID support. uuid4 and uuid7 are the only members that resolve a host provider.

Module contents

Types

Type	Kind	Description
`Bitset`	record	A growable set of bit positions counting from 0.
`Key`	record	A typed identity for one value in a Store.
`Pool`	record	A pool of instances stamped with one record declaration.
`Store`	interface	An independent typed bag indexed by keys.

Functions

Function	Kind	Description
`fnv1a64`	function	Hashes bytes with FNV-1a over 64 bits, as sixteen hexadecimal digits.
`newKey`	function	Registers a new key, optionally under a name.
`newPool`	function	Creates a pool of instances of one record type.
`newStore`	function	Creates an empty store.
`try`	function	Runs a function under pcall, answering (result, raised) rather than (ok, ...), which is the layout or return reads.
`tryWith`	function	The same for xpcall, with the handler after the function: it runs before the stack unwinds and its result is the reason.
`uuid4`	function	Generates a random version 4 UUID, hyphenated and lowercase.
`uuid7`	function	Generates a time-ordered version 7 UUID, hyphenated and lowercase.

Values

Value	Kind	Description
`WORD_BITS`	variable	The bits one word of a Bitset holds.

Types#

`Bitset`record#

record Bitset ...

A growable set of bit positions counting from 0.

Members

Name	Kind	Description
`words`	field	Zero-based words, lowest bit first.
`capacity`	field	Words allocated.
`used`	field	An upper bound on the words that may hold a set bit: every word at or above it is zero.
`population`	field	The last resolved population, meaningful only when stale is false.
`stale`	field	Whether population needs recomputing.
`constructor`	constructor	Creates an empty set.
`reserve`	method	Grows storage so at least bits bits fit.
`set`	method	Adds a bit, growing when it is past the end.
`clear`	method	Removes a bit.
`get`	method	Whether a bit is set.
`setRange`	method	Adds every bit in the inclusive range, one word-mask write per word rather than one operation per bit.
`count`	method	How many bits are set.
`isEmpty`	method	Whether nothing is set.
`clearAll`	method	Removes every bit, keeping capacity so a set reused each frame stops allocating once it has reached its peak.
`setOnly`	method	Removes every bit, then adds exactly one.
`wordCount`	method	An upper bound on the words that may hold a set bit.
`wordAt`	method	One stored word.
`nextSetBit`	method	The lowest set position at or after from.
`positionsInto`	method	Writes every set position at or after from into target, lowest first.
`containsAll`	method	Whether every bit set in other is also set here.
`overlaps`	method	Whether at least one bit is set in both.
`disjoint`	method	Whether the two share no set bit.
`copyFrom`	method	Replaces these bits with a copy of other's.
`orWith`	method	Adds every bit set in other.
`andWith`	method	Keeps only the bits also set in other.
`andNotWith`	method	Removes every bit set in other.
`xorWith`	method	Keeps only the bits set in exactly one of the two.

`words`field#

words: uint32[?]

@private

Zero-based words, lowest bit first. Every word from used up to capacity is zero, which is the invariant every word loop relies on.

`capacity`field#

capacity: integer

@private

Words allocated.

`used`field#

used: integer

@private

An upper bound on the words that may hold a set bit: every word at or above it is zero. Deliberately not the exact high-water mark, because keeping that exact costs a backwards scan on every clear and every intersection.

`population`field#

population: integer

@private

The last resolved population, meaningful only when stale is false.

`stale`field#

stale: boolean

@private

Whether population needs recomputing. Set algebra marks it rather than paying two popcounts per word to keep a number most callers never read.

`constructor`constructor#

constructor: function constructor(self, capacityBits: integer?)

Creates an empty set.

Arguments

Name	Type	Description
`self`	`any`	the set being initialized
`capacityBits`	`integer?`	how many bits to allocate initially; setting a later position grows the set

Raises

Type	Condition
`string`	when capacityBits is more than 2^31

`reserve`method#

reserve: function reserve(self, bits: integer): nil

Grows storage so at least bits bits fit. Only grows, and never returns storage. A growth at least doubles, so repeated small growths stay amortised.

Arguments

Name	Type	Description
`self`	`any`
`bits`	`integer`	how many bits must fit

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when bits is NaN or more than 2^31

`set`method#

set: function set(self, index: integer): nil

Adds a bit, growing when it is past the end.

Arguments

Name	Type	Description
`self`	`any`
`index`	`integer`	the bit position, counting from 0

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when index is negative, past 2^31 - 1, or not an integer

`clear`method#

clear: function clear(self, index: integer): nil

Removes a bit. Never allocates, and never narrows the used-word bound, so it stays constant-time whichever bit it was.

Arguments

Name	Type	Description
`self`	`any`
`index`	`integer`	the bit position, counting from 0. One past the end, a negative one included, does nothing.

Returns

Type	Description
`nil`

`get`method#

get: function get(self, index: integer): boolean

Whether a bit is set.

Arguments

Name	Type	Description
`self`	`any`
`index`	`integer`	the bit position, counting from 0

Returns

Type	Description
`boolean`	false for any position past the end, so no bound check is needed at the call site

`setRange`method#

setRange: function setRange(self, low: integer, high: integer): nil

Adds every bit in the inclusive range, one word-mask write per word rather than one operation per bit.

Arguments

Name	Type	Description
`self`	`any`
`low`	`integer`	the first position added, counting from 0
`high`	`integer`	the last position added. Below `low` adds nothing, so an empty range needs no guard at the call site.

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when low is negative, when high is past 2^31 - 1, or when either is not an integer

`count`method#

count: function count(self): integer

How many bits are set. Resolves a pending recount, so a caller that reads it every frame pays for the set algebra it skipped; one that never reads it never pays.

Arguments

Name	Type	Description
`self`	`any`

Returns

Type	Description
`integer`	the number of set bits

`isEmpty`method#

isEmpty: function isEmpty(self): boolean

Whether nothing is set. Says nothing about capacity.

Arguments

Name	Type	Description
`self`	`any`

Returns

Type	Description
`boolean`	true when no bit is set

`clearAll`method#

clearAll: function clearAll(self): nil

Removes every bit, keeping capacity so a set reused each frame stops allocating once it has reached its peak.

Arguments

Name	Type	Description
`self`	`any`

Returns

Type	Description
`nil`

`setOnly`method#

setOnly: function setOnly(self, index: integer): nil

Removes every bit, then adds exactly one.

Arguments

Name	Type	Description
`self`	`any`
`index`	`integer`	the one position left set, counting from 0

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when index is negative, past 2^31 - 1, or not an integer; the set is left unchanged

`wordCount`method#

wordCount: function wordCount(self): integer

An upper bound on the words that may hold a set bit. Every word at or above it is zero, and it is not narrowed by clear or by intersection, so it may exceed the exact high-water mark.

Arguments

Name	Type	Description
`self`	`any`

Returns

Type	Description
`integer`	the number of words a word-at-a-time walk must visit

`wordAt`method#

wordAt: function wordAt(self, index: integer): integer

One stored word. Word w holds positions w * WORD_BITS through w * WORD_BITS + WORD_BITS - 1, lowest position first.

Arguments

Name	Type	Description
`self`	`any`
`index`	`integer`	a word index counting from 0, bounded by `wordCount`

Returns

Type	Description
`integer`	the word as a signed value, so one with its top bit set reads negative, and 0 for any index outside the bound

`nextSetBit`method#

nextSetBit: function nextSetBit(self, from: integer): integer

The lowest set position at or after from.

Stateless, so nested walks do not interfere and a mutation between calls cannot invalidate a walk in progress.

Arguments

Name	Type	Description
`self`	`any`
`from`	`integer`	the lowest position that may be returned, counting from 0

Returns

Type	Description
`integer`	that position, or -1 when there is none

`positionsInto`method#

positionsInto: function positionsInto(self, target: int32[?], capacity: integer, from: integer): integer, integer

Writes every set position at or after from into target, lowest first.

One call rather than one per position. A walk pays a call and a word read for every position it returns, which for a few thousand positions is most of what it costs; this reads each word once and clears the position it just reported out of a register.

target is a pointer and a count because that is what a native kernel takes. Filling it here rather than allocating keeps a per-frame extraction allocation-free, and leaves the boundary where a native one would sit.

Arguments

Name	Type	Description
`self`	`any`
`target`	`int32[?]`	where positions are written, indexed from 0
`capacity`	`integer`	how many positions `target` holds
`from`	`integer`	the lowest position that may be written, counting from 0

Returns

Type	Description
`integer`	how many positions were written, and the position to resume from when `target` filled first, or -1 when the set is exhausted
`integer`

Raises

Type	Condition
`string`	when capacity is negative

`containsAll`method#

containsAll: function containsAll(self, other: Bitset): boolean

Whether every bit set in other is also set here.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified

Returns

Type	Description
`boolean`	true when `other` is a subset. An empty `other` is contained by anything.

`overlaps`method#

overlaps: function overlaps(self, other: Bitset): boolean

Whether at least one bit is set in both. Early-exiting, and deliberately not an intersection followed by a count.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified, as is the receiver

Returns

Type	Description
`boolean`	true when the two share a set bit

`disjoint`method#

disjoint: function disjoint(self, other: Bitset): boolean

Whether the two share no set bit.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified, as is the receiver

Returns

Type	Description
`boolean`	the negation of `overlaps`

`copyFrom`method#

copyFrom: function copyFrom(self, other: Bitset): nil

Replaces these bits with a copy of other's. The two are independent afterwards, and this keeps its own capacity when that is the larger.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified

Returns

Type	Description
`nil`

`orWith`method#

orWith: function orWith(self, other: Bitset): nil

Adds every bit set in other.

One bitwise operation per word: the population is marked for recount rather than tracked, and there is no per-word test for whether the word changed, because that branch costs more than the write it saves.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified

Returns

Type	Description
`nil`

`andWith`method#

andWith: function andWith(self, other: Bitset): nil

Keeps only the bits also set in other.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified. Words beyond the ones it uses are cleared, so an empty `other` empties the receiver.

Returns

Type	Description
`nil`

`andNotWith`method#

andNotWith: function andNotWith(self, other: Bitset): nil

Removes every bit set in other.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified. Words beyond the ones it uses keep their bits, so an empty `other` changes nothing.

Returns

Type	Description
`nil`

`xorWith`method#

xorWith: function xorWith(self, other: Bitset): nil

Keeps only the bits set in exactly one of the two.

Arguments

Name	Type	Description
`self`	`any`
`other`	`Bitset`	read and not modified

Returns

Type	Description
`nil`

`Key`record#

record Key<T> ...

A typed identity for one value in a Store.

Type parameters

Name	Description
`T`

Members

Name	Kind	Description
`Step`	type	The step of nupp.util.Key.registered.
`id`	field
`name`	field
`find`	method	Finds a registered key by name.
`registered`	method	Walks every registered name, ascending by id.

`Step`type#

type Step = function(any, integer): (integer, string)

The step of nupp.util.Key.registered.

Terminating on nil is the generic for's business, so the surface type promises what the loop delivers rather than what the last call returns.

`id`field#

id: integer

@readonly

`name`field#

name: string?

@readonly

`find`method#

find: function find(name: string): unknown

Finds a registered key by name.

The registry knows the name's id and nothing about its type, so the result is unknown and the caller casts to the Key<T> it claims.

Arguments

Name	Type	Description
`name`	`string`	the registered name

Returns

Type	Description
`unknown`	the key, or nil when the name is not registered

`registered`method#

registered: function registered(): function(any, integer): (integer, string), any, integer

Walks every registered name, ascending by id.

The walk allocates nothing: the step is one shared function and the control variable is the id it last reported. The registry itself is never handed out, so nothing the loop is given can be used to reach or change it. An anonymous key registers no name and is not walked.

Returns

Type	Description
`function(any, integer): (integer, string)`	the step the loop calls
`any`	nothing to carry, since the ids are the whole state
`integer`	the id to resume after, 0 to start

`Pool`record#

record Pool<T is table> ...

A pool of instances stamped with one record declaration.

Type parameters

Name	Description
`T`

Members

Name	Kind	Description
`witness`	field
`capacity`	field	How many released instances the pool retains for reuse.
`freeList`	field
`freeCount`	field
`liveCount`	field
`liveValues`	field
`acquire`	method	Hands out an instance, from the free list or freshly stamped.
`release`	method	Clears an instance and returns it to the free list.
`reserve`	method	Stamps free instances until at least count are waiting.
`live`	method	How many instances are acquired and not yet released.
`free`	method	How many instances are waiting on the free list.
`reset`	method	Drops the free list.

`witness`field#

witness: any

@private@readonly

`capacity`field#

capacity: integer

@readonly

How many released instances the pool retains for reuse.

`freeList`field#

freeList: {T}

@private

`freeCount`field#

freeCount: integer

@private

`liveCount`field#

liveCount: integer

@private

`liveValues`field#

liveValues: {[any]: boolean}

@private

`acquire`method#

acquire: function(exclusive self: Pool<T>): T

Hands out an instance, from the free list or freshly stamped.

Arguments

Name	Type	Description
`exclusive self`	`Pool<T>`

Returns

Type	Description
`T`

`release`method#

release: function(exclusive self: Pool<T>, value: T): nil

Clears an instance and returns it to the free list.

Arguments

Name	Type	Description
`exclusive self`	`Pool<T>`
`value`	`T`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when nothing is live, or value was not stamped by the pool's declaration

`reserve`method#

reserve: function(exclusive self: Pool<T>, count: integer): nil

Stamps free instances until at least count are waiting.

Arguments

Name	Type	Description
`exclusive self`	`Pool<T>`
`count`	`integer`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when count is negative

`live`method#

live: function(self: Pool<T>): integer

How many instances are acquired and not yet released.

Arguments

Name	Type	Description
`self`	`Pool<T>`

Returns

Type	Description
`integer`

`free`method#

free: function(self: Pool<T>): integer

How many instances are waiting on the free list.

Arguments

Name	Type	Description
`self`	`Pool<T>`

Returns

Type	Description
`integer`

`reset`method#

reset: function(exclusive self: Pool<T>): nil

Drops the free list.

Arguments

Name	Type	Description
`exclusive self`	`Pool<T>`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when any instance is live

`Store`interface#

interface Store ...

An independent typed bag indexed by keys.

Members

Name	Kind	Description
`Step`	type	The step of nupp.util.Store.entries.
`get`	method	Answers the value held under a key.
`set`	method	Stores a non-nil value under a key.
`remove`	method	Removes the value held under a key.
`clear`	method	Removes every value without touching key registration.
`entries`	method	Walks every occupied key ascending by id, without its value.

`Step`type#

type Step = function(Store, integer): (integer, string?, string)

The step of nupp.util.Store.entries.

Terminating on nil is the generic for's business, so the surface type promises what the loop delivers rather than what the last call returns.

`get`method#

get: function<T>(self: Store, key: Key<T>): T?

Answers the value held under a key.

Arguments

Name	Type	Description
`self`	`Store`
`key`	`Key<T>`

Returns

Type	Description
`T?`

`set`method#

set: function<T>(self: Store, key: Key<T>, value: T): nil

Stores a non-nil value under a key.

Arguments

Name	Type	Description
`self`	`Store`
`key`	`Key<T>`
`value`	`T`

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when value is nil; use `nupp.util.Store.remove` to delete an entry

`remove`method#

remove: function<T>(self: Store, key: Key<T>): nil

Removes the value held under a key.

Arguments

Name	Type	Description
`self`	`Store`
`key`	`Key<T>`

Returns

Type	Description
`nil`

`clear`method#

clear: function(self: Store): nil

Removes every value without touching key registration.

Arguments

Name	Type	Description
`self`	`Store`

Returns

Type	Description
`nil`

`entries`method#

entries: function(
    borrows self: Store
): (function(Store, integer): (integer, string?, string), Store borrows (self), integer)

Walks every occupied key ascending by id, without its value.

Arguments

Name	Type	Description
`borrows self`	`Store`

Returns

Type	Description
`function(Store, integer): (integer, string?, string)`
`Store borrows (self)`
`integer`

Functions#

`fnv1a64`function#

function fnv1a64(borrows value: string | ByteView): string

Hashes bytes with FNV-1a over 64 bits, as sixteen hexadecimal digits.

Arguments

Name	Type	Description
`borrows value`	`string \| ByteView`	the bytes to hash

Returns

Type	Description
`string`	the hash, as sixteen lowercase hexadecimal digits

`newKey`function#

function newKey<T>(name: string?): Key<T>

Registers a new key, optionally under a name.

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`name`	`string?`	the opaque name to register, or nil for an anonymous key

Returns

Type	Description
`Key<T>`	the key

Raises

Type	Condition
`string`	when the name is empty or already registered, before an id is used

`newPool`function#

function newPool<T is table>(witness: Type<T>, capacity: integer?): pool.Pool<T>

Creates a pool of instances of one record type.

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`witness`	`Type<T>`	the record declaration, whose metatable stamps every instance
`capacity`	`integer?`	how many released instances to retain, 32 when omitted

Returns

Type	Description
`pool.Pool<T>`	the pool, warmed to capacity

Raises

Type	Condition
`string`	when capacity is negative

`newStore`function#

function newStore(): Store

Creates an empty store.

Returns

Type	Description
`Store`	the store

`try`function#

function try<R, A...>(f: function(A...): R, ...: A...): R?, unknown

Runs a function under pcall, answering (result, raised) rather than (ok, ...), which is the layout or return reads.

Type parameters

Name	Description
`R`
`A`

Arguments

Name	Type	Description
`f`	`function(A...): R`	the function to run protected
`...`	`A...`	its arguments

Returns

Type	Description
`R?`	its result, or nil when it raised
`unknown`	the raised value, or nil when it did not

`tryWith`function#

function tryWith<R, E, A...>(f: function(A...): R, handler: function(any): E, ...: A...): R?, E?

The same for xpcall, with the handler after the function: it runs before the stack unwinds and its result is the reason.

Type parameters

Name	Description
`R`
`E`
`A`

Arguments

Name	Type	Description
`f`	`function(A...): R`	the function to run protected
`handler`	`function(any): E`	what to make of a raised value
`...`	`A...`	the function's arguments

Returns

Type	Description
`R?`	its result, or nil when it raised
`E?`	what `handler` made of the raised value, or nil when it did not raise

`uuid4`function#

function uuid4(): string

Generates a random version 4 UUID, hyphenated and lowercase.

Returns

Type	Description
`string`	the UUID, hyphenated and lowercase

Raises

Type	Condition
`string`	when the provider fails or returns a malformed UUID

`uuid7`function#

function uuid7(): string

Generates a time-ordered version 7 UUID, hyphenated and lowercase.

Ordered to the millisecond only: two made in the same millisecond carry random bits after the timestamp, so they compare in either order. It uses no RFC 9562 monotonic counter.

Returns

Type	Description
`string`	the UUID, hyphenated and lowercase

Raises

Type	Condition
`string`	when the provider fails or returns a malformed UUID

Values#

`WORD_BITS`variable#

const WORD_BITS

The bits one word of a Bitset holds.

nupp.util

Module contents

Types

Functions

Values

Types#

Bitsetrecord#

Members

wordsfield#

capacityfield#

usedfield#

populationfield#

stalefield#

constructorconstructor#

Arguments

Raises

reservemethod#

Arguments

Returns

Raises

setmethod#

Arguments

Returns

Raises

clearmethod#

Arguments

Returns

getmethod#

Arguments

Returns

setRangemethod#

Arguments

Returns

Raises

countmethod#

Arguments

Returns

isEmptymethod#

Arguments

Returns

clearAllmethod#

Arguments

Returns

setOnlymethod#

Arguments

Returns

Raises

wordCountmethod#

Arguments

Returns

wordAtmethod#

Arguments

Returns

nextSetBitmethod#

Arguments

Returns

positionsIntomethod#

Arguments

Returns

Raises

containsAllmethod#

Arguments

Returns

overlapsmethod#

Arguments

Returns

disjointmethod#

Arguments

Returns

copyFrommethod#

Arguments

Returns

orWithmethod#

Arguments

Returns

andWithmethod#

Arguments

Returns

andNotWithmethod#

Arguments

`nupp.util`

`Bitset`record#

`words`field#

`capacity`field#

`used`field#

`population`field#

`stale`field#

`constructor`constructor#

`reserve`method#

`set`method#

`clear`method#

`get`method#

`setRange`method#

`count`method#

`isEmpty`method#

`clearAll`method#

`setOnly`method#

`wordCount`method#

`wordAt`method#

`nextSetBit`method#

`positionsInto`method#

`containsAll`method#

`overlaps`method#

`disjoint`method#

`copyFrom`method#

`orWith`method#

`andWith`method#

`andNotWith`method#

`xorWith`method#

`Key`record#

`Step`type#

`id`field#

`name`field#

`find`method#

`registered`method#

`Pool`record#

`witness`field#

`capacity`field#

`freeList`field#

`freeCount`field#

`liveCount`field#

`liveValues`field#

`acquire`method#

`release`method#

`reserve`method#

`live`method#

`free`method#

`reset`method#

`Store`interface#

`Step`type#

`get`method#

`set`method#

`remove`method#

`clear`method#

`entries`method#

`fnv1a64`function#

`newKey`function#