Adt¶
ADT
Import¶
import "_IVLS/std-library/ksp/data-structures/imports/adt.ksp"Overview¶
ADT
LIBRARY MODULE
Core abstract data type collection: queue, stack, list, and heap.
Provides four general-purpose integer data structures for use in KSP scripts. Each structure is instantiated by calling its Create macro (e.g. adt.CreateQueue) which declares the backing storage and metadata variables. A paired Functions macro (e.g. adt.QueueFunctions) then generates the full operation set as inline functions namespaced under the instance name. Three persistence variants are available for each structure: transient, snapshot-persistent (make_persistent), and instrument-persistent (make_instr_persistent).
Structures:
- Queue — FIFO ring buffer with O(1) push/pop
- Stack — FILO array with O(1) push/pop
- List — Random-access array with O(N) insertion/deletion
- Heap — Priority queue with O(log N) push/pop; supports min and max variants
API¶
Macros¶
| Name | Description |
|---|---|
adt.CreateHeap(#name#, #size#, #type#) |
Constructs an integer heap (priority queue). |
adt.CreateHeapInstPers(#name#, #size#, #type#) |
Constructs an instrument-persistent heap. |
adt.CreateHeapPers(#name#, #size#, #type#) |
Constructs a snapshot-persistent heap. |
adt.CreateList(#name#, #size#) |
Constructs an integer list with random access support. |
adt.CreateListInstPers(#name#, #size#) |
Constructs an instrument-persistent list. |
adt.CreateListPers(#name#, #size#) |
Constructs a snapshot-persistent list. |
adt.CreateQueue(#name#, #size#) |
Constructs an integer queue with ring buffer storage. |
adt.CreateQueueInstPers(#name#, #size#) |
Constructs an instrument-persistent queue. |
adt.CreateQueuePers(#name#, #size#) |
Constructs a snapshot-persistent queue. |
adt.CreateStack(#name#, #size#) |
Constructs an integer stack. |
adt.CreateStackInstPers(#name#, #size#) |
Constructs an instrument-persistent stack. |
adt.CreateStackPers(#name#, #size#) |
Constructs a snapshot-persistent stack. |
adt.HeapFunctions(#name#) |
Generates all operational functions for a heap instance. |
adt.List.CoupledSort(#source#, #target#, #order#) |
Sorts source list and mirrors all swaps in target list for maintaining parallel ... |
adt.ListFunctions(#name#) |
Generates all operational functions for a list instance. |
adt.QueueFunctions(#name#) |
Generates all operational functions for a queue instance. |
adt.StackFunctions(#name#) |
Generates all operational functions for a stack instance. |
Functions¶
| Name | Description |
|---|---|
#name#.append(element) |
Adds an element to the end of the list. |
#name#.append.fast(element) |
Inserts element at end without capacity checking. |
#name#.clear() |
Resets the queue to empty state. |
#name#.clear() |
Resets the stack to empty state. |
#name#.clear() |
Resets the list to empty state. |
#name#.clear() |
Resets the heap to empty state. |
#name#.delete(idx) |
Removes the element at a specific index and shifts remaining elements. |
#name#.delete_item(item) |
Removes the first occurrence of a value from the list. |
#name#.get_next_re() -> result |
Returns the next read pointer index with wraparound. |
#name#.get_next_wr() -> result |
Returns the next write pointer index with wraparound. |
#name#.get_num_children(node) -> result |
Returns the number of children for a given heap node. |
#name#.get_parent_idx(node) -> result |
Returns the parent index for a given heap node. |
#name#.insert(element, idx) |
Inserts an element at a specific index in the list. |
#name#.peek() -> result |
Returns the front element without removing it. |
#name#.peek() -> result |
Returns the top element without removing it. |
#name#.peek(idx) -> result |
Returns an element at a specific index without removing it. |
#name#.peek() -> result |
Returns the root element without removing it. |
#name#.peek.fast() -> result |
Returns element at read pointer without empty checking. |
#name#.peek_end() -> result |
Returns the last element without removing it. |
#name#.pop() -> result |
Returns and removes the front element from the queue. |
#name#.pop() -> result |
Returns and removes the top element from the stack. |
#name#.pop() -> result |
Returns and removes the last element from the list. |
#name#.pop() -> result |
Returns and removes the root element, then restores heap order. |
#name#.pop.fast() -> result |
Returns and removes element without empty checking. |
#name#.pop.fast() -> result |
Returns and removes top element without empty checking. |
#name#.push(element) |
Adds an element to the back of the queue. |
#name#.push(element) |
Adds an element to the top of the stack. |
#name#.push(element) |
Adds an element to the heap and restores heap order. |
#name#.push.fast(element) |
Inserts element without capacity checking. |
#name#.push.fast(element) |
Inserts element without capacity checking. |
#name#.remove(idx) |
Removes element at specified index and shifts remaining elements. |
#name#.remove.fast(idx) |
Removes element at specified index without validation. |
#name#.retrieve(idx) -> result |
Returns and removes the element at a specific index. |
#name#.retrieve.fast(idx) -> result |
Returns and removes element at index without validation. |
#name#.retrieve_item(item) -> result |
Finds the first occurrence of a value, removes it, and returns its index. |
#name#.search(el) -> result |
Searches for first occurrence of element in queue. |
#name#.search(el) -> result |
Searches for first occurrence of element in stack. |
#name#.search(el) -> result |
Searches for first occurrence of element in list. |
#name#.sift_down(node) |
Sifts a node downward through the heap to restore heap order. |
#name#.sift_up(node) |
Sifts a node upward through the heap to restore heap order. |
(Ring) Queue¶
adt.CreateQueue(#name#, #size#)¶
Constructs an integer queue with ring buffer storage.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Ring buffer storage |
#name#.write_p |
int | Write pointer index |
#name#.read_p |
int | Read pointer index |
#name#.size |
int | Queue capacity |
#name#.count |
int | Current element count |
adt.CreateQueuePers(#name#, #size#)¶
Constructs a snapshot-persistent queue.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Ring buffer storage |
#name#.write_p |
int | Write pointer index |
#name#.read_p |
int | Read pointer index |
#name#.size |
int | Queue capacity |
#name#.count |
int | Current element count |
- Applies
make_persistentto#name#,#name#.write_p,#name#.read_p, and#name#.count
Notes: Values are stored in Kontakt snapshots and overridden when snapshots change.
adt.CreateQueueInstPers(#name#, #size#)¶
Constructs an instrument-persistent queue.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Ring buffer storage |
#name#.write_p |
int | Write pointer index |
#name#.read_p |
int | Read pointer index |
#name#.size |
int | Queue capacity |
#name#.count |
int | Current element count |
- Applies
make_instr_persistentto#name#,#name#.write_p,#name#.read_p, and#name#.count
Notes: Values are saved into the NKI on manual save, but not stored per snapshot.
adt.QueueFunctions(#name#)¶
Generates all operational functions for a queue instance.
Preconditions: Must be called after a CreateQueue macro for the same instance name.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#.get_next_wr() |
function | Returns next write pointer with wraparound |
#name#.get_next_re() |
function | Returns next read pointer with wraparound |
#name#.push(element) |
function | Adds element to back with validation |
#name#.push.fast(element) |
function | Adds element without validation |
#name#.peek() |
function | Returns front element with validation |
#name#.peek.fast() |
function | Returns front element without validation |
#name#.pop() |
function | Removes and returns front element with validation |
#name#.pop.fast() |
function | Removes and returns front element without validation |
#name#.remove(idx) |
function | Removes element at index with validation |
#name#.remove.fast(idx) |
function | Removes element at index without validation |
#name#.search(el) |
function | Searches for element, returns index or -1 |
#name#.clear() |
function | Resets queue to empty state |
#name#.get_next_wr() -> result¶
Returns the next write pointer index with wraparound.
Returns: result — next write pointer index
#name#.get_next_re() -> result¶
Returns the next read pointer index with wraparound.
Returns: result — next read pointer index
#name#.push(element)¶
Adds an element to the back of the queue.
Preconditions: Queue must not be full.
| Parameter | Description |
|---|---|
element |
element to put in the queue |
Post: Inserts the element and advances the write pointer. Prints an error and skips the write if the queue is full.
#name#.push.fast(element)¶
Inserts element without capacity checking.
| Parameter | Description |
|---|---|
element |
element to put in the queue |
Post: Inserts the element and increments the write pointer without validation.
#name#.peek() -> result¶
Returns the front element without removing it.
Preconditions: Queue must not be empty.
Returns: result — front element, or adt.TASK_FAIL if the queue is empty
#name#.peek.fast() -> result¶
Returns element at read pointer without empty checking.
Returns: result — element at read pointer
#name#.pop() -> result¶
Returns and removes the front element from the queue.
Preconditions: Queue must not be empty.
Returns: result — front element, or adt.TASK_FAIL if the queue is empty
#name#.pop.fast() -> result¶
Returns and removes element without empty checking.
Returns: result — element at read pointer, now removed from queue
#name#.remove(idx)¶
Removes element at specified index and shifts remaining elements.
| Parameter | Description |
|---|---|
idx |
index of element to remove |
Post: Element at index is removed and all subsequent elements are shifted backward. Validates index and prints error messages if index is invalid or points to unused space.
Notes: Depends on math.mod_loop for circular buffer index wrapping.
#name#.remove.fast(idx)¶
Removes element at specified index without validation.
| Parameter | Description |
|---|---|
idx |
index of element to remove |
Post: Element at index is removed and all subsequent elements are shifted backward without bounds checking.
#name#.search(el) -> result¶
Searches for first occurrence of element in queue.
| Parameter | Description |
|---|---|
el |
element to search for |
Returns: result — index of first occurrence, or -1 if not found
#name#.clear()¶
Resets the queue to empty state.
Post: Count and all pointers are reset to zero.
Stack¶
adt.CreateStack(#name#, #size#)¶
Constructs an integer stack.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Stack storage |
#name#.size |
int | Stack capacity |
#name#.count |
int | Current element count |
adt.CreateStackPers(#name#, #size#)¶
Constructs a snapshot-persistent stack.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Stack storage |
#name#.size |
int | Stack capacity |
#name#.count |
int | Current element count |
- Applies
make_persistentto#name#and#name#.count
Notes: Values are stored in Kontakt snapshots and overridden when snapshots change.
adt.CreateStackInstPers(#name#, #size#)¶
Constructs an instrument-persistent stack.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Stack storage |
#name#.size |
int | Stack capacity |
#name#.count |
int | Current element count |
- Applies
make_instr_persistentto#name#and#name#.count
Notes: Values are saved into the NKI on manual save, but not stored per snapshot.
adt.StackFunctions(#name#)¶
Generates all operational functions for a stack instance.
Preconditions: Must be called after a CreateStack macro for the same instance name.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#.push(element) |
function | Adds element to top with validation |
#name#.push.fast(element) |
function | Adds element without validation |
#name#.peek() |
function | Returns top element with validation |
#name#.pop() |
function | Removes and returns top element with validation |
#name#.pop.fast() |
function | Removes and returns top element without validation |
#name#.search(el) |
function | Searches for element, returns index or -1 |
#name#.clear() |
function | Resets stack to empty state |
#name#.push(element)¶
Adds an element to the top of the stack.
Preconditions: Stack must not be full.
| Parameter | Description |
|---|---|
element |
element to put in the stack |
Post: Inserts the element and increments the count. Prints an error and skips the write if the stack is full.
#name#.push.fast(element)¶
Inserts element without capacity checking.
| Parameter | Description |
|---|---|
element |
element to put in the stack |
Post: Inserts the element and increments the count without validation.
#name#.peek() -> result¶
Returns the top element without removing it.
Preconditions: Stack must not be empty.
Returns: result — top element, or adt.TASK_FAIL if the stack is empty
#name#.pop() -> result¶
Returns and removes the top element from the stack.
Preconditions: Stack must not be empty.
Returns: result — top element, or adt.TASK_FAIL if the stack is empty
#name#.pop.fast() -> result¶
Returns and removes top element without empty checking.
Returns: result — top element, now removed from stack
#name#.search(el) -> result¶
Searches for first occurrence of element in stack.
| Parameter | Description |
|---|---|
el |
element to search for |
Returns: result — index of first occurrence, or -1 if not found
#name#.clear()¶
Resets the stack to empty state.
Post: Count is reset to zero.
List¶
adt.CreateList(#name#, #size#)¶
Constructs an integer list with random access support.
| Parameter | Description |
|---|---|
#name# |
list instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | List storage |
#name#.size |
int | List capacity |
#name#.count |
int | Current element count |
adt.CreateListPers(#name#, #size#)¶
Constructs a snapshot-persistent list.
| Parameter | Description |
|---|---|
#name# |
list instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | List storage |
#name#.size |
int | List capacity |
#name#.count |
int | Current element count |
- Applies
make_persistentto#name#and#name#.count
Notes: Values are stored in Kontakt snapshots and overridden when snapshots change.
adt.CreateListInstPers(#name#, #size#)¶
Constructs an instrument-persistent list.
| Parameter | Description |
|---|---|
#name# |
list instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | List storage |
#name#.size |
int | List capacity |
#name#.count |
int | Current element count |
- Applies
make_instr_persistentto#name#and#name#.count
Notes: Values are saved into the NKI on manual save, but not stored per snapshot.
adt.ListFunctions(#name#)¶
Generates all operational functions for a list instance.
Preconditions: Must be called after a CreateList macro for the same instance name.
| Parameter | Description |
|---|---|
#name# |
list instance name |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#.append(element) |
function | Adds element to end with validation |
#name#.append.fast(element) |
function | Adds element to end without validation |
#name#.insert(element, idx) |
function | Inserts element at index with validation |
#name#.peek(idx) |
function | Returns element at index with validation |
#name#.peek_end() |
function | Returns last element without validation |
#name#.pop() |
function | Removes and returns last element |
#name#.retrieve(idx) |
function | Removes and returns element at index with validation |
#name#.retrieve.fast(idx) |
function | Removes and returns element without validation |
#name#.retrieve_item(item) |
function | Finds, removes, and returns index of item |
#name#.delete(idx) |
function | Removes element at index without validation |
#name#.delete_item(item) |
function | Removes first occurrence of item |
#name#.search(el) |
function | Searches for element, returns index or -1 |
#name#.clear() |
function | Resets list to empty state |
#name#.append(element)¶
Adds an element to the end of the list.
Preconditions: List must not be full.
| Parameter | Description |
|---|---|
element |
element to put in the list |
Post: Inserts the element at the end and increments the count. Prints an error and skips the write if the list is full.
#name#.append.fast(element)¶
Inserts element at end without capacity checking.
| Parameter | Description |
|---|---|
element |
element to put in the list |
Post: Inserts the element at the end and increments the count without validation.
#name#.insert(element, idx)¶
Inserts an element at a specific index in the list.
Preconditions: The list must not be full.
| Parameter | Description |
|---|---|
element |
element to insert |
idx |
the desired index for the element |
Post: Inserts the element at the specified index, shifting subsequent elements forward. Prints an error and skips the write if the list is full, the index is negative, or the index exceeds the count.
#name#.peek(idx) -> result¶
Returns an element at a specific index without removing it.
Preconditions: The list must not be empty.
| Parameter | Description |
|---|---|
idx |
the index of the element to peek |
Returns: result — element at the specified index, or adt.TASK_FAIL if the list is empty, the index is negative, or the index exceeds the count
#name#.peek_end() -> result¶
Returns the last element without removing it.
Preconditions: The list must not be empty.
Returns: result — last element in the list
#name#.pop() -> result¶
Returns and removes the last element from the list.
Preconditions: The list must not be empty.
Returns: result — last element, or adt.TASK_FAIL if the list is empty
#name#.retrieve(idx) -> result¶
Returns and removes the element at a specific index.
Preconditions: The list must not be empty.
| Parameter | Description |
|---|---|
idx |
the index of the element to retrieve |
Returns: result — element at the specified index, or adt.TASK_FAIL if the list is empty or the index is invalid
#name#.retrieve.fast(idx) -> result¶
Returns and removes element at index without validation.
| Parameter | Description |
|---|---|
idx |
index of element to retrieve |
Returns: result — element at specified index, now removed from list
#name#.retrieve_item(item) -> result¶
Finds the first occurrence of a value, removes it, and returns its index.
Preconditions: The list must not be empty.
| Parameter | Description |
|---|---|
item |
the value to find and remove |
Returns: result — index of the removed item, or -1 if not found
#name#.delete(idx)¶
Removes the element at a specific index and shifts remaining elements.
Preconditions: The list must not be empty.
| Parameter | Description |
|---|---|
idx |
the index of the element to delete |
Post: Element at idx is removed and all subsequent elements are shifted backward.
#name#.delete_item(item)¶
Removes the first occurrence of a value from the list.
Preconditions: The list must not be empty.
| Parameter | Description |
|---|---|
item |
the value to find and delete |
Post: First occurrence of item is removed and subsequent elements are shifted
backward. No change if the value is not found.
#name#.search(el) -> result¶
Searches for first occurrence of element in list.
| Parameter | Description |
|---|---|
el |
element to search for |
Returns: result — index of first occurrence, or -1 if not found
#name#.clear()¶
Resets the list to empty state.
Post: Count is reset to zero.
adt.List.CoupledSort(#source#, #target#, #order#)¶
Sorts source list and mirrors all swaps in target list for maintaining parallel arrays.
| Parameter | Description |
|---|---|
#source# |
list to sort |
#target# |
list that mirrors source's swaps |
#order# |
1 for ascending, 0 for descending |
Post: Both lists are modified. Source list is sorted according to order, and target list has all swaps mirrored to maintain element correspondence.
Side effects:
- Modifies
adt.list_i,adt.list_j, andadt.list_kscratch variables
Notes: Uses insertion sort algorithm. Useful for maintaining key-value pairs or other parallel data structures.
Heap¶
adt.CreateHeap(#name#, #size#, #type#)¶
Constructs an integer heap (priority queue).
| Parameter | Description |
|---|---|
#name# |
heap instance name |
#size# |
maximum capacity |
#type# |
heap type (adt.HEAP_TYPE_MIN or adt.HEAP_TYPE_MAX) |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Heap storage |
#name#.swap |
int | Temporary swap variable for sifting |
#name#.size |
int | Heap capacity |
#name#.count |
int | Current element count |
#name#.heap_type |
int | Heap type (min or max) |
adt.CreateHeapPers(#name#, #size#, #type#)¶
Constructs a snapshot-persistent heap.
| Parameter | Description |
|---|---|
#name# |
heap instance name |
#size# |
maximum capacity |
#type# |
heap type (adt.HEAP_TYPE_MIN or adt.HEAP_TYPE_MAX) |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Heap storage |
#name#.swap |
int | Temporary swap variable for sifting |
#name#.size |
int | Heap capacity |
#name#.count |
int | Current element count |
#name#.heap_type |
int | Heap type (min or max) |
- Applies
make_persistentto#name#and#name#.count
Notes: Values are stored in Kontakt snapshots and overridden when snapshots change.
adt.CreateHeapInstPers(#name#, #size#, #type#)¶
Constructs an instrument-persistent heap.
| Parameter | Description |
|---|---|
#name# |
heap instance name |
#size# |
maximum capacity |
#type# |
heap type (adt.HEAP_TYPE_MIN or adt.HEAP_TYPE_MAX) |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#size#] |
int[] | Heap storage |
#name#.swap |
int | Temporary swap variable for sifting |
#name#.size |
int | Heap capacity |
#name#.count |
int | Current element count |
#name#.heap_type |
int | Heap type (min or max) |
- Applies
make_instr_persistentto#name#and#name#.count
Notes: Values are saved into the NKI on manual save, but not stored per snapshot.
adt.HeapFunctions(#name#)¶
Generates all operational functions for a heap instance.
Preconditions: Must be called after a CreateHeap macro for the same instance name.
| Parameter | Description |
|---|---|
#name# |
heap instance name |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#.push(element) |
function | Inserts element and sifts upward with validation |
#name#.peek() |
function | Returns root element with validation |
#name#.pop() |
function | Removes and returns root element with validation |
#name#.get_num_children(node) |
function | Returns child count for node (internal use) |
#name#.get_parent_idx(node) |
function | Returns parent index for node |
#name#.sift_up(node) |
function | Sifts node upward to restore heap order (internal use) |
#name#.sift_down(node) |
function | Sifts node downward to restore heap order (internal use) |
#name#.clear() |
function | Resets heap to empty state |
#name#.push(element)¶
Adds an element to the heap and restores heap order.
Preconditions: Heap must not be full.
| Parameter | Description |
|---|---|
element |
element to put in the heap |
Post: Inserts the element and sifts it upward to its correct position. Prints an error and skips the write if the heap is full.
#name#.peek() -> result¶
Returns the root element without removing it.
Preconditions: The heap must not be empty.
Returns: result — root element (min or max depending on heap type), or adt.TASK_FAIL if the heap is empty
#name#.pop() -> result¶
Returns and removes the root element, then restores heap order.
Preconditions: The heap must not be empty.
Returns: result — root element, or adt.TASK_FAIL if the heap is empty. Moves the last element to the root and sifts it down.
#name#.get_num_children(node) -> result¶
Returns the number of children for a given heap node.
Preconditions: Internal use only.
| Parameter | Description |
|---|---|
node |
index of the node in the heap array |
Returns: result — number of children (0, 1, or 2)
#name#.get_parent_idx(node) -> result¶
Returns the parent index for a given heap node.
Preconditions: Node index must be greater than or equal to 0.
| Parameter | Description |
|---|---|
node |
index of the node in the heap array |
Returns: result — parent index of the node
#name#.sift_up(node)¶
Sifts a node upward through the heap to restore heap order.
Preconditions: Internal use only. Node must be a valid index.
| Parameter | Description |
|---|---|
node |
index of node to sift |
Post: The node is repeatedly swapped with its parent until heap order is restored. Prints an error if the node index is out of bounds.
#name#.sift_down(node)¶
Sifts a node downward through the heap to restore heap order.
Preconditions: Internal use only. Node must be a valid index.
| Parameter | Description |
|---|---|
node |
index of node to sift |
Post: The node is repeatedly swapped with its dominant child until heap order is restored. Prints an error if the node index is out of bounds.
#name#.clear()¶
Resets the heap to empty state.
Post: Count is reset to zero.
Example¶
// TODO: Add usage example