======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 number//s when you change an array by
using:

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

The //index number//s 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//) | Return a wordlist of **all** index numbers in the array whose //stuff/ is //literal-string//. |
| [[ifindfirst]](//array-name// //literal-string//) | Return the lowest index number of an item whose //stuff// is //literal-string//. |
| [[indextoitem]](//array-name// //index-number//) | Convert an index number to an item number. |
| [[itemtoindex]](//array-name// //item-number//) | Convert an item number to an index number. |
| [[delitem]](//array-name// //item-number//) | Delete an item from the array, moving every other item down one spot. |
| [[delitems]](//array-name// //item-number// ...) | Delete one or more item numbers from an array.  This is more efficient than doing one at a time. |
| [[delarray]](//array-name//) | Delete an entire array.  Poof.  Gone. |
| [[numarrays]]() | Return the number of arrays currently active |
| [[getarrays]]() | Return a wordlist of names of all current arrays. |
| [[listarray]](//array-name//) | Describe an array and its items. |

======History:======
Karll Arrays first appeared in "plus 3" (post-ircII, pre-epic).
Many functions have been added since the start.