By Andrew J. Wozniewicz
Milwaukee, August 30, 2008
System.List is a built-in type representing an ordered collection of elements. It was introduced into WANTScript with version 2.0.3.
The elements of a
System.List need not be all of the same type. You can easily mix and match Numbers, Strings, Booleans, and other objects, including other Lists.
A new instance of a
List is created via a call to its default constructor
var L := System.List.Create
Once the instance has been created, you can use its
Add method to add new elements:
System.List module also defines a
Delete method that you can use to remove a particular element from the list. The element is chosen via its zero-based index:
An attempt to delete a non-existent element, for example, by passing-in an index of an element beyond the end of the list, will cause an exception to be raised.
To find out how many elements a list contains, call its
There are two ways of retrieving a particular element from a list. The first method is via
System.List.Get(n) function, where
n represents the zero-based index of the element from the list:
WriteLn( L.Get(2) )
The aternative way of accessing an element in a list is to use the customary array subscript notation:
WriteLn( L )
These two methods of retrieving elements from a list are exactly equivalent.
Likewise, there are two equivalent ways of replacing existing elements in a list. The first method is
System.List.Put(n, value), where
n is the zero-based index of the element to be replaced, and
value is the replacement value. For example:
This puts the value of
12345.6789 into the third element of the list
L. If the list
L does not contain at least three elements, an exception is raised.
The alternative way of replacing list elements is, again, to use the normal array notation, as follows:
L := 'Peek-A-Boo'
This places the string
'Peek-A-Boo' as the third element of the list
L, if at all possible.
Lists of strings can easily be stored to, and retrieved from, disk files. To store a list's content into a disk file named
mylist1.txt you can use the following code:
To load a text file into a list, use the following call:
The file you are loading into a list via the
System.List.LoadFromTextFile() call does not have to be a previously saved list. You can load any arbitrary text file using the
System.List.LoadFromTextFile method. This capability provides a powerful way of processing text files, analogous to the way you would use a
TStringList in Delphi/Pascal. You can load a text file into a list and then access the individual lines of the file as
String-typed list elements.
Often, you need to retrieve the first element of a list. This can be done either by accessing the 0-th element of the list in one of the two methods described above (
Get, or the array subscript
), or by calling the
First function on a
System.List object. Thus
MyElement := L.First
is equivalent to either of the two following lines:
MyElement := L
MyElement := L.Get(0)
Correspondingly, there is the
System.List.Last function that makes it easier to access the last element of the list:
MyElement := L.Last
This is equivalent to either one of the following statements:
MyElement := L.Get(L.Count-1)
MyElement := L[L.Count-1]
Note that both
Last are functions returning an element value, and therefore cannot be used on the left-hand side of an assignment.