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

11. Lists

A list represents a sequence of zero or more elements (which may be any Lisp objects). The important difference between lists and vectors is that two or more lists can share part of their structure; in addition, you can insert or delete elements in a list without copying the whole list.

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

11.1 Lists and Cons Cells

Lists in Lisp are not a primitive data type; they are built up from cons cells. A cons cell is a data object that represents an ordered pair. It records two Lisp objects, one labeled as the CAR, and the other labeled as the CDR. These names are traditional; see Cons Cell and List Types. CDR is pronounced “could-er.”

A list is a series of cons cells chained together, one cons cell per element of the list. By convention, the CARs of the cons cells are the elements of the list, and the CDRs are used to chain the list: the CDR of each cons cell is the following cons cell. The CDR of the last cons cell is `nil`. This asymmetry between the CAR and the CDR is entirely a matter of convention; at the level of cons cells, the CAR and CDR slots have the same characteristics.

Because most cons cells are used as part of lists, the phrase list structure has come to mean any structure made out of cons cells.

The symbol `nil` is considered a list as well as a symbol; it is the list with no elements. For convenience, the symbol `nil` is considered to have `nil` as its CDR (and also as its CAR).

The CDR of any nonempty list l is a list containing all the elements of l except the first.

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

11.2 Lists as Linked Pairs of Boxes

A cons cell can be illustrated as a pair of boxes. The first box represents the CAR and the second box represents the CDR. Here is an illustration of the two-element list, `(tulip lily)`, made from two cons cells:

 ``` --------------- --------------- | car | cdr | | car | cdr | | tulip | o---------->| lily | nil | | | | | | | --------------- --------------- ```

Each pair of boxes represents a cons cell. Each box “refers to”, “points to” or “contains” a Lisp object. (These terms are synonymous.) The first box, which is the CAR of the first cons cell, contains the symbol `tulip`. The arrow from the CDR of the first cons cell to the second cons cell indicates that the CDR of the first cons cell points to the second cons cell.

The same list can be illustrated in a different sort of box notation like this:

 ``` ___ ___ ___ ___ |___|___|--> |___|___|--> nil | | | | --> tulip --> lily ```

Here is a more complex illustration, showing the three-element list, `((pine needles) oak maple)`, the first element of which is a two-element list:

 ``` ___ ___ ___ ___ ___ ___ |___|___|--> |___|___|--> |___|___|--> nil | | | | | | | --> oak --> maple | | ___ ___ ___ ___ --> |___|___|--> |___|___|--> nil | | | | --> pine --> needles ```

The same list represented in the first box notation looks like this:

 ``` -------------- -------------- -------------- | car | cdr | | car | cdr | | car | cdr | | o | o------->| oak | o------->| maple | nil | | | | | | | | | | | -- | --------- -------------- -------------- | | | -------------- ---------------- | | car | cdr | | car | cdr | ------>| pine | o------->| needles | nil | | | | | | | -------------- ---------------- ```

See section Cons Cell and List Types, for the read and print syntax of cons cells and lists, and for more “box and arrow” illustrations of lists.

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

11.3 Predicates on Lists

The following predicates test whether a Lisp object is an atom, is a cons cell or is a list, or whether it is the distinguished object `nil`. (Many of these predicates can be defined in terms of the others, but they are used so often that it is worth having all of them.)

Function: consp object

This function returns `t` if object is a cons cell, `nil` otherwise. `nil` is not a cons cell, although it is a list.

Function: atom object

This function returns `t` if object is an atom, `nil` otherwise. All objects except cons cells are atoms. The symbol `nil` is an atom and is also a list; it is the only Lisp object that is both.

 ```(atom object) ≡ (not (consp object)) ```
Function: listp object

This function returns `t` if object is a cons cell or `nil`. Otherwise, it returns `nil`. `true-list-p` is slower, but in some circumstances it is more appropriate.

 ```(listp '(1)) ⇒ t ``````(listp '()) ⇒ t ```
Function: nlistp object

This function is the opposite of `listp`: it returns `t` if object is not a list. Otherwise, it returns `nil`.

 ```(listp object) ≡ (not (nlistp object)) ```
Function: true-list-p object

This function returns `t` if object is an acyclic, `nil`-terminated (ie, not dotted), list. Otherwise it returns `nil`. `listp` is faster.

Function: null object

This function returns `t` if object is `nil`, and returns `nil` otherwise. This function is identical to `not`, but as a matter of clarity we use `null` when object is considered a list and `not` when it is considered a truth value (see `not` in Constructs for Combining Conditions).

 ```(null '(1)) ⇒ nil ``````(null '()) ⇒ t ```

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

11.4 Accessing Elements of Lists

Function: car cons-cell

This function returns the value pointed to by the first pointer of the cons cell cons-cell. Expressed another way, this function returns the CAR of cons-cell.

As a special case, if cons-cell is `nil`, then `car` is defined to return `nil`; therefore, any list is a valid argument for `car`. An error is signaled if the argument is not a cons cell or `nil`.

 ```(car '(a b c)) ⇒ a ``````(car '()) ⇒ nil ```
