The List Intrinsic Class

"List" is a native TADS 3 datatype.  Lists are actually instances of the intrinsic class List, which means that you can call methods defined by the List intrinsic class on list objects.

Value Semantics

Lists have "value semantics," which means that a given list value is immutable.  Any operation that appears to modify a list value is actually creating a new list value, and leaving the original value unchanged.  This behavior makes it very easy to work with lists, because you never have to worry about how many variables or properties refer to a list – even if several variables refer to a list value, each variable effectively has its own private copy of the list, so changes made to one variable's list won't affect any others.  This also means that you can pass a list to a function without having to worry about whether the function will modify the list, and similarly that you can modify a list passed in as an argument to your functions without having to worry about how the changes will affect the caller.

 

This is discussed in more detail in the Array intrinsic class section.

List Methods

The List class provides several methods for operating on list values.

 

applyAll(func) – for each element of the list, this method invokes the callback function func, passing the current element as the single argument, then adds the return value to a new list.  The method returns the resulting new list, which has the same number of elements as the original list.  Each element of the returned list contains the result returned by func for the corresponding element of the original list.  This method does not, of course, modify the original list, but simply creates a new list.

 

Here's an example that creates a new list consisting of multiplying each element of an original list by 2 (naturally, for this to work, the original list must consist entirely of integer values):

 

  x = [1, 2, 3, 4];
  y = x.applyAll({x: x*2});

 

car() – returns the first element of the list.  If the list has no elements, returns nil.

 

cdr() – returns the "tail" of the list; that is, the rest of the list after removing the first element.  If the list has no elements, returns nil.  This function is almost the same as sublist(2), except that sublist() would return an empty list if given an empty list, whereas cdr() returns nil in this case.

 

find(val) – returns the index of the given value in this list.  If val does not occur in this list, the method returns nil.  The first element is at index 1.

 

intersect(lst2) – returns a new list consisting of the intersection of this list and lst2; that is, a list consisting of the elements common to both this list and lst2.  lst2 must also be a list.  If the two lists have no elements in common, the result is an empty list.  If an element of the shorter list (or, if the lists are of equal length, this list) appears more than once in the shorter list, and that element value also appears in the longer list, then the element will be in the result list the same number of times that it is in the shorter list.  An element repeated in the longer list will not be repeated in the result list.

 

length() – returns the number of elements in the list.

 

sublist(start, length?) – creates and returns a new list consisting of a sublist of this list starting at the element of this list at index start, and continuing for the number of elements given by length, if present, or to the end of this list if not.  Examples:

 

  [1, 2, 3].sublist(2) yields [2, 3]
  [1, 2, 3].sublist(2, 1) yields [2]

 

subset(func) – creates and returns a new list containing the elements of this list for which the callback function func returns true (i.e., any value other than nil or the integer value 0).  For each element of the source list, this method invokes the callback function, passing the value of the current element as the callback function's single argument.  If the callback returns nil or the integer value 0, the method omits the element from the result; otherwise, the method includes the element in the result list.  The new list's elements will be in the same order as the selected elements from the source list.

 

This method does not modify the original list.

 

This example uses a short-form anonymous function to create a new list that contains only the elements from an original list whose values are greater than 10.

 

  x = [5, 10, 15, 20];
  y = x.subset({x: x > 10});