Lists
(see an overview of Magsbot lists here)

Several functions allow you to manipulate variables in groups called lists. (Originally MB only supported lists of strings; now lists of numbers are also supported. The names of functions for manipulating numeric lists are generally the same as the corresponding string list function names, but with an added underscore _. For example ENLIST is used for string lists, ENLIST_ for numeric lists.) Lists are created using commands like GETLIST,ENLIST, SETITEM and others (see Actions). List items (members of a list) are actually just individual variables with a similar name prefix. For instance, a list named stuff might actually be four variables named $stuff:1, $stuff:2, $stuff:3 and $stuff:4.  The item number is the number suffix of the variable name; for instance the items in the example list stuff have item numbers 1, 2, 3 and 4. It's important to note that the item numbers are NOT reliable indices into the items in the list. For instance, if item 3 of list stuff ($stuff:3) was deleted, the item numbers of the remaining items would NOT be updated to 1, 2 and 3. They would be remain 1, 2 and 4.

Function names shown in green are actually macros. See User-Defined Functions.


These are the "primitive" functions from which other list functions are derived. You should generally use the form shown in the section after this one rather than the primitive versions below. The ones in the next section are easier to remember, for one thing. :)
@ivnum[$list,$value,@start]
Returns the number of an item in a string list that matches $value, beginning the search at item @start.  (As of version 5.2 b8, @start is optional, and if omitted then all items in the specified list will be searched.)

@ivnum_[$list,@value,@start]
Returns the number of an item in a numeric list that matches @value, beginning the search at item @start. (As of version 5.2 b8, @start is optional, and if omitted then all items in the specified list will be searched.)

$ivar[$list,@num]
Returns the value of item @num in string list $list. An error occurs if the item number doesn't exist.

@ivar[$list,@num]
Returns the value of item @num in numeric list $list. An error occurs if the item number doesn't exist.

@isstrivar[$list,@num]
Returns true (1) if string list $list has an item number @num.

@isivar[$list,@num]
Returns true (1) if numeric list $list has an item number @num.

$iv_[$list,@num]
Returns the value of item @num in string list $list. Returns an empty string if the item number doesn't exist.

@iv_[$list,@num]
Returns the value of item @num in numeric list $list. Returns 0 if the item number doesn't exist.

These functions can be used when looping through a list:

$nextitem[$list]
Returns the next item in a string list. See also RESETLIST.

@nextitem[$list]
Returns the next item in a numeric list. See also RESETLIST_.

@nextnum[$list]
Returns the next item number in a string list. See also RESETLIST.

@nextindex[$list]
Returns the index number of the next item in a string list. Note this is the actual index number of the variable in the global variable list, NOT the item number. Use the index number with the $var_ and $varname_  functions to retrieve the full variable name and value. See also RESETLIST.

@nextnum_[$list]
Returns the next item number in a numeric list. See also RESETLIST_.

@nextindex_[$list]
Returns the index number of the next item in a numeric list. Note this is the actual index number of the variable in the global variable list, NOT the item number. Use the index number with the $var_ and $varname_  functions to retrieve the full variable name and value. (The value returned by $var_ will be in string form even though it's a numeric variable.) See also RESETLIST.

@isitem[$list,@num]
Returns true (1) if string list $list contains an item with the specified number. (Derived from @isstrivar.)

@isitem_[$list,@num]
Returns true (1) if numeric list $list contains an item with the specified number. (Derived from @isivar.)

$listitem[$list,@num]
Returns the value of item number @num from the specified string list. An error occurs if the item with that number doesn't exist. Use macro $litem instead to avoid an error; $litem will return an empty string when the specified item doesn't exist. (Derived from $ivar.)

@listitem[$list,@num]
Returns the value of item number @num from the specified numeric list. An error occurs if the item with that number doesn't exist. Use macro $litem instead to avoid an error; $litem will return an empty string when the specified item doesn't exist. (Derived from @ivar.)

$litem
The same as $listitem except that if the item is not found, $litem will return an empty string instead of causing an error. (Derived from $iv_.)

@litem
The same as @listitem except that if the item is not found, @litem will return 0 instead of causing an error. (Derived from @iv_.)

@itemnum[$list,$value]
Returns the number of the first item in string list $list whose value matches $value, or 0 if there is no match. (Derived from @ivnum.)
In versions prior to 5.2 b8, @itemnum wouldn't work correctly if the list contained any items numbered less than 1. This is a shortcoming due to the way that @ivnum used to work in versions prior to 5.2 b8. In version 5.2 b8 and higher, @itemnum will work correctly with lists containing items numbered less than 1.

@itemnum_[$list,@value]
Returns the number of the first item in string list $list whose value matches $value, or 0 if there is no match. (Derived from @ivnum_.)
In versions prior to 5.2 b8, @itemnum_ wouldn't work correctly if the list contained any items numbered less than 1. This is a shortcoming due to the way that @ivnum_ used to work in versions prior to 5.2 b8. In version 5.2 b8 and higher, @itemnum_ will work correctly with lists containing items numbered less than 1.

@itemcount[$list]
Returns a count of the number of items in the specified string list. (Derived from @varncount.)

@itemcount_[$list]
Returns a count of the number of items in the specified numeric list. (Derived from @varncount.)

$listprefix[$list]
Returns a variable prefix constructed from a string list name. For example Stuff becomes $Stuff:

$listprefix_[$list]
Returns a variable prefix constructed from a numeric list name. For example Stuff becomes @Stuff:

$suffixof[$listvarname]
Returns the suffix of a list item name. For example $suffixof["$mylist:blah"] would return "blah".

$prefixof[$listvarname]
Returns the prefix of a list item name. For example $suffixof["$mylist:blah"] would return "$mylist".

@ismember[$listname,$varname]
Tests if a variable name is a valid name for a specified list. For example, it would return true for @ismember[blah,"$blah:2"]

@itemnumof[$listvarname]
Returns item number from a list variable name. For example @itemnumof["$mylist:2"] would return 2.
 

Back to Functions