Function: cdr cons-cell

This function returns the value pointed to by the second pointer of the cons cell cons-cell. Expressed another way, this function returns the CDR of cons-cell.

As a special case, if cons-cell is `nil`, then `cdr` is defined to return `nil`; therefore, any list is a valid argument for `cdr`. An error is signaled if the argument is not a cons cell or `nil`.

 ```(cdr '(a b c)) ⇒ (b c) ``````(cdr '()) ⇒ nil ```
Function: car-safe object

This function lets you take the CAR of a cons cell while avoiding errors for other data types. It returns the CAR of object if object is a cons cell, `nil` otherwise. This is in contrast to `car`, which signals an error if object is not a list.

 ```(car-safe object) ≡ (let ((x object)) (if (consp x) (car x) nil)) ```
Function: cdr-safe object

This function lets you take the CDR of a cons cell while avoiding errors for other data types. It returns the CDR of object if object is a cons cell, `nil` otherwise. This is in contrast to `cdr`, which signals an error if object is not a list.

 ```(cdr-safe object) ≡ (let ((x object)) (if (consp x) (cdr x) nil)) ```
Function: nth n list

This function returns the nth element of list. Elements are numbered starting with zero, so the CAR of list is element number zero. If the length of list is n or less, the value is `nil`.

If n is negative, `nth` returns the first element of list.

 ```(nth 2 '(1 2 3 4)) ⇒ 3 ``````(nth 10 '(1 2 3 4)) ⇒ nil ``````(nth -3 '(1 2 3 4)) ⇒ 1 (nth n x) ≡ (car (nthcdr n x)) ```
Function: nthcdr n list

This function returns the nth CDR of list. In other words, it removes the first n links of list and returns what follows.

If n is zero or negative, `nthcdr` returns all of list. If the length of list is n or less, `nthcdr` returns `nil`.

 ```(nthcdr 1 '(1 2 3 4)) ⇒ (2 3 4) ``````(nthcdr 10 '(1 2 3 4)) ⇒ nil ``````(nthcdr -3 '(1 2 3 4)) ⇒ (1 2 3 4) ```

Many convenience functions are provided to make it easier for you to access particular elements in a nested list. All of these can be rewritten in terms of the functions just described.

Function: caar cons-cell
Function: cdar cons-cell
Function: cddr cons-cell
Function: caaar cons-cell
Function: cdaar cons-cell
Function: cddar cons-cell
Function: cdddr cons-cell
Function: caaaar cons-cell
Function: cdaaar cons-cell
Function: cddaar cons-cell
Function: cdddar cons-cell
Function: cddddr cons-cell

Each of these functions is equivalent to one or more applications of `car` and/or `cdr`. For example,

 ```(cadr x) ```

is equivalent to

 ```(car (cdr x)) ```

and

 ```(cdaddr x) ```

is equivalent to

 ```(cdr (car (cdr (cdr x)))) ```

That is to say, read the a’s and d’s from right to left and apply a `car` or `cdr` for each a or d found, respectively.

Function: first list

This is equivalent to `(nth 0 list)`, i.e. the first element of list. (Note that this is also equivalent to `car`.)

Function: second list

This is equivalent to `(nth 1 list)`, i.e. the second element of list.

Function: third list
Function: fourth list
Function: fifth list
Function: sixth list
Function: seventh list
Function: eighth list
Function: ninth list
Function: tenth list

These are equivalent to `(nth 2 list)` through `(nth 9 list)` respectively, i.e. the third through tenth elements of list.

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

11.5 Building Cons Cells and Lists

Many functions build lists, as lists reside at the very heart of Lisp. `cons` is the fundamental list-building function; however, it is interesting to note that `list` is used more times in the source code for Emacs than `cons`.

Function: cons object1 object2

This function is the fundamental function used to build new list structure. It creates a new cons cell, making object1 the CAR, and object2 the CDR. It then returns the new cons cell. The arguments object1 and object2 may be any Lisp objects, but most often object2 is a list.

 ```(cons 1 '(2)) ⇒ (1 2) ``````(cons 1 '()) ⇒ (1) ``````(cons 1 2) ⇒ (1 . 2) ```

`cons` is often used to add a single element to the front of a list. This is called consing the element onto the list. For example:

 ```(setq list (cons newelt list)) ```

Note that there is no conflict between the variable named `list` used in this example and the function named `list` described below; any symbol can serve both purposes.

Function: list &rest objects

This function creates a list with objects as its elements. The resulting list is always `nil`-terminated. If no objects are given, the empty list is returned.

 ```(list 1 2 3 4 5) ⇒ (1 2 3 4 5) ``````(list 1 2 '(3 4 5) 'foo) ⇒ (1 2 (3 4 5) foo) ``````(list) ⇒ nil ```
Function: make-list length object

This function creates a list of length length, in which all the elements have the identical value object. Compare `make-list` with `make-string` (see section Creating Strings).

 ```(make-list 3 'pigs) ⇒ (pigs pigs pigs) ``````(make-list 0 'pigs) ⇒ nil ```
Function: append &rest sequences

