Skip to content

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_persistent to #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_persistent to #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_persistent to #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_persistent to #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_persistent to #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_persistent to #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, and adt.list_k scratch 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_persistent to #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_persistent to #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

See Also