www.want-tool.org
Built-In Type: System.List
   

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 Create:

var L := System.List.Create

Once the instance has been created, you can use its Add method to add new elements:

L.Add(1)
L.Add("Hello")
L.Add(3.1415)
L.Add(True)

The 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:

Delete(0)

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 Count function:

WriteLn("L.Count=",L.Count)

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[2] )

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:

L.Put(2, 12345.6789)

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[2] := '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:

L.SaveToTextFile('mylist1.txt')

To load a text file into a list, use the following call:

L.LoadFromTextFile('mylist1.txt')

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[0]
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 First and Last are functions returning an element value, and therefore cannot be used on the left-hand side of an assignment.

-Andrew