This function returns a list containing all the elements of sequences. The sequences may be lists, vectors, or strings, but the last one should be a list. All arguments except the last one are copied, so none of them are altered.

More generally, the final argument to `append` may be any Lisp object. The final argument is not copied or converted; it becomes the CDR of the last cons cell in the new list. If the final argument is itself a list, then its elements become in effect elements of the result list. If the final element is not a list, the result is a “dotted list” since its final CDR is not `nil` as required in a true list.

See `nconc` in Functions that Rearrange Lists, for a way to join lists with no copying.

Here is an example of using `append`:

 ```(setq trees '(pine oak)) ⇒ (pine oak) (setq more-trees (append '(maple birch) trees)) ⇒ (maple birch pine oak) ``````trees ⇒ (pine oak) more-trees ⇒ (maple birch pine oak) ``````(eq trees (cdr (cdr more-trees))) ⇒ t ```

You can see how `append` works by looking at a box diagram. The variable `trees` is set to the list `(pine oak)` and then the variable `more-trees` is set to the list ```(maple birch pine oak)```. However, the variable `trees` continues to refer to the original list:

 ```more-trees trees | | | ___ ___ ___ ___ -> ___ ___ ___ ___ --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil | | | | | | | | --> maple -->birch --> pine --> oak ```

An empty sequence contributes nothing to the value returned by `append`. As a consequence of this, a final `nil` argument forces a copy of the previous argument.

 ```trees ⇒ (pine oak) ``````(setq wood (append trees ())) ⇒ (pine oak) ``````wood ⇒ (pine oak) ``````(eq wood trees) ⇒ nil ```

This once was the usual way to copy a list, before the function `copy-sequence` was invented. See section Sequences, Arrays, and Vectors.

With the help of `apply`, we can append all the lists in a list of lists:

 ```(apply 'append '((a b c) nil (x y z) nil)) ⇒ (a b c x y z) ```

If no sequences are given, `nil` is returned:

 ```(append) ⇒ nil ```

Here are some examples where the final argument is not a list:

 ```(append '(x y) 'z) ⇒ (x y . z) (append '(x y) [z]) ⇒ (x y . [z]) ```

The second example shows that when the final argument is a sequence but not a list, the sequence’s elements do not become elements of the resulting list. Instead, the sequence becomes the final CDR, like any other non-list final argument.

The `append` function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. Don’t use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with `format` (see section Formatting Strings) or `number-to-string` (see section Conversion of Characters and Strings).

Function: reverse sequence

This function creates a new sequence whose elements are the elements of sequence, but in reverse order. The original argument sequence is not altered.

 ```(setq x '(1 2 3 4)) ⇒ (1 2 3 4) ``````(reverse x) ⇒ (4 3 2 1) x ⇒ (1 2 3 4) ```

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

11.6 Modifying Existing List Structure

You can modify the CAR and CDR contents of a cons cell with the primitives `setcar` and `setcdr`.

Common Lisp note: Common Lisp uses functions `rplaca` and `rplacd` to alter list structure; they change structure the same way as `setcar` and `setcdr`, but the Common Lisp functions return the cons cell while `setcar` and `setcdr` return the new CAR or CDR.

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

11.6.1 Altering List Elements with `setcar`

Changing the CAR of a cons cell is done with `setcar`. When used on a list, `setcar` replaces one element of a list with a different element.

Function: setcar cons-cell object

This function stores object as the new CAR of cons-cell, replacing its previous CAR. It returns the value object. For example:

 ```(setq x '(1 2)) ⇒ (1 2) ``````(setcar x 4) ⇒ 4 ``````x ⇒ (4 2) ```

When a cons cell is part of the shared structure of several lists, storing a new CAR into the cons changes one element of each of these lists. Here is an example:

 ```;; Create two lists that are partly shared. (setq x1 '(a b c)) ⇒ (a b c) (setq x2 (cons 'z (cdr x1))) ⇒ (z b c) ``````;; Replace the CAR of a shared link. (setcar (cdr x1) 'foo) ⇒ foo x1 ; Both lists are changed. ⇒ (a foo c) x2 ⇒ (z foo c) ``````;; Replace the CAR of a link that is not shared. (setcar x1 'baz) ⇒ baz x1 ; Only one list is changed. ⇒ (baz foo c) x2 ⇒ (z foo c) ```

Here is a graphical depiction of the shared structure of the two lists in the variables `x1` and `x2`, showing why replacing `b` changes them both:

 ``` ___ ___ ___ ___ ___ ___ x1---> |___|___|----> |___|___|--> |___|___|--> nil | --> | | | | | | --> a | --> b --> c | ___ ___ | x2--> |___|___|-- | | --> z ```

Here is an alternative form of box diagram, showing the same relationship:

 ```x1: -------------- -------------- -------------- | car | cdr | | car | cdr | | car | cdr | | a | o------->| b | o------->| c | nil | | | | -->| | | | | | -------------- | -------------- -------------- | x2: | -------------- | | car | cdr | | | z | o---- | | | -------------- ```

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

11.6.2 Altering the CDR of a List

The lowest-level primitive for modifying a CDR is `setcdr`:

