Next: , Previous: List Selection, Up: Lists

22.2.5 Append and Reverse

append and append! are used to concatenate two or more lists in order to form a new list. reverse and reverse! return lists with the same elements as their arguments, but in reverse order. The procedure variants with an ! directly modify the pairs which form the list, whereas the other procedures create new pairs. This is why you should be careful when using the side-effecting variants.

— Scheme Procedure: append [args ...]
— C Function: scm_append (args) |0 |0 |1

Return a list consisting of the elements of the first list in args followed by the elements of the other lists. 

          (append '(x) '(y))
          ⇒ (x y)
          
          (append '(a) '(b c d))
          ⇒ (a b c d)
          
          (append '(a (b)) '((c)))
          ⇒ (a (b) (c))

The resulting list is always newly allocated, except that it shares structure with the last list argument. The last argument may actually be any object; an improper list results if the last argument is not a proper list. 

          (append '(a b) '(c . d))
          ⇒ (a b c . d)
          
          (append '() 'a)
          ⇒ a
— Scheme Procedure: append! [args ...]
— C Function: scm_append_x (args) |0 |0 |1

A destructive version of append (see Pairs and Lists). The cdr field of each list's final pair is changed to point to the head of the next list, so no consing is performed. Return a pointer to the mutated list.

— Scheme Procedure: reverse lst
— C Function: scm_reverse (lst)

Return a new list that contains the elements of lst but in reverse order.

— Scheme Procedure: reverse! lst [extra]
— C Function: scm_reverse_x (lst, extra) |1 |1 |0

A destructive version of reverse (see Pairs and Lists). The cdr of each cell in lst is modified to point to the previous list element. Return a pointer to the head of the reversed list.

Optional arg extra specifies a new tail for the returned list. It must be a proper list, as well. 

          (define ls (iota 4))
          (reverse! ls (list 4 2)) ⇒ (3 2 1 0 4 2)
          ls ⇒ (0 4 2)

Caveat: because the list is modified in place, the tail of the original list now becomes its head, and the head of the original list now becomes the tail. Therefore, the lst symbol to which the head of the original list was bound now points to the tail. To ensure that the head of the modified list is not lost (as in the example above), it is wise to save the return value of reverse!.