Previous section: Operations on Deques

Dylan reference manual -- Operations on Lists

## 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
#()
```
```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 =.

Next section: Operations on Ranges