Karll Arrays (named after the person who contributed them to the client) are named collections of items. Unlike the client's standard associative arrays, karll arrays use index refnums to refer to items.

Arrays can have any name that is a lawful C string, and array names are case sensitive. An array is created when you set item 0 in that array. Any other operation on a non-existant array has not been created is a “not found” error.

Further items may be added sequentially with no gaps in the array. The canonical example of adding an item is:

$setitem(array-name $numitems(array-name) //stuff//)

You can replace an item that already exists in the array:

$setitem(array-name 0 //new-stuff//)

Each item in an array has an item number and an index number. The item number is what you passed to setitem. The index number is automatically generated when you change the array, and is the item's sorted-order position in the array. You can avoid the automatic recalculation of the index numbers when you change an array by using:

$usetitem(array-name $numitems(array-name) //stuff//)

The index numbers will be recalculated automatically the next time you fetch an item from the array.

You can fetch an item from an array using either it's item number or it's index number. To fetch by its item number,

$getitem(array-name 0)

To fetch by its index number,

$igetitem(array-name 0)

An example of traversing an entire array in sorted order:

for i from 0 to $numitems(array-name) {
	echo $igetitem(array-name $i);
};

When you delete an item from an array, all the items numbers above it move down one spot. If you have an array with 4 items (0 to 3) and then delete item 1, the old item 2 becomes the new item 1, and the old item 3 becomes the new item 2. There are never gaps in an array.

When you delete the final item from an array, the array is automatically destroyed.

You can atomically delete an array with delarray.