User Tools

Site Tools


Karll's Array Suite

You are probably familiar with the client's builtin variables, which work like perl's hash tables, and store a simple scalar value into a named variable. You can stick multiple values into a variable, but they require that you do your own encoding, and that's always hard to get correct.

The client also supports Karll Arrays which are multi-variable arrays. Each Karll array has a name and can store an unlimited number of scalar values, which are indexed with a number, just like a regular perl array.

Arrays are indexed sequentially, starting with 0 (zero). An array is created when item 0 in a previously nonexistent array is defined:

 $setitem(booya 0 random data)

This sets element 0 of array “booya” to the text string “random data”. Further items may be added sequentially; the next new element in the array must be 1, and anything above 1 will result in an error. Existing array elements may be freely overwritten:

 $setitem(booya 0 other data)

Now element 0 of array “booya” contains the string “other data”. Any item may be deleted from the array. If the deleted element is not the last one in the array (the one with the highest item number), all items after it are shifted down by one; this prevents an array from having “holes” in it.

 $setitem(booya 1 new data)
 $delitem(booya 0)

This first adds a new element, then deletes the first element. The result is an array that is one item in size. Item 1 become item 0.

One powerful feature of arrays not present in hashes is the ability to search through the array elements for random data. The simplest methods are probably already familiar to you. They operate in much the same manner as the $match() and $rmatch() functions. Given that some array “blah” held the following items (in order, from 0):

One could then use $matchitem() to find the element that best matches an arbitrary input pattern. Similarly, if an array contained a set of wildcard patterns, $rmatchitem() could find which one best matched some non-wildcard string.

The most powerful searching feature is $finditem(). Like the matching functions, it runs through an array looking for an item that matches the input string. However, it looks for an exact match, and is sensitive to case. This function uses a binary search algorithm, and is quite fast.

The other feature of note is an array's ability to be sorted on the fly. All array elements have an item number (the order in which it was added) and an index number (its sorted position in the array). Array elements are fetched by item number with $getitem() and by index number with $igetitem(). The result is that you can sequentially print out an array's elements using $igetitem(), and they will be sorted automatically.

There is more to these arrays than is presented here. Each function used to access and manipulate them is fully documented in Section 6 of these help files. Refer to that section for more information.

arrays.txt · Last modified: 2007/07/10 20:02 (external edit)