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)