Contents - Index

List (function)

List(sListName,sAction,sValue) : string

Note: The list function was originally created because GSAK had no array support. As the macro language now has array support that may be a better alternative depending on your requirements.

sListName = This is the name of the list that all corresponding "actions" will be applied to
sAction = This function provides several "actions" that will enable you to manipulate the list
sValue = This is a string value associated with your corresponding "action"

You can define as many lists as you like, and lists can contain an unlimited number of items (OK, limited by memory). In order to use a list you must first "initialize" it in memory with the "create" action.

Actions:

Create - This creates the named list in memory for future actions to reference. You only need to do this once per list. sValue should contain the character(s ) to use as the delimiter for the list. The recommended value is ; (semi colon) as this will make your list compatible with other functions in GSAK that return items separated by a ; (the sysinfo function for example).

Replace - This action will enable you to completely replace the whole list. Useful when you want to allocate the result of sysinfo variables to a list for further manipulation. sValue should contain the new list value. Make sure the delimiter in sValue is the same character(s) as defined in your create action, otherwise you will only end up with one element. The return value will be the contents of the new list (same as sValue)

Add - This will add a single item to the end of your list. sValue contains the data that will be added. The return value is the new complete list.

Count - This will return the total number of items currently in the list. Svalue has no meaning for this action, so you can just enter as "". Note: because this is a string function, the result will be a string. You would normally want to convert this result to a numeric value with the val function

Item - This will return the value stored in this item of the list. sValue should contain the item number you wish to retrieve.

Delete - This will delete the item number identified by sValue from the list. The return value is the list minus this item.

Destroy - This action will allow you to destroy any list that you created in a macro. Use the reserved list named "*all" to destroy all lists created in the current macro. For more informaion on why you would use this action see this post

Find - This will return the item number that is equal to the search value of sValue. If no item is found the return value is "0". The search ignores case (so "cat" will find "CAT"). If case is important then use FindCS. sValue should contain the string you want to find in the list.

FindCS - This will return the item number that is equal to the search value of sValue, but is "Case Sensitive". If no item is found the return value is "0". sValue should contain the string you want to find in the list.

RegEx - This will return the item number that matches the regular expression of sValue. If there is no item that matches this regular expression the return value is "0"

Edit - This will allow you to change any item in the list. sValue should contain the value of the data you want to replace in a particular item. In order for this action to indicate which item you want to edit, you must use the syntax edit:nn where nn is the item number to edit. The return value is the complete list with the item updated.

Sort - This will sort the list alphabetically and return the sorted list as the result. sValue has no meaning for this action, so it can be passed as "". The return value is the complete list sorted. If you want to actually have the internal list sorted, you will then need to use the "Replace" action to replace the list with the returned value. 

Get - This will return the complete list. sValue has no meaning for this action.

Example: We want to get a list of databases for the user to select in a combo box. However, we do not want to allow selection of the "found" database or the "default" database.
 

$databases = sysInfo("Databases")
$Formdb = list("db","create",";")
$formdb = list("db","replace",$databases)
$del = Val(list("db","find","found"))
if $del > 0
  $formdb = list("db","delete","$del")
endif
$del = Val(list("db","find","default"))
if $del > 0
  $formdb = list("db","delete","$del")
endif
$formdb = list("db","get","")


Note: As the new list function can have more than one character as the delimiter, you can set it to $_Newline and this would give you another way to manipulate text files. Just get the contents of the text file via GetFile, replace in you list, and then use the actions required.

Related: Array

Alpha List         Category List