Site Tools


karll_arrays

Karll Arrays

What are Karll Arrays?

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.

Adding items to an array

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.

Getting items from an 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);
};

Finding values in an array

Using an array to hold wildcard patterns

Using an array to hold strings to be matched

Using an array with duplicate items

Deleting items from an array

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.

Functions:

Function name Description
setitem(array-name item-number stuff) Set an item in an array
usetitem(array-name item-number stuff) Set an item, but defer index recalculation
getitem(array-name item-number) Return an item based on its item number
igetitem(array-name index-number) Return an item based on its index number
numitems(array-name) Return the number of items in array; this is the next item number to use.
matchitem(array-name pattern) Return the item number of best literal string in array matched by pattern
rmatchitem(array-name literal-string) Return the item nubmer of best pattern in array matching literal-string
gettmatch(array-name pattern) Returns that item that matchitem finds, instead of its item number
getmatches(array-name pattern) Return a wordlist of all item numbers in array that are matched by the pattern.
getrmatches(array-name literal-string) Return a wordlist of all item numbers in array that match the literal-string.
igetmatches(array-name pattern) Reeturn a wordlist of all index numbers in an array that are matched by the pattern.
igetrmatches(array-name literal-string) Return a wordlist of all index numbers in array that match the literal-string.
finditem(array-name literal-string) Return the item number of any item whose stuff is literal-string.
ifinditem(array-name literal-string) Return the index number of any item whose stuff is literal-string.
finditems(array-name literal-string) Return a wordlist of all item numbers in the array whose stuff is literal-string.
ifinditems(array-name literal-string)
karll_arrays.txt · Last modified: 2007/02/26 21:19 by 127.0.0.1