Site Tools


karll_arrays

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

karll_arrays [2007/02/26 21:19] (current)
Line 1: Line 1:
 +======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.
  
karll_arrays.txt ยท Last modified: 2007/02/26 21:19 (external edit)