This is elisp, produced by makeinfo version 4.0f from ./elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 21.2. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Copying", with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: elisp, Node: Cons Cells, Next: Lists as Boxes, Up: Lists 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. That is, it has two slots, and each slot "holds", or "refers to", some Lisp object. One slot is known as the CAR, and the other is known as the CDR. (These names are traditional; see *Note Cons Cell Type::.) CDR is pronounced "could-er." We say that "the CAR of this cons cell is" whatever object its CAR slot currently holds, and likewise for the CDR. A list is a series of cons cells "chained together," so that each cell refers to the next one. There is one cons cell for each element of the list. By convention, the CARs of the cons cells hold the elements of the list, and the CDRs are used to chain the list: the CDR slot of each cons cell refers to 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.  File: elisp, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists 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 "holds" a Lisp object. (These terms are synonymous.) The first box, which describes the CAR of the first cons cell, contains the symbol `tulip'. The arrow from the CDR box of the first cons cell to the second cons cell indicates that the CDR of the first cons cell is 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 | | | | | | | -------------- ---------------- *Note Cons Cell Type::, for the read and print syntax of cons cells and lists, and for more "box and arrow" illustrations of lists.  File: elisp, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists 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'. (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: 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 *Note Combining Conditions::). (null '(1)) => nil (null '()) => t  File: elisp, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists Accessing Elements of Lists =========================== - Function: car cons-cell This function returns the value referred to by the first slot 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 referred to by the second slot 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)) - Macro: pop listname This macro is a way of examining the CAR of a list, and taking it off the list, all at once. It is new in Emacs 21. It operates on the list which is stored in the symbol LISTNAME. It removes this element from the list by setting LISTNAME to the CDR of its old value--but it also returns the CAR of that list, which is the element being removed. x => (a b c) (pop x) => a x => (b c) - 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)) The function `elt' is similar, but applies to any kind of sequence. For historical reasons, it takes its arguments in the opposite order. *Note Sequence Functions::. - Function: nthcdr n list This function returns the Nth CDR of LIST. In other words, it skips past 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) - Function: last list &optional n This function returns the last link of LIST. The `car' of this link is the list's last element. If LIST is null, `nil' is returned. If N is non-nil the N-th-to-last link is returned instead, or the whole LIST if N is bigger than LIST's length. - Function: safe-length list This function returns the length of LIST, with no risk of either an error or an infinite loop. If LIST is not really a list, `safe-length' returns 0. If LIST is circular, it returns a finite value which is at least the number of distinct elements. The most common way to compute the length of a list, when you are not worried that it may be circular, is with `length'. *Note Sequence Functions::. - Function: caar cons-cell This is the same as `(car (car CONS-CELL))'. - Function: cadr cons-cell This is the same as `(car (cdr CONS-CELL))' or `(nth 1 CONS-CELL)'. - Function: cdar cons-cell This is the same as `(cdr (car CONS-CELL))'. - Function: cddr cons-cell This is the same as `(cdr (cdr CONS-CELL))' or `(nthcdr 2 CONS-CELL)'. - Function: butlast x &optional n This function returns the list X with the last element, or the last N elements, removed. If N is greater than zero it makes a copy of the list so as not to damage the original list. In general, `(append (butlast X N) (last X N))' will return a list equal to X. - Function: nbutlast x &optional n This is a version of `butlast' that works by destructively modifying the `cdr' of the appropriate element, rather than making a copy of the list.  File: elisp, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists 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". (1) 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. - Macro: push newelt listname This macro provides an alternative way to write `(setq LISTNAME (cons NEWELT LISTNAME))'. It is new in Emacs 21. (setq l '(a b)) => (a b) (push 'c l) => (c a b) l => (c a b) - 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 elements, in which each element is OBJECT. Compare `make-list' with `make-string' (*note Creating Strings::). (make-list 3 'pigs) => (pigs pigs pigs) (make-list 0 'pigs) => nil (setq l (make-list 3 '(a b)) => ((a b) (a b) (a b)) (eq (car l) (cadr l)) => t - Function: append &rest sequences This function returns a list containing all the elements of SEQUENCES. The SEQUENCES may be lists, vectors, bool-vectors, or strings, but the last one should usually be a list. All arguments except the last one are copied, so none of the arguments is altered. (See `nconc' in *Note Rearrangement::, for a way to join lists with no copying.) 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. 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' (*note Formatting Strings::) or `number-to-string' (*note String Conversion::). 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 nil)) => (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. *Note Sequences Arrays Vectors::. Here we show the use of vectors and strings as arguments to `append': (append [a b] "cd" nil) => (a b 99 100) With the help of `apply' (*note Calling Functions::), 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. - Function: reverse list This function creates a new list whose elements are the elements of LIST, but in reverse order. The original argument LIST is _not_ altered. (setq x '(1 2 3 4)) => (1 2 3 4) (reverse x) => (4 3 2 1) x => (1 2 3 4) - Function: remq object list This function returns a copy of LIST, with all elements removed which are `eq' to OBJECT. The letter `q' in `remq' says that it uses `eq' to compare OBJECT against the elements of `list'. (setq sample-list '(a b c a b c)) => (a b c a b c) (remq 'a sample-list) => (b c b c) sample-list => (a b c a b c) The function `delq' offers a way to perform this operation destructively. See *Note Sets And Lists::. ---------- Footnotes ---------- (1) There is no strictly equivalent way to add an element to the end of a list. You can use `(append LISTNAME (list NEWELT))', which creates a whole new list by copying LISTNAME and adding NEWELT to its end. Or you can use `(nconc LISTNAME (list NEWELT))', which modifies LISTNAME by following all the CDRs and then replacing the terminating `nil'. Compare this to adding an element to the beginning of a list with `cons', which neither copies nor modifies the list.  File: elisp, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists Modifying Existing List Structure ================================= You can modify the CAR and CDR contents of a cons cell with the primitives `setcar' and `setcdr'. We call these "destructive" operations because they change existing list structure. 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. * Menu: * Setcar:: Replacing an element in a list. * Setcdr:: Replacing part of the list backbone. This can be used to remove or add elements. * Rearrangement:: Reordering the elements in a list; combining lists.  File: elisp, Node: Setcar, Next: Setcdr, Up: Modifying Lists 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 object This function stores OBJECT as the new CAR of CONS, replacing its previous CAR. In other words, it changes the CAR slot of CONS to refer to OBJECT. 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---- | | | --------------  File: elisp, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists Altering the CDR of a List -------------------------- The lowest-level primitive for modifying a CDR is `setcdr': - Function: setcdr cons object This function stores OBJECT as the new CDR of CONS, replacing its previous CDR. In other words, it changes the CDR slot of CONS to refer to OBJECT. 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 cons 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------ | | | ---------------  File: elisp, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists 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, relinking their cons cells to form a new list that is the returned value. See `delq', in *Note Sets And Lists::, for another function that modifies cons cells. - Function: nconc &rest lists This function returns a list containing all the elements of LISTS. Unlike `append' (*note Building 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) However, the other arguments (all but the last) must be lists. 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 list This function reverses the order of the elements of LIST. Unlike `reverse', `nreverse' alters its argument by reversing the CDRs in the cons cells forming the list. The cons cell that used to be the last one in LIST becomes the first cons cell of the value. For example: (setq x '(a b c)) => (a b c) x => (a b c) (nreverse x) => (c b a) ;; The cons cell that was first is now last. x => (a) To avoid confusion, we usually store the result of `nreverse' back in the same variable which held the original list: (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 list predicate This function sorts LIST stably, though destructively, and returns the sorted list. 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. The argument PREDICATE must be a function that accepts two arguments. It is called with two elements of LIST. 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 comparison function PREDICATE must give reliable results for any given pair of arguments, at least within a single call to `sort'. It must be "antisymmetric"; that is, if A is less than B, B must not be less than A. It must be "transitive"--that is, if A is less than B, and B is less than C, then A must be less than C. If you use a comparison function which does not meet these requirements, the result of `sort' is unpredictable. The destructive aspect of `sort' is that it rearranges the cons cells forming LIST by changing CDRs. A nondestructive sort function would create new cons cells to store the elements in their sorted order. If you wish to make a sorted copy without destroying the original, copy it first with `copy-sequence' and then sort. Sorting does not change the CARs of the cons cells in LIST; the cons cell that originally contained the element `a' in LIST still has `a' in its CAR after sorting, but it now appears in a different position in the list 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) *Warning*: 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 list: (setq nums (sort nums '<)) *Note Sorting::, for more functions that perform sorting. See `documentation' in *Note Accessing Documentation::, for a useful example of `sort'.  File: elisp, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists 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. To form the union of two sets, use `append' (as long as you don't mind having duplicate elements). Other useful functions for sets include `memq' and `delq', and their `equal' versions, `member' and `delete'. Common Lisp note: Common Lisp has functions `union' (which avoids duplicate elements) and `intersection' for set operations, but GNU Emacs Lisp does not have them. You can write them in Lisp if you wish. - Function: memq object list This function tests to see whether OBJECT is a member of LIST. If it is, `memq' returns a list starting with the first occurrence of OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq' says that it uses `eq' to compare OBJECT against the elements of the list. For example: (memq 'b '(a b c b a)) => (b c b a) (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'. => nil - Function: member-ignore-case object list This function is like `member', except that it ignores differences in letter-case and text representation: upper-case and lower-case letters are treated as equal, and unibyte strings are converted to multibyte prior to comparison. - Function: delq object list This function destructively removes all elements `eq' to OBJECT from LIST. The letter `q' in `delq' says that it uses `eq' to compare OBJECT against the elements of the list, like `memq' and `remq'. When `delq' deletes elements from the front of the list, it does so simply by advancing down the list and returning a sublist that starts after those elements: (delq 'a '(a b c)) == (cdr '(a b c)) When an element to be deleted appears in the middle of the list, removing it involves changing the CDRs (*note Setcdr::). (setq sample-list '(a b c (4))) => (a b c (4)) (delq 'a sample-list) => (b c (4)) sample-list => (a b c (4)) (delq 'c sample-list) => (a b (4)) sample-list => (a b (4)) Note that `(delq 'c sample-list)' modifies `sample-list' to splice out the third element, but `(delq 'a sample-list)' does not splice anything--it just returns a shorter list. 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 `delq' and use that. Most often we store the result back into the variable that held the original list: (setq flowers (delq 'rose flowers)) In the following example, the `(4)' that `delq' attempts to match and the `(4)' in the `sample-list' are not `eq': (delq '(4) sample-list) => (a c (4)) The following two functions are like `memq' and `delq' but use `equal' rather than `eq' to compare elements. *Note Equality Predicates::. - Function: member object list The function `member' tests to see whether OBJECT is a member of LIST, comparing members with OBJECT using `equal'. If OBJECT is a member, `member' returns a list starting with its first occurrence in LIST. Otherwise, it returns `nil'. Compare this with `memq': (member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'. => ((2)) (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'. => nil ;; Two strings with the same contents are `equal'. (member "foo" '("foo" "bar")) => ("foo" "bar") - Function: delete object sequence If `sequence' is a list, this function destructively removes all elements `equal' to OBJECT from SEQUENCE. For lists, `delete' is to `delq' as `member' is to `memq': it uses `equal' to compare elements with OBJECT, like `member'; when it finds an element that matches, it removes the element just as `delq' would. If `sequence' is a vector or string, `delete' returns a copy of `sequence' with all elements `equal' to `object' removed. For example: (delete '(2) '((2) (1) (2))) => ((1)) (delete '(2) [(2) (1) (2)]) => [(1)] - Function: remove object sequence This function is the non-destructive counterpart of `delete'. If returns a copy of `sequence', a list, vector, or string, with elements `equal' to `object' removed. For example: (remove '(2) '((2) (1) (2))) => ((1)) (remove '(2) [(2) (1) (2)]) => [(1)] Common Lisp note: The functions `member', `delete' and `remove' in GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common Lisp versions do not use `equal' to compare elements. See also the function `add-to-list', in *Note Setting Variables::, for another way to add an element to a list stored in a variable.  File: elisp, Node: Association Lists, Prev: Sets And Lists, Up: Lists 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 cons 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 of such an alist: ((rose red) (lily white) (buttercup yellow)) Here we regard `red' as the value associated with `rose'. One advantage of this kind of alist 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 Emacs 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. 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. *Note Property Lists::, for a comparison of property lists and association lists. - Function: assoc key alist This function returns the first association for KEY in ALIST. It compares KEY against the alist elements using `equal' (*note Equality Predicates::). 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 functions `assoc-ignore-representation' and `assoc-ignore-case' are much like `assoc' except using `compare-strings' to do the comparison. *Note Text Comparison::. - Function: rassoc value alist This function returns the first association with value VALUE in ALIST. It returns `nil' if no association in ALIST has a CDR `equal' 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. - Function: assq key alist This function is like `assoc' in that it returns the first association for KEY in ALIST, but it makes the comparison using `eq' instead of `equal'. `assq' returns `nil' if no association in ALIST has a CAR `eq' to KEY. This function is used more often than `assoc', since `eq' is faster than `equal' and most alists use symbols as keys. *Note Equality Predicates::. (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) => ((pine . cones) (oak . acorns) (maple . seeds)) (assq 'pine trees) => (pine . cones) On the other hand, `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 function returns the first association with value VALUE in ALIST. It returns `nil' if no association in ALIST has a CDR `eq' to VALUE. `rassq' is like `assq' except that it compares the CDR of each ALIST association instead of the CAR. You can think of this as "reverse `assq'", finding the key for a given value. 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: assoc-default key alist &optional test default This function searches ALIST for a match for KEY. For each element of ALIST, it compares the element (if it is an atom) or the element's CAR (if it is a cons) against KEY, by calling TEST with two arguments: the element or its CAR, and KEY. The arguments are passed in that order so that you can get useful results using `string-match' with an alist that contains regular expressions (*note Regexp Search::). If TEST is omitted or `nil', `equal' is used for comparison. If an alist element matches KEY by this criterion, then `assoc-default' returns a value based on this element. If the element is a cons, then the value is the element's CDR. Otherwise, the return value is DEFAULT. If no alist element matches KEY, `assoc-default' returns `nil'. - 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") - Function: assq-delete-all key alist This function deletes from ALIST all the elements whose CAR is `eq' to KEY. It returns ALIST, modified in this way. Note that it modifies the original list structure of ALIST. (assq-delete-all 'foo '((foo 1) (bar 2) (foo 3) (lose 4))) => ((bar 2) (lose 4)) ---------- Footnotes ---------- (1) This usage of "key" is not related to the term "key sequence"; it means a value used to look up an item in a table. In this case, the table is the alist, and the alist associations are the items.  File: elisp, Node: Sequences Arrays Vectors, Next: Hash Tables, Prev: Lists, Up: Top Sequences, Arrays, and Vectors ****************************** Recall that the "sequence" type is the union of two other Lisp types: lists and arrays. In other words, any list is a sequence, and any array is a sequence. The common property that all sequences have is that each is an ordered collection of elements. An "array" is a single primitive object that has a slot for each of its elements. All the elements are accessible in constant time, but the length of an existing array cannot be changed. Strings, vectors, char-tables and bool-vectors are the four types of arrays. A list is a sequence of elements, but it is not a single primitive object; it is made of cons cells, one cell per element. Finding the Nth element requires looking through N cons cells, so elements farther from the beginning of the list take longer to access. But it is possible to add elements to the list, or remove elements. The following diagram shows the relationship between these types: _____________________________________________ | | | Sequence | | ______ ________________________________ | | | | | | | | | List | | Array | | | | | | ________ ________ | | | |______| | | | | | | | | | | Vector | | String | | | | | |________| |________| | | | | ____________ _____________ | | | | | | | | | | | | | Char-table | | Bool-vector | | | | | |____________| |_____________| | | | |________________________________| | |_____________________________________________| The elements of vectors and lists may be any Lisp objects. The elements of strings are all characters. * Menu: * Sequence Functions:: Functions that accept any kind of sequence. * Arrays:: Characteristics of arrays in Emacs Lisp. * Array Functions:: Functions specifically for arrays. * Vectors:: Special characteristics of Emacs Lisp vectors. * Vector Functions:: Functions specifically for vectors. * Char-Tables:: How to work with char-tables. * Bool-Vectors:: How to work with bool-vectors.