Function: setcdr cons-cell object

This function stores object as the new CDR of cons-cell, replacing its previous CDR. It returns the value object.

Here is an example of replacing the CDR of a list with a different list. All but the first element of the list are removed in favor of a different sequence of elements. The first element is unchanged, because it resides in the CAR of the list, and is not reached via the CDR.

 ```(setq x '(1 2 3)) ⇒ (1 2 3) ``````(setcdr x '(4)) ⇒ (4) ``````x ⇒ (1 4) ```

You can delete elements from the middle of a list by altering the CDRs of the cons cells in the list. For example, here we delete the second element, `b`, from the list `(a b c)`, by changing the CDR of the first cell:

 ```(setq x1 '(a b c)) ⇒ (a b c) (setcdr x1 (cdr (cdr x1))) ⇒ (c) x1 ⇒ (a c) ```

Here is the result in box notation:

 ``` -------------------- | | -------------- | -------------- | -------------- | car | cdr | | | car | cdr | -->| car | cdr | | a | o----- | b | o-------->| c | nil | | | | | | | | | | -------------- -------------- -------------- ```

The second cons cell, which previously held the element `b`, still exists and its CAR is still `b`, but it no longer forms part of this list.

It is equally easy to insert a new element by changing CDRs:

 ```(setq x1 '(a b c)) ⇒ (a b c) (setcdr x1 (cons 'd (cdr x1))) ⇒ (d b c) x1 ⇒ (a d b c) ```

Here is this result in box notation:

 ``` -------------- ------------- ------------- | car | cdr | | car | cdr | | car | cdr | | a | o | -->| b | o------->| c | nil | | | | | | | | | | | | --------- | -- | ------------- ------------- | | ----- -------- | | | --------------- | | | car | cdr | | -->| d | o------ | | | --------------- ```

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

11.6.3 Functions that Rearrange Lists

Here are some functions that rearrange lists “destructively” by modifying the CDRs of their component cons cells. We call these functions “destructive” because they chew up the original lists passed to them as arguments, to produce a new list that is the returned value.

Function: nconc &rest lists

This function returns a list containing all the elements of lists. Unlike `append` (see section Building Cons Cells and Lists), the lists are not copied. Instead, the last CDR of each of the lists is changed to refer to the following list. The last of the lists is not altered. For example:

 ```(setq x '(1 2 3)) ⇒ (1 2 3) ``````(nconc x '(4 5)) ⇒ (1 2 3 4 5) ``````x ⇒ (1 2 3 4 5) ```

Since the last argument of `nconc` is not itself modified, it is reasonable to use a constant list, such as `'(4 5)`, as in the above example. For the same reason, the last argument need not be a list:

 ```(setq x '(1 2 3)) ⇒ (1 2 3) ``````(nconc x 'z) ⇒ (1 2 3 . z) ``````x ⇒ (1 2 3 . z) ```

A common pitfall is to use a quoted constant list as a non-last argument to `nconc`. If you do this, your program will change each time you run it! Here is what happens:

 ```(defun add-foo (x) ; We want this function to add (nconc '(foo) x)) ; `foo` to the front of its arg. ``````(symbol-function 'add-foo) ⇒ (lambda (x) (nconc (quote (foo)) x)) ``````(setq xx (add-foo '(1 2))) ; It seems to work. ⇒ (foo 1 2) ``````(setq xy (add-foo '(3 4))) ; What happened? ⇒ (foo 1 2 3 4) ``````(eq xx xy) ⇒ t ``````(symbol-function 'add-foo) ⇒ (lambda (x) (nconc (quote (foo 1 2 3 4) x))) ```
Function: nreverse sequence

This function reverses the order of the elements of sequence. Unlike `reverse`, `nreverse` alters its argument. If sequence is a list, it does this by reversing the CDRs in the cons cells forming the sequence. The cons cell that used to be the last one in sequence becomes the first cell of the value.

For example:

 ```(setq x '(1 2 3 4)) ⇒ (1 2 3 4) ``````x ⇒ (1 2 3 4) (nreverse x) ⇒ (4 3 2 1) ``````;; The cell that was first is now last. x ⇒ (1) ```

To avoid confusion, we usually store the result of `nreverse` back in the same variable which held the original sequence:

 ```(setq x (nreverse x)) ```

Here is the `nreverse` of our favorite example, `(a b c)`, presented graphically:

 ```Original list head: Reversed list: ------------- ------------- ------------ | car | cdr | | car | cdr | | car | cdr | | a | nil |<-- | b | o |<-- | c | o | | | | | | | | | | | | | | ------------- | --------- | - | -------- | - | | | | ------------- ------------ ```
