Operations on Lists

The <list> class is partitioned into two subclasses, <pair> and <empty-list>. The classes <list>, <pair>, and <empty-list> are sealed; users cannot create new subclasses of <list>.

An improper list is a list that is not terminated by the empty list, either because it is terminated by something that is not a list, or because it is circular and thus non-terminating. Except when their behavior on improper lists is documented explicitly, collection or sequence functions are not guaranteed to return an answer when an improper list is used as a collection or a sequence. At the implementation's option, these functions may return the correct result, signal a <type-error>, or (in the case of a circular list) fail to return.

pair   head tail =>  pair	[Function]

pair creates a new pair whose head and tail values are as indicated.

? pair (1, 2)
#(1 . 2)
? pair (1, #(2, 3, 4, 5))
#(1, 2, 3, 4, 5)

list   #rest args =>  list	[Function]

list returns a list of the args, in order.

? list (1, 2, 3)
#(1, 2, 3)
? list (4 + 3, 4 - 3)
#(7, 1)

head   list  =>  object	[Function]

If list is a pair, this function returns the value of the head slot. Otherwise, list is the empty list, and head returns the empty list.

? head (#(4, 5, 6))
4
? head (#())
#()

tail   list  =>  object	[Function]

If list is a pair, this function returns the value of the tail slot. Otherwise, list is the empty list, and tail returns the empty list.

? tail (#(4, 5, 6))
#(5, 6)
? tail (#())
#()

head-setter   object  pair =>  object	[Function]

This function sets the head of pair to contain object and returns object.

? define variable x = list (4, 5, 6)
#(4, 5, 6)
? head (x) := 9
9
? x
#(9, 5, 6)

tail-setter   object  pair =>  object	[Function]

This function sets the tail of pair to contain object and returns object.

? define variable x = list (4, 5, 6)
#(4, 5, 6)
? tail (x) := #(9, 8, 7)
#(9, 8, 7)
? x
#(4, 9, 8, 7)

add!   list element =>  pair	[G.F. Method]

Equivalent to (pair element list). That is, the result shares structure with list but will not be == to list.

remove!   list element #key test count=>  list	[G.F. Method]

remove! destructively modifies list. The result is not necessarily == to list.

size  list  =>  {integer or #f}	[G.F. Method]

For circular lists, size is guaranteed to terminate and return #f. For non-circular lists, size returns an integer size value.

list1 = list2 =>  boolean	[G.F. Method]

For lists, = returns #f unless the two lists are the same size, corresponding elements of list1 and list2 are = and the final tails are =.

list  = sequence  =>  boolean	[G.F. Method]
sequence  =  list  =>  boolean	[G.F. Method]

For mixed lists and sequences, = returns #f unless the list is not a dotted list, both have the same size, and elements with = keys are =.