Adt 2D¶
LIBRARY MODULE
Import¶
import "_IVLS/std-library/ksp/data-structures/imports/adt-2d.ksp"Overview¶
LIBRARY MODULE
2D variants of the core abstract data type collections: queue, stack, and list.
Each data structure is organized as a set of independent rows, allowing a single ADT instance to act as multiple parallel queues, stacks, or lists. All Create macros declare the backing storage array and per-row metadata arrays. Corresponding Functions macros generate the full operation set (push, pop, peek, search, clear, etc.) as inline functions namespaced under the instance name.
For single-row usage the standard 1D ADT variants in adt.ksp are preferred.
API¶
Macros¶
| Name | Description |
|---|---|
adt.2DList.Copy_Row(#source#, #target#, #row#) |
Copies all data from specified row of source to same row of target. |
adt.2DList.CoupledSort_1to1(#source#, #target#, #order#, #row#) |
Sorts specified row of source 2DList and mirrors all swaps in target 2DList row. |
adt.2DListFunctions(#name#) |
Generates all operational functions for a 2D list instance. |
adt.2DQueueFunctions(#name#) |
Generates all operational functions for a 2D queue instance. |
adt.2DStackFunctions(#name#) |
Generates all operational functions for a 2D stack instance. |
adt.Create2DList(#name#, #row1#, #row2#) |
Constructs a 2D integer list with random access support. |
adt.Create2DListInstPers(#name#, #size#) |
Constructs an instrument-persistent 2D list. |
adt.Create2DListPers(#name#, #size#) |
Constructs a snapshot-persistent 2D list. |
adt.Create2DQueue(#name#, #row#, #size#) |
Constructs a 2D integer queue with ring buffer storage per row. |
adt.Create2DQueueInstPers(#name#, #size#) |
Constructs an instrument-persistent 2D queue. |
adt.Create2DQueuePers(#name#, #row#, #size#) |
Constructs a snapshot-persistent 2D queue. |
adt.Create2DStack(#name#, #row#, #size#) |
Constructs a 2D integer stack. |
adt.Create2DStackInstPers(#name#, #row#, #size#) |
Constructs an instrument-persistent 2D stack. |
adt.Create2DStackPers(#name#, #row#, #size#) |
Constructs a snapshot-persistent 2D stack. |
Functions¶
| Name | Description |
|---|---|
#name#.append(row, element) |
Adds an element to the end of a row in the list. |
#name#.append.fast(row, element) |
Inserts element at end of row without capacity checking. |
#name#.clear(row) |
Resets a row in the queue to empty state. |
#name#.clear(row) |
Resets a row in the stack to empty state. |
#name#.clear() |
Resets all rows in the list to empty state. |
#name#.clear_row(row) |
Resets a single row in the list to empty state. |
#name#.delete(row, idx) |
Removes the element at a specific index in a row and shifts remaining elements. |
#name#.delete_item(row, item) |
Removes the first occurrence of a value from a row in the list. |
#name#.get_next_re(row) -> result |
Returns the next read pointer index with wraparound for a row. |
#name#.get_next_wr(row) -> result |
Returns the next write pointer index with wraparound for a row. |
#name#.insert(row, element, idx) |
Inserts an element at a specific index in a row of the list. |
#name#.peek(row) -> result |
Returns the front element in a row without removing it. |
#name#.peek(row) -> result |
Returns the top element in a row without removing it. |
#name#.peek(row, idx) -> result |
Returns an element at a specific index in a row without removing it. |
#name#.peek.fast(row) -> result |
Returns element at read pointer in row without empty checking. |
#name#.peek_end(row) -> result |
Returns the last element in a row without removing it. |
#name#.pop(row) -> result |
Returns and removes the front element from a row in the queue. |
#name#.pop(row) -> result |
Returns and removes the top element from a row in the stack. |
#name#.pop(row) -> result |
Returns and removes the last element from a row in the list. |
#name#.pop.fast(row) -> result |
Returns and removes element from row without empty checking. |
#name#.pop.fast(row) -> result |
Returns and removes top element from row without empty checking. |
#name#.push(row, element) |
Adds an element to the back of a row in the queue. |
#name#.push(row, element) |
Adds an element to the top of a row in the stack. |
#name#.push.fast(row, element) |
Inserts element in row without capacity checking. |
#name#.push.fast(row, element) |
Inserts element in row without capacity checking. |
#name#.remove(row, idx) -> result |
Removes element at specified index in row and shifts remaining elements. |
#name#.remove.fast(row, idx) -> result |
Removes element at specified index in row without validation. |
#name#.retrieve(row, idx) -> result |
Returns and removes the element at a specific index in a row. |
#name#.retrieve.fast(row, idx) -> result |
Returns and removes element at index in row without validation. |
#name#.retrieve_item(row, item) -> result |
Finds the first occurrence of a value in a row, removes it, and returns its inde... |
#name#.search(row, el) -> result |
Searches for first occurrence of element in specified row. |
#name#.search(row, el) -> result |
Searches for first occurrence of element in specified row. |
#name#.search(row, el) -> result |
Searches for first occurrence of element in specified row. |
Ring Queue¶
adt.Create2DQueue(#name#, #row#, #size#)¶
Constructs a 2D integer queue with ring buffer storage per row.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
#row# |
number of rows |
#size# |
maximum capacity per row |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row#, #size#] |
int[,] | 2D ring buffer storage |
#name#.size |
int | Capacity per row |
#name#.count[#row#] |
int[] | Current element count per row |
#name#.write_p[#row#] |
int[] | Write pointer index per row |
#name#.read_p[#row#] |
int[] | Read pointer index per row |
adt.Create2DQueuePers(#name#, #row#, #size#)¶
Constructs a snapshot-persistent 2D queue.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
#row# |
number of rows |
#size# |
maximum capacity per row |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row#, #size#] |
int[,] | 2D ring buffer storage |
#name#.size |
int | Capacity per row |
#name#.count[#row#] |
int[] | Current element count per row |
#name#.write_p[#row#] |
int[] | Write pointer index per row |
#name#.read_p[#row#] |
int[] | Read pointer index per row |
- 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.Create2DQueueInstPers(#name#, #size#)¶
Constructs an instrument-persistent 2D queue.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
#size# |
maximum capacity |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row#, #size#] |
int[,] | 2D ring buffer storage |
#name#.size |
int | Capacity per row |
#name#.count[#row#] |
int[] | Current element count per row |
#name#.write_p[#row#] |
int[] | Write pointer index per row |
#name#.read_p[#row#] |
int[] | Read pointer index per row |
- 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.2DQueueFunctions(#name#)¶
Generates all operational functions for a 2D queue instance.
Preconditions: Must be called after a Create2DQueue macro for the same instance name.
| Parameter | Description |
|---|---|
#name# |
queue instance name |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#.get_next_wr(row) |
function | Returns next write pointer with wraparound for row |
#name#.get_next_re(row) |
function | Returns next read pointer with wraparound for row |
#name#.push(row, element) |
function | Adds element to row with validation |
#name#.push.fast(row, element) |
function | Adds element to row without validation |
#name#.peek(row) |
function | Returns front element in row with validation |
#name#.peek.fast(row) |
function | Returns front element in row without validation |
#name#.pop(row) |
function | Removes and returns front element from row with validation |
#name#.pop.fast(row) |
function | Removes and returns front element from row without validation |
#name#.remove(row, idx) |
function | Removes element at index in row with validation |
#name#.remove.fast(row, idx) |
function | Removes element at index in row without validation |
#name#.search(row, el) |
function | Searches for element in row, returns index or -1 |
#name#.clear(row) |
function | Resets row to empty state |
#name#.get_next_wr(row) -> result¶
Returns the next write pointer index with wraparound for a row.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — next write pointer index
#name#.get_next_re(row) -> result¶
Returns the next read pointer index with wraparound for a row.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — next read pointer index
#name#.push(row, element)¶
Adds an element to the back of a row in the queue.
Preconditions: 2DQueue row must not be full.
| Parameter | Description |
|---|---|
row |
row index |
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 row is full.
#name#.push.fast(row, element)¶
Inserts element in row without capacity checking.
| Parameter | Description |
|---|---|
row |
row index |
element |
element to put in the queue |
Post: Inserts the element in specified row and increments the write pointer without validation.
#name#.peek(row) -> result¶
Returns the front element in a row without removing it.
Preconditions: 2DQueue row must not be empty.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — front element in the row, or adt.TASK_FAIL if the row is empty
#name#.peek.fast(row) -> result¶
Returns element at read pointer in row without empty checking.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — element at read pointer in specified row
#name#.pop(row) -> result¶
Returns and removes the front element from a row in the queue.
Preconditions: 2DQueue row must not be empty.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — front element in the row, or adt.TASK_FAIL if the row is empty
#name#.pop.fast(row) -> result¶
Returns and removes element from row without empty checking.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — element at read pointer in specified row, now removed from queue
#name#.remove(row, idx) -> result¶
Removes element at specified index in row and shifts remaining elements.
| Parameter | Description |
|---|---|
row |
row index |
idx |
index of element to remove |
Returns: result — Element at index in specified row 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(row, idx) -> result¶
Removes element at specified index in row without validation.
| Parameter | Description |
|---|---|
row |
row index |
idx |
index of element to remove |
Returns: result — Element at index in specified row is removed and all subsequent elements are shifted backward without bounds checking.
#name#.search(row, el) -> result¶
Searches for first occurrence of element in specified row.
| Parameter | Description |
|---|---|
row |
row index |
el |
element to search for |
Returns: result — index of first occurrence in row, or -1 if not found
#name#.clear(row)¶
Resets a row in the queue to empty state.
| Parameter | Description |
|---|---|
row |
row index |
Post: Count and all pointers for the row are reset to zero.
2DStack¶
adt.Create2DStack(#name#, #row#, #size#)¶
Constructs a 2D integer stack.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
#row# |
number of rows |
#size# |
maximum capacity per row |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row#, #size#] |
int[,] | 2D stack storage |
#name#.size |
int | Capacity per row |
#name#.count[#row#] |
int[] | Current element count per row |
adt.Create2DStackPers(#name#, #row#, #size#)¶
Constructs a snapshot-persistent 2D stack.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
#row# |
number of rows |
#size# |
maximum capacity per row |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row#, #size#] |
int[,] | 2D stack storage |
#name#.size |
int | Capacity per row |
#name#.count[#row#] |
int[] | Current element count per row |
- Applies
make_persistentto#name#and#name#.count
Notes: Values are stored in Kontakt snapshots and overridden when snapshots change.
adt.Create2DStackInstPers(#name#, #row#, #size#)¶
Constructs an instrument-persistent 2D stack.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
#row# |
number of rows |
#size# |
maximum capacity per row |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row#, #size#] |
int[,] | 2D stack storage |
#name#.size |
int | Capacity per row |
#name#.count[#row#] |
int[] | Current element count per row |
- Applies
make_instr_persistentto#name#and#name#.count
Notes: Values are saved into the NKI on manual save, but not stored per snapshot.
adt.2DStackFunctions(#name#)¶
Generates all operational functions for a 2D stack instance.
Preconditions: Must be called after a Create2DStack macro for the same instance name.
| Parameter | Description |
|---|---|
#name# |
stack instance name |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#.push(row, element) |
function | Adds element to row with validation |
#name#.push.fast(row, element) |
function | Adds element to row without validation |
#name#.peek(row) |
function | Returns top element in row with validation |
#name#.pop(row) |
function | Removes and returns top element from row with validation |
#name#.pop.fast(row) |
function | Removes and returns top element from row without validation |
#name#.search(row, el) |
function | Searches for element in row, returns index or -1 |
#name#.clear(row) |
function | Resets row to empty state |
#name#.push(row, element)¶
Adds an element to the top of a row in the stack.
Preconditions: 2DStack row must not be full.
| Parameter | Description |
|---|---|
row |
row index |
element |
element to put in the stack |
Post: Inserts the element and increments the count. Prints an error and skips the write if the row is full.
#name#.push.fast(row, element)¶
Inserts element in row without capacity checking.
| Parameter | Description |
|---|---|
row |
row index |
element |
element to put in the stack |
Post: Inserts the element in specified row and increments the count without validation.
#name#.peek(row) -> result¶
Returns the top element in a row without removing it.
Preconditions: 2DStack row must not be empty.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — top element in the row, or adt.TASK_FAIL if the row is empty
#name#.pop(row) -> result¶
Returns and removes the top element from a row in the stack.
Preconditions: 2DStack row must not be empty.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — top element in the row, or adt.TASK_FAIL if the row is empty
#name#.pop.fast(row) -> result¶
Returns and removes top element from row without empty checking.
| Parameter | Description |
|---|---|
row |
row index |
Returns: result — top element in specified row, now removed from stack
#name#.search(row, el) -> result¶
Searches for first occurrence of element in specified row.
| Parameter | Description |
|---|---|
row |
row index |
el |
element to search for |
Returns: result — index of first occurrence in row, or -1 if not found
#name#.clear(row)¶
Resets a row in the stack to empty state.
| Parameter | Description |
|---|---|
row |
row index |
Post: Count for the row is reset to zero.
2DList¶
adt.Create2DList(#name#, #row1#, #row2#)¶
Constructs a 2D integer list with random access support.
| Parameter | Description |
|---|---|
#name# |
list instance name |
#row1# |
number of rows |
#row2# |
number of columns per row |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row1#, #row2#] |
int[,] | 2D list storage |
#name#.rows |
int | Number of rows |
#name#.columns |
int | Number of columns per row |
#name#.count[#row1#] |
int[] | Current element count per row |
#name#.CoupledSortHelperA |
List | Helper list for coupled sorting operations |
#name#.CoupledSortHelperB |
List | Helper list for coupled sorting operations |
#name#.loop_i |
int | Loop counter for operations |
- Calls
adt.CreateListtwice to create helper lists
adt.Create2DListPers(#name#, #size#)¶
Constructs a snapshot-persistent 2D list.
| Parameter | Description |
|---|---|
#name# |
list instance name |
#size# |
size of list |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row1#, #row2#] |
int[,] | 2D list storage |
#name#.rows |
int | Number of rows |
#name#.columns |
int | Number of columns per row |
#name#.count[#row1#] |
int[] | Current element count per row |
#name#.CoupledSortHelperA |
List | Helper list for coupled sorting operations |
#name#.CoupledSortHelperB |
List | Helper list for coupled sorting operations |
#name#.loop_i |
int | Loop counter for operations |
- Calls
adt.Create2DList(#name#, #size#) - Applies
make_persistentto#name#and#name#.count
Notes: Values are stored in Kontakt snapshots and overridden when snapshots change.
adt.Create2DListInstPers(#name#, #size#)¶
Constructs an instrument-persistent 2D list.
| Parameter | Description |
|---|---|
#name# |
list instance name |
#size# |
size of list |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#[#row1#, #row2#] |
int[,] | 2D list storage |
#name#.rows |
int | Number of rows |
#name#.columns |
int | Number of columns per row |
#name#.count[#row1#] |
int[] | Current element count per row |
#name#.CoupledSortHelperA |
List | Helper list for coupled sorting operations |
#name#.CoupledSortHelperB |
List | Helper list for coupled sorting operations |
#name#.loop_i |
int | Loop counter for operations |
- Calls
adt.Create2DList(#name#, #size#) - Applies
make_instr_persistentto#name#and#name#.count
Notes: Values are saved into the NKI on manual save, but not stored per snapshot.
adt.2DListFunctions(#name#)¶
Generates all operational functions for a 2D list instance.
Preconditions: Must be called after a Create2DList macro for the same instance name.
| Parameter | Description |
|---|---|
#name# |
list instance name |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#name#.append(row, element) |
function | Adds element to end of row with validation |
#name#.append.fast(row, element) |
function | Adds element to end of row without validation |
#name#.insert(row, element, idx) |
function | Inserts element at index in row with validation |
#name#.peek(row, idx) |
function | Returns element at index in row with validation |
#name#.peek_end(row) |
function | Returns last element in row without validation |
#name#.pop(row) |
function | Removes and returns last element from row |
#name#.retrieve(row, idx) |
function | Removes and returns element at index with validation |
#name#.retrieve.fast(row, idx) |
function | Removes and returns element without validation |
#name#.retrieve_item(row, item) |
function | Finds, removes, and returns index of item |
#name#.delete(row, idx) |
function | Removes element at index in row without validation |
#name#.delete_item(row, item) |
function | Removes first occurrence of item in row |
#name#.search(row, el) |
function | Searches for element in row, returns index or -1 |
#name#.clear_row(row) |
function | Resets row to empty state |
#name#.clear() |
function | Resets all rows to empty state |
- Calls
adt.ListFunctionsfor helper listsCoupledSortHelperAandCoupledSortHelperB
#name#.append(row, element)¶
Adds an element to the end of a row in the list.
Preconditions: Row must not be full.
| Parameter | Description |
|---|---|
row |
the row of the list |
element |
element to put in the list |
Post: Inserts the element at the end of the row and increments the count. Prints an error and skips the write if the row is full.
#name#.append.fast(row, element)¶
Inserts element at end of row without capacity checking.
| Parameter | Description |
|---|---|
row |
row index |
element |
element to put in the list |
Post: Inserts the element at the end of specified row and increments the count without validation.
#name#.insert(row, element, idx)¶
Inserts an element at a specific index in a row of the list.
Preconditions: Row must not be full.
| Parameter | Description |
|---|---|
row |
the row of the list |
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 row is full, the index is negative, or the index exceeds the count.
#name#.peek(row, idx) -> result¶
Returns an element at a specific index in a row without removing it.
Preconditions: The row must not be empty.
| Parameter | Description |
|---|---|
row |
the row of the list |
idx |
the index of the element to peek |
Returns: result — element at the specified index in the row, or adt.TASK_FAIL if the row is empty, the index is negative, or the index exceeds the count
#name#.peek_end(row) -> result¶
Returns the last element in a row without removing it.
Preconditions: The row must not be empty.
| Parameter | Description |
|---|---|
row |
the row of the list |
Returns: result — last element in the row
#name#.pop(row) -> result¶
Returns and removes the last element from a row in the list.
Preconditions: The row must not be empty.
| Parameter | Description |
|---|---|
row |
the row of the list |
Returns: result — last element in the row, or adt.TASK_FAIL if the row is empty
#name#.retrieve(row, idx) -> result¶
Returns and removes the element at a specific index in a row.
Preconditions: The row must not be empty.
| Parameter | Description |
|---|---|
row |
the row of the list |
idx |
the index of the element to retrieve |
Returns: result — element at the specified index in the row, or adt.TASK_FAIL if the row is empty or the index is invalid
#name#.retrieve.fast(row, idx) -> result¶
Returns and removes element at index in row without validation.
| Parameter | Description |
|---|---|
row |
row index |
idx |
index of element to retrieve |
Returns: result — element at specified index in row, now removed from list
#name#.retrieve_item(row, item) -> result¶
Finds the first occurrence of a value in a row, removes it, and returns its index.
Preconditions: The row must not be empty.
| Parameter | Description |
|---|---|
row |
the row of the list |
item |
the value to find and remove |
Returns: result — index of the removed item, or -1 if not found
#name#.delete(row, idx)¶
Removes the element at a specific index in a row and shifts remaining elements.
Preconditions: The row must not be empty.
| Parameter | Description |
|---|---|
row |
the row of the list |
idx |
the index of the element to delete |
Post: Element at idx in the row is removed and all subsequent elements are
shifted backward.
#name#.delete_item(row, item)¶
Removes the first occurrence of a value from a row in the list.
Preconditions: The row must not be empty.
| Parameter | Description |
|---|---|
row |
the row of the list |
item |
the value to find and delete |
Post: First occurrence of item in the row is removed and subsequent elements
are shifted backward. No change if the value is not found.
#name#.clear_row(row)¶
Resets a single row in the list to empty state.
| Parameter | Description |
|---|---|
row |
the row of the list |
Post: Count for the row is reset to zero.
#name#.search(row, el) -> result¶
Searches for first occurrence of element in specified row.
| Parameter | Description |
|---|---|
row |
row index |
el |
element to search for |
Returns: result — index of first occurrence in row, or -1 if not found
#name#.clear()¶
Resets all rows in the list to empty state.
Post: Count for every row is reset to zero.
adt.2DList.CoupledSort_1to1(#source#, #target#, #order#, #row#)¶
Sorts specified row of source 2DList and mirrors all swaps in target 2DList row.
| Parameter | Description |
|---|---|
#source# |
2DList to sort |
#target# |
2DList that mirrors source's swaps |
#order# |
1 for ascending, 0 for descending |
#row# |
row index to sort |
Post: Specified row in both lists is modified. Source list row is sorted according to order, and target list row has all swaps mirrored to maintain element correspondence.
Side effects:
- Modifies
source.CoupledSortHelperA,source.CoupledSortHelperB, andsource.loop_i
Notes: Uses helper lists internally for 1D coupled sort operation.
adt.2DList.Copy_Row(#source#, #target#, #row#)¶
Copies all data from specified row of source to same row of target.
| Parameter | Description |
|---|---|
#source# |
source 2DList |
#target# |
target 2DList |
#row# |
row index to copy |
Post: Target row is overwritten with source row data, including count metadata.
Side effects:
- Modifies
source.loop_i
Example¶
// TODO: Add usage example