6.7.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 lst … obj

Scheme Procedure: append

Scheme Procedure: append! lst … obj

Scheme Procedure: append!

C Function: scm_append (lstlst)

C Function: scm_append_x (lstlst)

Return a list comprising all the elements of lists lst … obj. If called with no arguments, return the empty list.

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

The last argument obj 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

append doesn’t modify the given lists, but the return may share structure with the final obj. append! modifies the given lists to form its return.

For scm_append and scm_append_x, lstlst is a list of the list operands lst … obj. That lstlst itself is not modified or used in the return.

Scheme Procedure: reverse lst

Scheme Procedure: reverse! lst [newtail]

C Function: scm_reverse (lst)

C Function: scm_reverse_x (lst, newtail)

Return a list comprising the elements of lst, in reverse order.

reverse constructs a new list, reverse! modifies lst in constructing its return.

For reverse!, the optional newtail is appended to the result. newtail isn’t reversed, it simply becomes the list tail. For scm_reverse_x, the newtail parameter is mandatory, but can be SCM_EOL if no further tail is required.