www.delorie.com/gnu/docs/guile/guile_222.html   search  
Buy GNU books!

Guile Reference Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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)
Return a list consisting of the elements the lists passed as arguments.
(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! . lists
C Function: scm_append_x (lists)
A destructive version of append (see section `Pairs and lists' in The Revised^5 Report on Scheme). 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 [new_tail]
C Function: scm_reverse_x (lst, new_tail)
A destructive version of reverse (see section `Pairs and lists' in The Revised^5 Report on Scheme). 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.

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, it is wise to save the return value of reverse!

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003