Beamline Instrument Software Support |
|
SPEC Macro documentation:
[ Macro Index |
BCU Home ]
|
STLIST.MAC | ||||||
[ source code | installed at | configured at ] | ||||||
See other macros in category: All | ||||||
Description:
| ||||||
Documentation:
This macro file provides a set of functions to handle lists of elements with optional parameters. A list is data structure stored in an associative array that is composed of a number of elements. Each element is a string that occupies a certain position in the list, numeric elements are not allowed. An element can be referenced by it name (string) or by its position in the list (number). Each element in the list can have an arbitrary number of parameters associated to it. Each parameter has a name (a string) and a value (a number or a string). This macro set provides functions to initialise the list and add elements and parameters to it. It also provides functions to retrieve information from the list. When retrieving information it may be convenient to use shortcuts to access directily the content of the list instead of going through the macro functions. In this case there is no error checking but performance is considerably increased. if LIST[] is the associative array that holds the list, the following expressions can be used: ATTENTION This macro set overrides some macros previously included in stlocal.mac. EXAMPLE DEPENDENCIES No dependencies | ||||||
Macros:
Usage: list_test <list> This macro checks if <list> is an associative array and if not initialises it to be ready to contain a list. It does nothing if <list> was already initialised. list_init Usage: list_init <list> This macro clears and iniatilises <list> to contain a list. The information contained (if any) is lost. list_n Usage: list_n (<list>) This function returns the number of elements contained in the list specified as parameter. <list> must be an associative array (old-style array), if not the function returns -1. list_check Usage: list_check (<list>, <item>) This function checks if <item> is contained in <list> and returns its current position. If <item> is not in the list the function returns zero. <list> must be an associative array (old-style array), if not the function returns -1. <item> is either a string or a number. If a number is used it refers to the position of the element in the list. list_add Usage: list_add (<list>, <item>) This function adds a new element to the list. The element is specified by the string <item>. If such element already exists it is moved to the end of the list but no new elements are appended. The function returns the position in the list of the element recently added. This value is always the size of the list. <item> cannot be a numeric value. If <item> is a number, the element is not added and the function returns 0. If <list> is not a valid list the function returns -1. list_splitadd Usage: list_splitadd (<list>, <string> [,<separator>]) This function adds new elements to <list> in the same way than list_add but several elements can be appended in the same function call. The element specifiers are obtained by spliting <string> by means of the spec function split(). If no <separator> is specified space characters are used as delimiters. The function returns the number of elements added to the list. If an error happens -1 is returned and <list> is not modified. list_setpar Usage: list_setpar (<list>, <item>, <param>, <value>) This function sets the value of a parameter for a particular element in a list. <list> and <item> must follow the rules explained for the function list_check() . <param> is a string that specifies the parameter, if a number is used it is internally converted to string. <value> can be a number or a string. If no error is found, the function returns 1, otherwise it returns -1. list_getparlist Usage: list_getparlist (<list>, <item>, <param_list>) This function creates an auxiliary list that contains all the parameters associated to a given element in a list. <list> and <item> must follow the rules explained for the function list_check() . The auxiliary list is created in <param_list> that must be also an associative array as <list>. When the function returns, the elements of <param_list> are the identifiers of all the parameters associated to the element <item> in <list>. Each element of <param_list> has a single parameter called `value' that is set to the actual value of the corresponding parameter in <list>. The function returns the total number of parameters associated to <item>, i.e. the total number of elements in <param_list>, or -1 if an error happens. list_getpar Usage: list_getpar (<list>, <item>, <param>) This function returns the value of a particular parameter associated to an element of a list. <list>, <item> and <param> must follow the rules explained for the function list_setpar() . If an error is found the function returns -1. list_removepar Usage: list_removepar (<list>, <item> [, <param>]) This function removes a parameter associated to an element of a list. If <param> is not especified, all the parameters associated with the element <item> are removed. list_remove Usage: list_remove (<list>, <item>) This function deletes a particular element in a list and returns its position in the list before deletion. If <item> is not in the list the function returns zero. <list> must be an associative array (old-style array), if not the function returns -1. list_item Usage: list_item (<list>, <item>) This function returns -1 if the element <item> is not included in <list> or if an error happens. If <item> is a valid element the function returns the element identifier (that may be different from <item> if a number is used). list_list Usage: list_list (<list>) This function prints on the screen all the elements in a list along with the associated parameters. It is intended for debugging purposes. It returns the number of eleemnts in the list or -1 if an error happens. | ||||||
Internal Macros: | ||||||
| ||||||
|