Function: sort* sequence predicate &key (key #'identity)

This function sorts sequence stably, though destructively, and returns the sorted sequence. It compares elements using predicate. A stable sort is one in which elements with equal sort keys maintain their relative order before and after the sort. Stability is important when successive sorts are used to order elements according to different criteria.

sequence can be any sequence, that is, a list, a vector, a bit-vector, or a string.

The argument predicate must be a function that accepts two arguments. It is called with two elements of sequence. To get an increasing order sort, the predicate should return `t` if the first element is “less than” the second, or `nil` if not.

The keyword argument key, if supplied, is a function used to extract an object to be used for comparison from each element of sequence, and defaults to `identity`. For example, to sort a vector of lists by the numeric value of the first element, you could use the following code:

 ```(setq example-vector [(1 "foo") (3.14159 bar) (2 . quux)]) ⇒ [(1 "foo") (3.14159 bar) (2 . quux)] ``````(sort* example-vector #'< :key #'car) ⇒ [(1 "foo") (2 . quux) (3.14159 bar)] ```

If sequence is a list, `sort*` rearranges the cons cells forming sequence by changing CDRs. A nondestructive sort function would create new cons cells to store the elements in their sorted order. `sort*` treats other sequence types in an analogous fashion—if you wish to make a sorted copy without destroying the original, copy it first with `copy-sequence` and then sort.

Sorting will not change the CARs of the cons cells of a list sequence; the cons cell that originally contained the element `a` in sequence still has `a` in its CAR after sorting, but it now appears in a different position in the sequence due to the change of CDRs. For example:

 ```(setq nums '(1 3 2 6 5 4 0)) ⇒ (1 3 2 6 5 4 0) ``````(sort* nums '<) ⇒ (0 1 2 3 4 5 6) ``````nums ⇒ (1 2 3 4 5 6) ```

Note that the list in `nums` no longer contains 0; this is the same cons cell that it was before, but it is no longer the first one in the list. Don’t assume a variable that formerly held the argument now holds the entire sorted list! Instead, save the result of `sort*` and use that. Most often we store the result back into the variable that held the original sequence:

 ```(setq nums (sort* nums '<)) ```

In this implementation, `sort` is a function alias for `sort*`, and accepts the same arguments. In older XEmacs, and in current GNU Emacs, `sort` only accepted lists, and did not accept the key argument, so the byte-compiler will warn you if you call `sort` with more than two arguments.

See section Sorting Text, for more functions that perform sorting. See `documentation` in Access to Documentation Strings, for a useful example of `sort*`.

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

11.7 Using Lists as Sets

A list can represent an unordered mathematical set—simply consider a value an element of a set if it appears in the list, and ignore the order of the list. XEmacs provides set operations inherited from Common Lisp.

Function: member* item list &key :test :test-not :key

This function tests to see whether item is a member of list, comparing with `eql`. If it is, `member*` returns the tail of list starting with the first occurrence of item. Otherwise, it returns `nil`.

This is equivalent to the Common Lisp `member` function, but that name was already taken in Emacs Lisp, whence the asterisk at the end of `member*`.

The `:test` keyword argument allows you to specify the test used to decide whether item is equivalent to a given element of list. The function should return non-`nil` if the items match, `nil` if they do not. The `:test-not` keyword is similar, but the meaning of `nil` and non-`nil` results are reversed. The `:key` keyword allows you to examine a component of each object in list, rather than the object itself.

 ```(member* 'b '(a b c b a)) ⇒ (b c b a) ``````(member* '(2) '((1) (2))) ; `(2)` and `(2)` are not `eql`. ⇒ nil ``````(member* '(2) '((1) (2)) :test #'equal) ; but they are `equal`. ⇒ ((2)) ``````(member* 3 '((1) (2) (3) (4)) :key 'car) ; key not applied to item ⇒ ((3) (4)) ```
Function: memq item list

This is equivalent to calling `(member* item list :test 'eq)`, but for historical reasons is more common in the XEmacs code base. Both expressions compile to the same byte-code.

Function: member item list

This is equivalent to calling `(member* item list :test 'equal)`.

Function: remove* item sequence &key (test #'eql) (key #'identity) (start 0) (end (length sequence)) from-end count test-not

This function removes all occurrences of object from sequence, which can be a list, vector, or bit-vector.

The `:test` keyword argument allows you to specify the test used to decide whether item is equivalent to a given element of sequence. The function should return non-`nil` if the items match, `nil` if they do not. The `:test-not` keyword is similar, but the meaning of `nil` and non-`nil` results are reversed. The `:key` keyword allows you to examine a component of each object in sequence, rather than the object itself.

The `:start` and `:end` keywords allow you to specify a zero-based subrange of sequence to operate on, `remove*` will call the test function on all items of sequence between the index specified by `:start`, inclusive, and `:end`, exclusive. `:count` gives a maximum number of items to remove, and `:from-end`, most useful in combination with `:count`, specifies that the removal should start from the end of sequence.

As with `member*`, this function is equivalent to the Common Lisp function of almost the same name (the Common Lisp function has no asterisk.)

When `remove*` removes elements from the front of a list sequence, it does so simply by advancing down the list and returning a sublist that starts after those elements:

 ```(remove* 'a '(a b c)) ≡ (cdr '(a b c)) ```

When an element to be deleted appears in the middle of the list, removing it involves copying the list conses up to that point, and setting the tail of the copied list to the tail of the original list past that point.

 ```(setq sample-list '(a b c (4))) ⇒ (a b c (4)) ``````(remove* 'a sample-list) ⇒ (b c (4)) ``````sample-list ⇒ (a b c (4)) ``````(remove* 'c sample-list) ⇒ (a b (4)) ``````sample-list ⇒ (a b c (4)) ```

Don’t assume that a variable which formerly held the argument list now has fewer elements, or that it still holds the original list! Instead, save the result of `remove*` and use that. Most often we store the result back into the variable that held the original list:

 ```(setq flowers (remove* 'rose flowers)) ```

In the following example, the `(4)` that `remove*` attempts to match and the `(4)` in the `sample-list` are not `eql`:

 ```(remove* '(4) sample-list) ⇒ (a b c (4)) ```
Function: remq item sequence

This is equivalent to calling `(remove* item sequence :test #'eq)`.

Function: remove item sequence

This is equivalent to calling `(remove* item sequence :test #'equal)`.

Function: delete* item sequence &key (test #'eql) (key #'identity) (start 0) (end (length sequence)) from-end count test-not

This is like `remove*`, but a list sequence is modified in-place (‘destructively’, in Lisp parlance). So some of the examples above change:

 ```(setq sample-list '(a b c (4))) ⇒ (a b c (4)) ``````(delete* 'c sample-list) ⇒ (a b (4)) ``````sample-list ⇒ (a b (4)) ```
Function: delq item sequence

This is equivalent to calling `(delete* item sequence :test #'eq)`.

Function: delete item list

This is equivalent to calling `(delete* item sequence :test #'equal)`.

Function: subsetp list1 list2 &key :test :test-not :key

This function returns non-`nil` if every item in list1 is present in list2.

Function: union list1 list2 &key :test :test-not :key :stable

This function calculates the union of two lists, returning a list containing all those items that appear in either list. It doesn’t guarantee that duplicates in list1 or list2 will be eliminated; see `remove-duplicates` if this is important to you.

A non-nil value for the `:stable` keyword, not specified by Common Lisp, means return the items in the order they appear in list1, followed by the remaining items in the order they appear in list2. The other keywords are as in `member*`.

`union` does not modify list1 or list2.

Function: intersection list1 list2 &key :test :test-not :key :stable

This function calculates the intersection of two lists, returning a list containing all those items that appear in both lists. It doesn’t guarantee that duplicates in list1 or list2 will be eliminated; see `remove-duplicates` if this is important to you. `intersection` does not modify either list.

A non-nil value for the `:stable` keyword, not specified by Common Lisp, means return the items in the order they appear in list1. The other keywords are as in `member*`.

Function: set-difference list1 list2 &key :test :test-not :key :stable

This function returns those items that are in list1 but not in list2. It does not modify either list.

A non-nil value for the `:stable` keyword, not specified by Common Lisp, means return the items in the order they appear in list1. The other keywords are as in `member*`.

Function: set-exclusive-or list1 list2 &key :test :test-not :key :stable

This function returns those items that are in list1 but not in list2, together with those in list2 but not in list1. It does not modify either list.

A non-nil value for the `:stable` keyword, not specified by Common Lisp, means return the items in the order they appear in list1, followed by the remaining items in the order they appear in list2. The other keywords are as in `member*`.

The following functions are equivalent to the previous four functions, but with two important differences; they do not accept the `:stable` keyword, and they modify one or both list arguments in the same way `delete*` does.

Function: nintersection list1 list2 &key :test :test-not :key
Function: nset-difference list1 list2 &key :test :test-not :key
Function: nset-exclusive-or list1 list2 &key :test :test-not :key
Function: nunion list1 list2 &key :test :test-not :key

See also the function `add-to-list`, in How to Alter a Variable Value, for another way to add an element to a list stored in a variable.

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

11.8 Association Lists

An association list, or alist for short, records a mapping from keys to values. It is a list of cons cells called associations: the CAR of each cell is the key, and the CDR is the associated value.(1)

Here is an example of an alist. The key `pine` is associated with the value `cones`; the key `oak` is associated with `acorns`; and the key `maple` is associated with `seeds`.

 ```'((pine . cones) (oak . acorns) (maple . seeds)) ```

The associated values in an alist may be any Lisp objects; so may the keys. For example, in the following alist, the symbol `a` is associated with the number `1`, and the string `"b"` is associated with the list `(2 3)`, which is the CDR of the alist element:

 ```((a . 1) ("b" 2 3)) ```

Sometimes it is better to design an alist to store the associated value in the CAR of the CDR of the element. Here is an example:

 ```'((rose red) (lily white) (buttercup yellow)) ```

Here we regard `red` as the value associated with `rose`. One advantage of this method is that you can store other related information—even a list of other items—in the CDR of the CDR. One disadvantage is that you cannot use `rassq` (see below) to find the element containing a given value. When neither of these considerations is important, the choice is a matter of taste, as long as you are consistent about it for any given alist.

Note that the same alist shown above could be regarded as having the associated value in the CDR of the element; the value associated with `rose` would be the list `(red)`.

Association lists are often used to record information that you might otherwise keep on a stack, since new associations may be added easily to the front of the list. When searching an association list for an association with a given key, the first one found is returned, if there is more than one.

In XEmacs Lisp, it is not an error if an element of an association list is not a cons cell. The alist search functions simply ignore such elements. Many other versions of Lisp signal errors in such cases, and it is good practice to avoid adding non-cons-cells to association lists.

Note that property lists are similar to association lists in several respects. A property list behaves like an association list in which each key can occur only once. See section Property Lists, for a comparison of property lists and association lists.

Function: assoc* key alist &key :test :test-not :key

This function returns the first association for key in alist. It compares key against the alist elements using `eql` (see section Equality Predicates), or the test specified with the `:test` keyword. It returns `nil` if no association in alist has a CAR `equal` to key. For example:

 ```(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) ⇒ ((pine . cones) (oak . acorns) (maple . seeds)) (assoc* 'oak trees) ⇒ (oak . acorns) (cdr (assoc* 'oak trees)) ⇒ acorns (assoc* 'birch trees) ⇒ nil ```

Here is another example, in which the keys and values are not symbols:

 ```(setq needles-per-cluster '((2 "Austrian Pine" "Red Pine") (3 "Pitch Pine") (5 "White Pine"))) (cdr (assoc* 3 needles-per-cluster)) ⇒ ("Pitch Pine") (cdr (assoc* 2 needles-per-cluster)) ⇒ ("Austrian Pine" "Red Pine") ```

The `:test` keyword argument allows you to specify the test used to decide whether key is equivalent to a given element of alist. The function should return non-`nil` if the items match, `nil` if they do not. The `:test-not` keyword is similar, but the meaning of `nil` and non-`nil` results are reversed. The `:key` keyword allows you to examine a component of each CAR in alist, rather than the CAR itself.

Function: rassoc* value alist &key :test :test-not :key

This function returns the first association with value value in alist. It returns `nil` if no association in alist has a CDR `eql` to value.

`rassoc*` is like `assoc*` except that it compares the CDR of each alist association instead of the CAR. You can think of this as “reverse `assoc*`”, finding the key for a given value.

The keywords work similarly to `assoc*`.

Function: assq key alist

This is equivalent to calling `(assoc* key alist :test 'eq)`, and compiles to the same byte code.

 ```(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) ⇒ ((pine . cones) (oak . acorns) (maple . seeds)) (assq 'pine trees) ⇒ (pine . cones) ```

`assq` is not usually useful in alists where the keys may not be symbols:

 ```(setq leaves '(("simple leaves" . oak) ("compound leaves" . horsechestnut))) (assq "simple leaves" leaves) ⇒ nil (assoc "simple leaves" leaves) ⇒ ("simple leaves" . oak) ```
Function: rassq value alist

This is equivalent to calling `(rassoc* value alist :test 'eq)`, and compiles to the same byte code. For example:

 ```(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) (rassq 'acorns trees) ⇒ (oak . acorns) (rassq 'spores trees) ⇒ nil ```

Note that `rassq` cannot search for a value stored in the CAR of the CDR of an element:

 ```(setq colors '((rose red) (lily white) (buttercup yellow))) (rassq 'white colors) ⇒ nil ```

In this case, the CDR of the association `(lily white)` is not the symbol `white`, but rather the list `(white)`. This becomes clearer if the association is written in dotted pair notation:

 ```(lily white) ≡ (lily . (white)) ```
Function: copy-alist alist

This function returns a two-level deep copy of alist: it creates a new copy of each association, so that you can alter the associations of the new alist without changing the old one.

 ```(setq needles-per-cluster '((2 . ("Austrian Pine" "Red Pine")) (3 . ("Pitch Pine")) `````` (5 . ("White Pine")))) ⇒ ((2 "Austrian Pine" "Red Pine") (3 "Pitch Pine") (5 "White Pine")) (setq copy (copy-alist needles-per-cluster)) ⇒ ((2 "Austrian Pine" "Red Pine") (3 "Pitch Pine") (5 "White Pine")) (eq needles-per-cluster copy) ⇒ nil (equal needles-per-cluster copy) ⇒ t (eq (car needles-per-cluster) (car copy)) ⇒ nil (cdr (car (cdr needles-per-cluster))) ⇒ ("Pitch Pine") ``````(eq (cdr (car (cdr needles-per-cluster))) (cdr (car (cdr copy)))) ⇒ t ```

This example shows how `copy-alist` makes it possible to change the associations of one copy without affecting the other:

 ```(setcdr (assq 3 copy) '("Martian Vacuum Pine")) (cdr (assq 3 needles-per-cluster)) ⇒ ("Pitch Pine") ```

For removing elements from alists, use `remove*` or `delete*` with appropriate `:key` arguments. If it is necessary that XEmacs not error on encountering a non-cons in such a list, there are XEmacs-specific functions `remassq`, `remrassq`, `remassoc`, and `remrassoc` with this behavior, but they are neither available under GNU Emacs nor Common Lisp. They are marked as obsolete, and it is preferable to fix your code to avoid adding non-cons objects to alists.

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

11.9 Property Lists

A property list (or plist) is another way of representing a mapping from keys to values. Instead of the list consisting of conses of a key and a value, the keys and values alternate as successive entries in the list. Thus, the association list

 ```((a . 1) (b . 2) (c . 3)) ```

has the equivalent property list form

 ```(a 1 b 2 c 3) ```

Property lists are used to represent the properties associated with various sorts of objects, such as symbols, strings, frames, etc. The convention is that property lists can be modified in-place, while association lists generally are not.

Plists come in two varieties: normal plists, whose keys are compared with `eq`, and lax plists, whose keys are compared with `equal`,

Function: valid-plist-p plist

Given a plist, this function returns non-`nil` if its format is correct. If it returns `nil`, `check-valid-plist` will signal an error when given the plist; that means it’s a malformed or circular plist or has non-symbols as keywords.

Function: check-valid-plist plist

Given a plist, this function signals an error if there is anything wrong with it. This means that it’s a malformed or circular plist.

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

11.9.1 Working With Normal Plists

Function: plist-get plist property &optional default

This function extracts a value from a property list. The function returns the value corresponding to the given property, or default if property is not one of the properties on the list.

Function: plist-put plist property value

This function changes the value in plist of property to value. If property is already a property on the list, its value is set to value, otherwise the new property value pair is added. The new plist is returned; use `(setq x (plist-put x property value))` to be sure to use the new value. The plist is modified by side effects.

Function: plist-remprop plist property

This function removes from plist the property property and its value. The new plist is returned; use ```(setq x (plist-remprop x property))``` to be sure to use the new value. The plist is modified by side effects.

Function: plist-member plist property

This function returns `t` if property has a value specified in plist.

In the following functions, if optional arg nil-means-not-present is non-`nil`, then a property with a `nil` value is ignored or removed. This feature is a virus that has infected old Lisp implementations (and thus E-Lisp, due to RMS’s enamorment with old Lisps), but should not be used except for backward compatibility.

Function: plists-eq a b &optional nil-means-not-present

This function returns non-`nil` if property lists A and B are `eq` (i.e. their values are `eq`).

Function: plists-equal a b &optional nil-means-not-present

This function returns non-`nil` if property lists A and B are `equal` (i.e. their values are `equal`; their keys are still compared using `eq`).

Function: canonicalize-plist plist &optional nil-means-not-present

This function destructively removes any duplicate entries from a plist. In such cases, the first entry applies.

The new plist is returned. If nil-means-not-present is given, the return value may not be `eq` to the passed-in value, so make sure to `setq` the value back into where it came from.

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

11.9.2 Working With Lax Plists

Recall that a lax plist is a property list whose keys are compared using `equal` instead of `eq`.

Function: lax-plist-get lax-plist property &optional default

This function extracts a value from a lax property list. The function returns the value corresponding to the given property, or default if property is not one of the properties on the list.

Function: lax-plist-put lax-plist property value

This function changes the value in lax-plist of property to value.

Function: lax-plist-remprop lax-plist property

This function removes from lax-plist the property property and its value. The new plist is returned; use ```(setq x (lax-plist-remprop x property))``` to be sure to use the new value. The lax-plist is modified by side effects.

Function: lax-plist-member lax-plist property

This function returns `t` if property has a value specified in lax-plist.

In the following functions, if optional arg nil-means-not-present is non-`nil`, then a property with a `nil` value is ignored or removed. This feature is a virus that has infected old Lisp implementations (and thus E-Lisp, due to RMS’s enamorment with old Lisps), but should not be used except for backward compatibility.

Function: lax-plists-eq a b &optional nil-means-not-present

This function returns non-`nil` if lax property lists A and B are `eq` (i.e. their values are `eq`; their keys are still compared using `equal`).

Function: lax-plists-equal a b &optional nil-means-not-present

This function returns non-`nil` if lax property lists A and B are `equal` (i.e. their values are `equal`).

Function: canonicalize-lax-plist lax-plist &optional nil-means-not-present

This function destructively removes any duplicate entries from a lax plist. In such cases, the first entry applies.

The new plist is returned. If nil-means-not-present is given, the return value may not be `eq` to the passed-in value, so make sure to `setq` the value back into where it came from.

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

11.9.3 Converting Plists To/From Alists

Function: alist-to-plist alist

This function converts association list alist into the equivalent property-list form. The plist is returned. This converts from

 ```((a . 1) (b . 2) (c . 3)) ```

into

 ```(a 1 b 2 c 3) ```

The original alist is not modified.

Function: plist-to-alist plist

This function converts property list plist into the equivalent association-list form. The alist is returned. This converts from

 ```(a 1 b 2 c 3) ```

into

 ```((a . 1) (b . 2) (c . 3)) ```

The original plist is not modified.

The following two functions are equivalent to the preceding two except that they destructively modify their arguments, using cons cells from the original list to form the new list rather than allocating new cons cells.

Function: destructive-alist-to-plist alist

This function destructively converts association list alist into the equivalent property-list form. The plist is returned.

Function: destructive-plist-to-alist plist

This function destructively converts property list plist into the equivalent association-list form. The alist is returned.

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

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.