List is a sequence of nodes storing data and links to other node. Each node has place for single piece of data and a single link. First node of the list contains link to second node, second node contains link to the third node, etc. There is special value representing empty list. Last node of a list contains this value in as its link. In FriCAS value stored in first node is given by first, link is obtained using rest. We test if list is empty using empty? and create empty list using empty or '[]'. We can write lists in source by surronding them with square brackets. Simple manipulation on list may look like:

(1) -> l := [1, 2, 3]

(1)

first(l)

(2)

l2 := rest(l)

(3)

first(l2)

(4)

l3 := rest(l2)

(5)

empty?(l3)

(6)

empty?(rest(l3))

(7)

One can use elt to access value in arbitrary node effectively using list as an array. But usually this is inefficient, because such access to N-th node has to traverse all preceding nodes, giving O(N) operation. Note: some languages do not have true lists, they use arrays but call them lists. Array access is constant cost operation, use them if you need quick access to an arbitrary elements and do not need flexibility given by lists.

One of most common operations of lists is creating list from sequence of values. One can create list with given value and given tail by using cons. Several applications of cons can create any (proper) list. For example:

l := empty()$List(Integer)

(8)

l := cons(3, l)

(9)

l := cons(2, l)

(10)

l := cons(1, l)

(11)

Of course, in sequential code square brace notation '[1, 2, 3]?' is much more convenient. But cons can be used in loops:

l := empty()$List(Integer)

(12)

for i in 1..10 repeat l := cons(i, l)

l

(13)

Note that in both examples elements appear in opposite order to applying 'cons': the last application of cons creates first node of new list. We could correct this problem by using concat, but that is potentially inefficient since concat has to copy the whole list leading to quadratic algorithm (concat! avoids copy but still using it is quadratic due to need to traverse preceding nodes). Instead, the standard idiom is to reverse the list after construction. In normal case after construction the freshly build list in reverse order is no longer needed, so we can use reverse! which reuses nodes to make reversal faster:

l := reverse!(l)

(14)

Note: after calling reverse! old value stored in l is no longer useful, we have to use value returned by reverse!.

We frequently need to create new list by applying the same transformation to all elements of list. FriCAS has special notation in this case:

l2 := [i^2 for i in l]

(15)

Note: instead of i^2 we can use more complicated expression and we can replace for part by other FriCAS loop controls. For more details see FriCAS book, chapter 5.4 "Loops" and 5.5 "Creating lists and streams with iterators""). Here we just note that this lead to very efficient code (slightly more efficient that construction in reverse order followed by reversal).

Parts of list can be shared:

l1 := [1, 2, 3]

(16)

l2 := cons(10, l1)

(17)

l3 := cons(20, l1)

(18)

l2 has on "own" node and other nodes are shared with l1 and l3. Similarly l3 has one "own" node and the other are shared. One can see that nodes are shared by modifying them:

setfirst!(l1, 15)

(19)

l1

(20)

l2

(21)

l3

(22)

Above we used modification on to show sharing. However in general modifying shared structures may give tricky results. So normal practice is to avoid modifying shared lists. In other words we first build list which may use modification (notably reversing list in place), then we use it without further changes.

When Spad functions modify lists there is fundamental limitation: at low level lists are represented by pointers and called function has copy of a pointer to the list. So function can modify list elements, but can not change pointer in the caller. In other words, function can shorten a list, but can not change nonempty list to empty list:

fun1(l) ==
    empty?(l) => l
    l := []
    l

l := [1, 2, 3]

(23)

fun1(l)

Compiling function fun1 with type List(PositiveInteger) -> List(
      PositiveInteger)

(24)

l

(25)

To avoid this limitation usual convention is that caller should use return value of a function:

l := reverse!(l)

(26)

l

(27)

l := fun1(l)

(28)

l

(29)

Note that after modification value of original list may be useless, while return value is OK. For example

bb := [3, 4, 1, 2]

(30)

bs := sort! bb

(31)

bb

(32)

bs

(33)

sort! rearranges connections between list nodes, so orignal list looks too short. But return value is correct. So remember to use return value!

If one really wants to change argument there is a trick of prepending dummy element:

fun2(l) ==
    t := l
    t := []
    setrest!(l, t)

l := [1, 2, 3]

(34)

dl := cons(0, l)

(35)

fun2(dl)

Compiling function fun2 with type List(Integer) -> List(Integer)

(36)

rest(dl)

(37)

Note: we need variable t and extra assignment to t to work around weakness of interpreter. We should be able to use '[]' directly as the second argument to setrest!.