Arrays¶
Arrays
Import¶
import "_IVLS/std-library/ksp/data-structures/imports/arrays.ksp"Overview¶
Arrays
LIBRARY MODULE
Pool-allocated fixed-size integer array type system for KSP.
- Each array type is backed by a flat integer pool divided into equal-sized blocks
- Instances are identified by block address (integer) rather than a dedicated variable
- Two-step setup:
array.Create(name, size)thenarray.Functions(name) - Generated CRUD functions:
new(),copy(),delete(),init(),copy_a_to_b() - Element access via
name[ref].i[idx]property
API¶
Properties¶
| Name | Description |
|---|---|
property #array#.i |
Indexed read/write access to elements within an array instance. |
property #array#.r_i |
Indexed read/write access to elements at pointer+1 offset (next sequential block... |
Macros¶
| Name | Description |
|---|---|
array.Create(#array#, #dimension#) |
Creates a new array type with the specified dimension and default pool size (524... |
array.CreateCustomPool(#array#, #dimension#, #pool#) |
Creates a new array type with a custom memory pool size. |
array.Functions(#array#) |
Generates runtime CRUD functions for the specified array type. |
Functions¶
| Name | Description |
|---|---|
#array#.copy(src) -> result |
Allocates a new array instance and copies the contents of an existing one into i... |
#array#.copy_a_to_b(a_ref, b_ref) |
Copies the contents of one array instance to another with reference validation. |
#array#.copy_a_to_b.unsafe(a_ref, b_ref) |
Copies array contents without reference validation. |
#array#.delete(ref) |
Deallocates an array instance and returns its block to the free-list. |
#array#.init(address) |
Zeros all elements of an array instance. |
#array#.new() -> result |
Allocates a new array instance from the memory pool. |
Properties¶
property #array#.i¶
Indexed read/write access to elements within an array instance.
property #array#.r_i¶
Indexed read/write access to elements at pointer+1 offset (next sequential block).
Macros¶
array.Create(#array#, #dimension#)¶
Creates a new array type with the specified dimension and default pool size (524288 elements).
| Parameter | Description |
|---|---|
#array# |
name identifier for the array type |
#dimension# |
number of elements per array instance (block size) |
array.CreateCustomPool(#array#, #dimension#, #pool#)¶
Creates a new array type with a custom memory pool size.
| Parameter | Description |
|---|---|
#array# |
name identifier for the array type |
#dimension# |
number of elements per array instance (block size) |
#pool# |
total number of elements in the memory pool (rounded down to block multiple) |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#array#.BLOCK |
const int | Block size (elements per array instance) |
#array#.POOL_SIZE |
const int | Adjusted pool size (rounded to block multiple) |
#array#.pool[] |
int[] | Memory pool backing storage |
#array#.is_alloc[] |
int[] | Allocation status flags (1 = allocated, 0 = free) |
#array#.count |
int | Current number of allocated array instances |
#array#.i |
property | Indexed element access for an array instance |
#array#.r_i |
property | Indexed element access at pointer+1 offset |
array.Functions(#array#)¶
Generates runtime CRUD functions for the specified array type.
| Parameter | Description |
|---|---|
#array# |
name identifier of the array type to generate functions for |
Side effects:
| Name | Type | Purpose |
|---|---|---|
#array#.new() |
function | Allocates a new array instance |
#array#.copy(src) |
function | Allocates a new instance and copies from src |
#array#.delete(ref) |
function | Deallocates an array instance |
#array#.copy_a_to_b(a, b) |
function | Copies instance a to b with validation |
#array#.copy_a_to_b.unsafe(a, b) |
function | Copies instance a to b without validation |
#array#.init(address) |
function | Zeros all elements in an instance |
Functions¶
#array#.copy(src) -> result¶
Allocates a new array instance and copies the contents of an existing one into it.
| Parameter | Type | Description |
|---|---|---|
src |
int | block address of the source array instance |
Returns: result — block address of the newly allocated instance containing the copied data
#array#.copy_a_to_b(a_ref, b_ref)¶
Copies the contents of one array instance to another with reference validation.
| Parameter | Type | Description |
|---|---|---|
a_ref |
int | block address of the source instance |
b_ref |
int | block address of the destination instance |
#array#.copy_a_to_b.unsafe(a_ref, b_ref)¶
Copies array contents without reference validation.
Preconditions: Both a_ref and b_ref must be valid allocated block addresses.
| Parameter | Type | Description |
|---|---|---|
a_ref |
int | block address of the source instance |
b_ref |
int | block address of the destination instance |
#array#.delete(ref)¶
Deallocates an array instance and returns its block to the free-list.
| Parameter | Type | Description |
|---|---|---|
ref |
int | block address of the instance to deallocate |
Notes: Writes -1 to the caller's ref variable (inlining side effect). No deallocation occurs if validation fails.
#array#.init(address)¶
Zeros all elements of an array instance.
| Parameter | Type | Description |
|---|---|---|
address |
int | block address of the array instance to initialize |
#array#.new() -> result¶
Allocates a new array instance from the memory pool.
Returns: result — block address of the allocated instance, or -1 if the pool is exhausted
Example¶
// TODO: Add usage example