Go to the first, previous, next, last section, table of contents.

# Lists

This chapter describes Guile list functions not found in standard Scheme.

primitive: append! [lst...]
A destructive version of `append` (see section `Pairs and Lists' in The Revised^4 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.

primitive: last-pair lst
Return a pointer to the last pair in lst, signalling an error if lst is circular.

primitive: reverse! lst [newtail]
A destructive version of `reverse` (see section `Pairs and Lists' in The Revised^4 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!`

primitive: list-set! lst k val
Set the kth element of lst to val.

primitive: list-cdr-ref lst k
primitive: list-tail lst k
Return the "tail" of lst beginning with its kth element. The first element of the list is considered to be element 0.

`list-cdr-ref` and `list-tail` are identical. It may help to think of `list-cdr-ref` as accessing the kth cdr of the list, or returning the results of cdring k times down lst.

primitive: list-cdr-set! lst k val
Set the kth cdr of lst to val.

primitive: list-head lst k
Copy the first k elements from lst into a new list, and return it.

primitive: list-copy lst
Return a (newly-created) copy of lst.

primitive: delq item lst
primitive: delv item lst
primitive: delete item lst
Return a newly-created copy of lst with item removed. These procedures mirror `memq`, `memv` and `member`: `delq` compares elements of lst against item with `eq?`, `delv` uses `eqv?` and `delete` uses `equal?`

primitive: delq! item lst
primitive: delv! item lst
primitive: delete! item lst
These procedures are destructive versions of `delq`, `delv` and `delete`: they modify the pointers in the existing lst rather than creating a new list. Caveat evaluator: Like other destructive list functions, these functions cannot modify the binding of lst, and so cannot be used to delete the first element of lst destructively.

[FIXME: is there any reason to have the `sloppy' functions available at high level at all? Maybe these docs should be relegated to a "Guile Internals" node or something. -twp]

primitive: sloppy-memq
primitive: sloppy-memv
primitive: sloppy-member
These procedures behave like `memq`, `memv` and `member` (see section `Pairs and Lists' in The Revised^4 Report on Scheme), but do not perform any type or error checking. Their use is recommended only in writing Guile internals, not for high-level Scheme programs.

Go to the first, previous, next, last section, table of contents.