6.6.9.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! is permitted, but not required, to modify 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! is permitted, but not required, to modify 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.