Skip to content

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_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.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_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.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_persistent to #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_persistent to #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.CreateList twice 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_persistent to #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_persistent to #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.ListFunctions for helper lists CoupledSortHelperA and CoupledSortHelperB

#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, and source.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

See Also