String List Handles

The following group of functions relate to lists of strings accessed by a handle. Such lists are returned by functions that find, for example, the list of layers in the current technology file, of a list of subcells in the current cell. Lists can also be defined by the user and are quite convenient for some purposes.

(stringlist_handle) StringHandle(string, sepchars)
This function returns a handle to a list of strings which are derived by splitting the string argument at characters found in the sepchars string. If sepchars is empty or null, the strings will be separated by white space, so each string in the handle list will be a word from the argument string.

(stringlist_handle) ListHandle(arglist)
This function creates a list of strings corresponding to the variable number of arguments, and returns a handle to the list. The arguments are converted to strings in the manner of the Print function, however each argument corresponds to a unique string in the list. The strings are accessed in (left to right) order of the arguments.

If no arguments are given, a handle to an empty list is returned. Calls to ListAddFront and/or ListAddBack can be used to add strings subsequently.

(string) ListContent(stringlist_handle)
This function returns the string currently referenced by the handle, and does not increment the handle to the next string in the list. If the handle is not found or contains no further list elements, a null string is returned. The function will fail if the handle is not a reference to a list of strings.

(int) ListReverse(stringlist_handle)
This function reverses the order of strings in the stringlist handle passed. If the operation succeeds the return value is 1, or if the list is empty or an error occurs the value is 0.

(string) ListNext(stringlist_handle)
This function will return the string at the front of the list referenced by the handle, and set the handle to reference the next string in the list. The function will fail if the handle is not a reference to a list of strings. A null string is returned if the handle is not found, or after all strings in the list have been returned.

(int) ListAddFront(stringlist_handle, string)
This function adds string to the front of the list of strings referenced by the handle, so that the handle immediately references the new string. The function will fail if the handle is not a reference to a string list, or the given string is null. The return value is 1 unless the handle is not found, in which case 0 is returned.

(int) ListAddBack(stringlist_handle, string)
This function adds string to the back of the list of strings referenced by the handle, so that the handle references the new string after all existing strings have been cycled. The function will fail if the handle is not a reference to a string list, or the given string is null. The return value is 1 unless the handle is not found, in which case 0 is returned.

(int) ListAlphaSort(stringlist_handle)
This function will alphabetically sort the list of strings referenced by the handle. The function will fail if the handle is not a reference to a list of strings. The return value is 1 unless the handle is not found, in which case 0 is returned.

(int) ListUnique(stringlist_handle)
This function deletes duplicate strings from the string list referenced by the handle, so that strings remaining in the list are unique. The function will fail if the handle is not a reference to a list of strings. The return value is 1 unless the handle is not found, in which case 0 is returned.

(string) ListFormatCols(stringlist_handle, columns)
This function returns a string which contains the column formatted list of strings referenced by the handle. The columns argument sets the page width in character columns. This function is useful for formatting lists of cell names, for example. The return is a null string if the handle is not found. The function fails if the handle does not reference a list of strings.

(string) ListConcat(stringlist_handle, sepchars)
This function returns a string consisting of each string in the list referenced by the handle separated by the sepchars string. If the sepchars string is empty or null, there is no separation between the strings. The function will fail if the handle does not reference a list of strings. A null string is returned if the handle is not found.

(int) ListIncluded(stringlist_handle, string)
This function compares string to each string in the list referenced by the handle and returns 1 if a match is found (case sensitive). If no match, or the handle is not found, 0 is returned. The function will fail if the handle is not a reference to a list of strings.