1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists
55 Accessing Elements of Lists
56 ===========================
58 - Function: car cons-cell
59 This function returns the value pointed to by the first pointer of
60 the cons cell CONS-CELL. Expressed another way, this function
61 returns the CAR of CONS-CELL.
63 As a special case, if CONS-CELL is `nil', then `car' is defined to
64 return `nil'; therefore, any list is a valid argument for `car'.
65 An error is signaled if the argument is not a cons cell or `nil'.
72 - Function: cdr cons-cell
73 This function returns the value pointed to by the second pointer of
74 the cons cell CONS-CELL. Expressed another way, this function
75 returns the CDR of CONS-CELL.
77 As a special case, if CONS-CELL is `nil', then `cdr' is defined to
78 return `nil'; therefore, any list is a valid argument for `cdr'.
79 An error is signaled if the argument is not a cons cell or `nil'.
86 - Function: car-safe object
87 This function lets you take the CAR of a cons cell while avoiding
88 errors for other data types. It returns the CAR of OBJECT if
89 OBJECT is a cons cell, `nil' otherwise. This is in contrast to
90 `car', which signals an error if OBJECT is not a list.
99 - Function: cdr-safe object
100 This function lets you take the CDR of a cons cell while avoiding
101 errors for other data types. It returns the CDR of OBJECT if
102 OBJECT is a cons cell, `nil' otherwise. This is in contrast to
103 `cdr', which signals an error if OBJECT is not a list.
112 - Function: nth n list
113 This function returns the Nth element of LIST. Elements are
114 numbered starting with zero, so the CAR of LIST is element number
115 zero. If the length of LIST is N or less, the value is `nil'.
117 If N is negative, `nth' returns the first element of LIST.
126 (nth n x) == (car (nthcdr n x))
128 - Function: nthcdr n list
129 This function returns the Nth CDR of LIST. In other words, it
130 removes the first N links of LIST and returns what follows.
132 If N is zero or negative, `nthcdr' returns all of LIST. If the
133 length of LIST is N or less, `nthcdr' returns `nil'.
135 (nthcdr 1 '(1 2 3 4))
137 (nthcdr 10 '(1 2 3 4))
139 (nthcdr -3 '(1 2 3 4))
142 Many convenience functions are provided to make it easier for you to
143 access particular elements in a nested list. All of these can be
144 rewritten in terms of the functions just described.
146 - Function: caar cons-cell
147 - Function: cadr cons-cell
148 - Function: cdar cons-cell
149 - Function: cddr cons-cell
150 - Function: caaar cons-cell
151 - Function: caadr cons-cell
152 - Function: cadar cons-cell
153 - Function: caddr cons-cell
154 - Function: cdaar cons-cell
155 - Function: cdadr cons-cell
156 - Function: cddar cons-cell
157 - Function: cdddr cons-cell
158 - Function: caaaar cons-cell
159 - Function: caaadr cons-cell
160 - Function: caadar cons-cell
161 - Function: caaddr cons-cell
162 - Function: cadaar cons-cell
163 - Function: cadadr cons-cell
164 - Function: caddar cons-cell
165 - Function: cadddr cons-cell
166 - Function: cdaaar cons-cell
167 - Function: cdaadr cons-cell
168 - Function: cdadar cons-cell
169 - Function: cdaddr cons-cell
170 - Function: cddaar cons-cell
171 - Function: cddadr cons-cell
172 - Function: cdddar cons-cell
173 - Function: cddddr cons-cell
174 Each of these functions is equivalent to one or more applications
175 of `car' and/or `cdr'. For example,
189 (cdr (car (cdr (cdr x))))
191 That is to say, read the a's and d's from right to left and apply
192 a `car' or `cdr' for each a or d found, respectively.
194 - Function: first list
195 This is equivalent to `(nth 0 LIST)', i.e. the first element of
196 LIST. (Note that this is also equivalent to `car'.)
198 - Function: second list
199 This is equivalent to `(nth 1 LIST)', i.e. the second element of
202 - Function: third list
203 - Function: fourth list
204 - Function: fifth list
205 - Function: sixth list
206 - Function: seventh list
207 - Function: eighth list
208 - Function: ninth list
209 - Function: tenth list
210 These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
211 respectively, i.e. the third through tenth elements of LIST.
214 File: lispref.info, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists
216 Building Cons Cells and Lists
217 =============================
219 Many functions build lists, as lists reside at the very heart of
220 Lisp. `cons' is the fundamental list-building function; however, it is
221 interesting to note that `list' is used more times in the source code
222 for Emacs than `cons'.
224 - Function: cons object1 object2
225 This function is the fundamental function used to build new list
226 structure. It creates a new cons cell, making OBJECT1 the CAR,
227 and OBJECT2 the CDR. It then returns the new cons cell. The
228 arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
229 often OBJECT2 is a list.
238 `cons' is often used to add a single element to the front of a
239 list. This is called "consing the element onto the list". For
242 (setq list (cons newelt list))
244 Note that there is no conflict between the variable named `list'
245 used in this example and the function named `list' described below;
246 any symbol can serve both purposes.
248 - Function: list &rest objects
249 This function creates a list with OBJECTS as its elements. The
250 resulting list is always `nil'-terminated. If no OBJECTS are
251 given, the empty list is returned.
255 (list 1 2 '(3 4 5) 'foo)
260 - Function: make-list length object
261 This function creates a list of length LENGTH, in which all the
262 elements have the identical value OBJECT. Compare `make-list'
263 with `make-string' (*note Creating Strings::).
270 - Function: append &rest sequences
271 This function returns a list containing all the elements of
272 SEQUENCES. The SEQUENCES may be lists, vectors, or strings, but
273 the last one should be a list. All arguments except the last one
274 are copied, so none of them are altered.
276 More generally, the final argument to `append' may be any Lisp
277 object. The final argument is not copied or converted; it becomes
278 the CDR of the last cons cell in the new list. If the final
279 argument is itself a list, then its elements become in effect
280 elements of the result list. If the final element is not a list,
281 the result is a "dotted list" since its final CDR is not `nil' as
282 required in a true list.
284 See `nconc' in *Note Rearrangement::, for a way to join lists with
287 Here is an example of using `append':
289 (setq trees '(pine oak))
291 (setq more-trees (append '(maple birch) trees))
292 => (maple birch pine oak)
297 => (maple birch pine oak)
298 (eq trees (cdr (cdr more-trees)))
301 You can see how `append' works by looking at a box diagram. The
302 variable `trees' is set to the list `(pine oak)' and then the
303 variable `more-trees' is set to the list `(maple birch pine oak)'.
304 However, the variable `trees' continues to refer to the original
309 | ___ ___ ___ ___ -> ___ ___ ___ ___
310 --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
313 --> maple -->birch --> pine --> oak
315 An empty sequence contributes nothing to the value returned by
316 `append'. As a consequence of this, a final `nil' argument forces
317 a copy of the previous argument.
321 (setq wood (append trees ()))
328 This once was the usual way to copy a list, before the function
329 `copy-sequence' was invented. *Note Sequences Arrays Vectors::.
331 With the help of `apply', we can append all the lists in a list of
334 (apply 'append '((a b c) nil (x y z) nil))
337 If no SEQUENCES are given, `nil' is returned:
342 Here are some examples where the final argument is not a list:
349 The second example shows that when the final argument is a
350 sequence but not a list, the sequence's elements do not become
351 elements of the resulting list. Instead, the sequence becomes the
352 final CDR, like any other non-list final argument.
354 The `append' function also allows integers as arguments. It
355 converts them to strings of digits, making up the decimal print
356 representation of the integer, and then uses the strings instead
357 of the original integers. *Don't use this feature; we plan to
358 eliminate it. If you already use this feature, change your
359 programs now!* The proper way to convert an integer to a decimal
360 number in this way is with `format' (*note Formatting Strings::)
361 or `number-to-string' (*note String Conversion::).
363 - Function: reverse list
364 This function creates a new list whose elements are the elements of
365 LIST, but in reverse order. The original argument LIST is _not_
376 File: lispref.info, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists
378 Modifying Existing List Structure
379 =================================
381 You can modify the CAR and CDR contents of a cons cell with the
382 primitives `setcar' and `setcdr'.
384 Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
385 to alter list structure; they change structure the same way as
386 `setcar' and `setcdr', but the Common Lisp functions return the
387 cons cell while `setcar' and `setcdr' return the new CAR or CDR.
391 * Setcar:: Replacing an element in a list.
392 * Setcdr:: Replacing part of the list backbone.
393 This can be used to remove or add elements.
394 * Rearrangement:: Reordering the elements in a list; combining lists.
397 File: lispref.info, Node: Setcar, Next: Setcdr, Up: Modifying Lists
399 Altering List Elements with `setcar'
400 ------------------------------------
402 Changing the CAR of a cons cell is done with `setcar'. When used on
403 a list, `setcar' replaces one element of a list with a different
406 - Function: setcar cons object
407 This function stores OBJECT as the new CAR of CONS, replacing its
408 previous CAR. It returns the value OBJECT. For example:
417 When a cons cell is part of the shared structure of several lists,
418 storing a new CAR into the cons changes one element of each of these
419 lists. Here is an example:
421 ;; Create two lists that are partly shared.
424 (setq x2 (cons 'z (cdr x1)))
427 ;; Replace the CAR of a shared link.
428 (setcar (cdr x1) 'foo)
430 x1 ; Both lists are changed.
435 ;; Replace the CAR of a link that is not shared.
438 x1 ; Only one list is changed.
443 Here is a graphical depiction of the shared structure of the two
444 lists in the variables `x1' and `x2', showing why replacing `b' changes
447 ___ ___ ___ ___ ___ ___
448 x1---> |___|___|----> |___|___|--> |___|___|--> nil
459 Here is an alternative form of box diagram, showing the same
463 -------------- -------------- --------------
464 | car | cdr | | car | cdr | | car | cdr |
465 | a | o------->| b | o------->| c | nil |
467 -------------- | -------------- --------------
477 File: lispref.info, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists
479 Altering the CDR of a List
480 --------------------------
482 The lowest-level primitive for modifying a CDR is `setcdr':
484 - Function: setcdr cons object
485 This function stores OBJECT as the new CDR of CONS, replacing its
486 previous CDR. It returns the value OBJECT.
488 Here is an example of replacing the CDR of a list with a different
489 list. All but the first element of the list are removed in favor of a
490 different sequence of elements. The first element is unchanged,
491 because it resides in the CAR of the list, and is not reached via the
501 You can delete elements from the middle of a list by altering the
502 CDRs of the cons cells in the list. For example, here we delete the
503 second element, `b', from the list `(a b c)', by changing the CDR of
508 (setcdr x1 (cdr (cdr x1)))
513 Here is the result in box notation:
517 -------------- | -------------- | --------------
518 | car | cdr | | | car | cdr | -->| car | cdr |
519 | a | o----- | b | o-------->| c | nil |
521 -------------- -------------- --------------
523 The second cons cell, which previously held the element `b', still
524 exists and its CAR is still `b', but it no longer forms part of this
527 It is equally easy to insert a new element by changing CDRs:
531 (setcdr x1 (cons 'd (cdr x1)))
536 Here is this result in box notation:
538 -------------- ------------- -------------
539 | car | cdr | | car | cdr | | car | cdr |
540 | a | o | -->| b | o------->| c | nil |
541 | | | | | | | | | | |
542 --------- | -- | ------------- -------------
553 File: lispref.info, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists
555 Functions that Rearrange Lists
556 ------------------------------
558 Here are some functions that rearrange lists "destructively" by
559 modifying the CDRs of their component cons cells. We call these
560 functions "destructive" because they chew up the original lists passed
561 to them as arguments, to produce a new list that is the returned value.
563 See `delq', in *Note Sets And Lists::, for another function that
566 - Function: nconc &rest lists
567 This function returns a list containing all the elements of LISTS.
568 Unlike `append' (*note Building Lists::), the LISTS are _not_
569 copied. Instead, the last CDR of each of the LISTS is changed to
570 refer to the following list. The last of the LISTS is not
571 altered. For example:
580 Since the last argument of `nconc' is not itself modified, it is
581 reasonable to use a constant list, such as `'(4 5)', as in the
582 above example. For the same reason, the last argument need not be
592 A common pitfall is to use a quoted constant list as a non-last
593 argument to `nconc'. If you do this, your program will change
594 each time you run it! Here is what happens:
596 (defun add-foo (x) ; We want this function to add
597 (nconc '(foo) x)) ; `foo' to the front of its arg.
599 (symbol-function 'add-foo)
600 => (lambda (x) (nconc (quote (foo)) x))
602 (setq xx (add-foo '(1 2))) ; It seems to work.
604 (setq xy (add-foo '(3 4))) ; What happened?
609 (symbol-function 'add-foo)
610 => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
612 - Function: nreverse list
613 This function reverses the order of the elements of LIST. Unlike
614 `reverse', `nreverse' alters its argument by reversing the CDRs in
615 the cons cells forming the list. The cons cell that used to be
616 the last one in LIST becomes the first cell of the value.
626 ;; The cell that was first is now last.
630 To avoid confusion, we usually store the result of `nreverse' back
631 in the same variable which held the original list:
633 (setq x (nreverse x))
635 Here is the `nreverse' of our favorite example, `(a b c)',
636 presented graphically:
638 Original list head: Reversed list:
639 ------------- ------------- ------------
640 | car | cdr | | car | cdr | | car | cdr |
641 | a | nil |<-- | b | o |<-- | c | o |
642 | | | | | | | | | | | | |
643 ------------- | --------- | - | -------- | -
645 ------------- ------------
647 - Function: sort list predicate
648 This function sorts LIST stably, though destructively, and returns
649 the sorted list. It compares elements using PREDICATE. A stable
650 sort is one in which elements with equal sort keys maintain their
651 relative order before and after the sort. Stability is important
652 when successive sorts are used to order elements according to
655 The argument PREDICATE must be a function that accepts two
656 arguments. It is called with two elements of LIST. To get an
657 increasing order sort, the PREDICATE should return `t' if the
658 first element is "less than" the second, or `nil' if not.
660 The destructive aspect of `sort' is that it rearranges the cons
661 cells forming LIST by changing CDRs. A nondestructive sort
662 function would create new cons cells to store the elements in their
663 sorted order. If you wish to make a sorted copy without
664 destroying the original, copy it first with `copy-sequence' and
667 Sorting does not change the CARs of the cons cells in LIST; the
668 cons cell that originally contained the element `a' in LIST still
669 has `a' in its CAR after sorting, but it now appears in a
670 different position in the list due to the change of CDRs. For
673 (setq nums '(1 3 2 6 5 4 0))
680 Note that the list in `nums' no longer contains 0; this is the same
681 cons cell that it was before, but it is no longer the first one in
682 the list. Don't assume a variable that formerly held the argument
683 now holds the entire sorted list! Instead, save the result of
684 `sort' and use that. Most often we store the result back into the
685 variable that held the original list:
687 (setq nums (sort nums '<))
689 *Note Sorting::, for more functions that perform sorting. See
690 `documentation' in *Note Accessing Documentation::, for a useful
694 File: lispref.info, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists
699 A list can represent an unordered mathematical set--simply consider a
700 value an element of a set if it appears in the list, and ignore the
701 order of the list. To form the union of two sets, use `append' (as
702 long as you don't mind having duplicate elements). Other useful
703 functions for sets include `memq' and `delq', and their `equal'
704 versions, `member' and `delete'.
706 Common Lisp note: Common Lisp has functions `union' (which avoids
707 duplicate elements) and `intersection' for set operations, but
708 XEmacs Lisp does not have them. You can write them in Lisp if you
711 - Function: memq object list
712 This function tests to see whether OBJECT is a member of LIST. If
713 it is, `memq' returns a list starting with the first occurrence of
714 OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq'
715 says that it uses `eq' to compare OBJECT against the elements of
716 the list. For example:
718 (memq 'b '(a b c b a))
720 (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
723 - Function: delq object list
724 This function destructively removes all elements `eq' to OBJECT
725 from LIST. The letter `q' in `delq' says that it uses `eq' to
726 compare OBJECT against the elements of the list, like `memq'.
728 When `delq' deletes elements from the front of the list, it does so
729 simply by advancing down the list and returning a sublist that starts
730 after those elements:
732 (delq 'a '(a b c)) == (cdr '(a b c))
734 When an element to be deleted appears in the middle of the list,
735 removing it involves changing the CDRs (*note Setcdr::).
737 (setq sample-list '(a b c (4)))
739 (delq 'a sample-list)
743 (delq 'c sample-list)
748 Note that `(delq 'c sample-list)' modifies `sample-list' to splice
749 out the third element, but `(delq 'a sample-list)' does not splice
750 anything--it just returns a shorter list. Don't assume that a variable
751 which formerly held the argument LIST now has fewer elements, or that
752 it still holds the original list! Instead, save the result of `delq'
753 and use that. Most often we store the result back into the variable
754 that held the original list:
756 (setq flowers (delq 'rose flowers))
758 In the following example, the `(4)' that `delq' attempts to match
759 and the `(4)' in the `sample-list' are not `eq':
761 (delq '(4) sample-list)
764 The following two functions are like `memq' and `delq' but use
765 `equal' rather than `eq' to compare elements. They are new in Emacs 19.
767 - Function: member object list
768 The function `member' tests to see whether OBJECT is a member of
769 LIST, comparing members with OBJECT using `equal'. If OBJECT is a
770 member, `member' returns a list starting with its first occurrence
771 in LIST. Otherwise, it returns `nil'.
773 Compare this with `memq':
775 (member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'.
777 (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
779 ;; Two strings with the same contents are `equal'.
780 (member "foo" '("foo" "bar"))
783 - Function: delete object list
784 This function destructively removes all elements `equal' to OBJECT
785 from LIST. It is to `delq' as `member' is to `memq': it uses
786 `equal' to compare elements with OBJECT, like `member'; when it
787 finds an element that matches, it removes the element just as
788 `delq' would. For example:
790 (delete '(2) '((2) (1) (2)))
793 Common Lisp note: The functions `member' and `delete' in XEmacs
794 Lisp are derived from Maclisp, not Common Lisp. The Common Lisp
795 versions do not use `equal' to compare elements.
797 See also the function `add-to-list', in *Note Setting Variables::,
798 for another way to add an element to a list stored in a variable.
801 File: lispref.info, Node: Association Lists, Next: Property Lists, Prev: Sets And Lists, Up: Lists
806 An "association list", or "alist" for short, records a mapping from
807 keys to values. It is a list of cons cells called "associations": the
808 CAR of each cell is the "key", and the CDR is the "associated value".(1)
810 Here is an example of an alist. The key `pine' is associated with
811 the value `cones'; the key `oak' is associated with `acorns'; and the
812 key `maple' is associated with `seeds'.
818 The associated values in an alist may be any Lisp objects; so may the
819 keys. For example, in the following alist, the symbol `a' is
820 associated with the number `1', and the string `"b"' is associated with
821 the _list_ `(2 3)', which is the CDR of the alist element:
825 Sometimes it is better to design an alist to store the associated
826 value in the CAR of the CDR of the element. Here is an example:
828 '((rose red) (lily white) (buttercup yellow))
830 Here we regard `red' as the value associated with `rose'. One
831 advantage of this method is that you can store other related
832 information--even a list of other items--in the CDR of the CDR. One
833 disadvantage is that you cannot use `rassq' (see below) to find the
834 element containing a given value. When neither of these considerations
835 is important, the choice is a matter of taste, as long as you are
836 consistent about it for any given alist.
838 Note that the same alist shown above could be regarded as having the
839 associated value in the CDR of the element; the value associated with
840 `rose' would be the list `(red)'.
842 Association lists are often used to record information that you might
843 otherwise keep on a stack, since new associations may be added easily to
844 the front of the list. When searching an association list for an
845 association with a given key, the first one found is returned, if there
848 In XEmacs Lisp, it is _not_ an error if an element of an association
849 list is not a cons cell. The alist search functions simply ignore such
850 elements. Many other versions of Lisp signal errors in such cases.
852 Note that property lists are similar to association lists in several
853 respects. A property list behaves like an association list in which
854 each key can occur only once. *Note Property Lists::, for a comparison
855 of property lists and association lists.
857 - Function: assoc key alist
858 This function returns the first association for KEY in ALIST. It
859 compares KEY against the alist elements using `equal' (*note
860 Equality Predicates::). It returns `nil' if no association in
861 ALIST has a CAR `equal' to KEY. For example:
863 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
864 => ((pine . cones) (oak . acorns) (maple . seeds))
867 (cdr (assoc 'oak trees))
872 Here is another example, in which the keys and values are not
875 (setq needles-per-cluster
876 '((2 "Austrian Pine" "Red Pine")
880 (cdr (assoc 3 needles-per-cluster))
882 (cdr (assoc 2 needles-per-cluster))
883 => ("Austrian Pine" "Red Pine")
885 - Function: rassoc value alist
886 This function returns the first association with value VALUE in
887 ALIST. It returns `nil' if no association in ALIST has a CDR
890 `rassoc' is like `assoc' except that it compares the CDR of each
891 ALIST association instead of the CAR. You can think of this as
892 "reverse `assoc'", finding the key for a given value.
894 - Function: assq key alist
895 This function is like `assoc' in that it returns the first
896 association for KEY in ALIST, but it makes the comparison using
897 `eq' instead of `equal'. `assq' returns `nil' if no association
898 in ALIST has a CAR `eq' to KEY. This function is used more often
899 than `assoc', since `eq' is faster than `equal' and most alists
900 use symbols as keys. *Note Equality Predicates::.
902 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
903 => ((pine . cones) (oak . acorns) (maple . seeds))
907 On the other hand, `assq' is not usually useful in alists where the
908 keys may not be symbols:
911 '(("simple leaves" . oak)
912 ("compound leaves" . horsechestnut)))
914 (assq "simple leaves" leaves)
916 (assoc "simple leaves" leaves)
917 => ("simple leaves" . oak)
919 - Function: rassq value alist
920 This function returns the first association with value VALUE in
921 ALIST. It returns `nil' if no association in ALIST has a CDR `eq'
924 `rassq' is like `assq' except that it compares the CDR of each
925 ALIST association instead of the CAR. You can think of this as
926 "reverse `assq'", finding the key for a given value.
930 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
932 (rassq 'acorns trees)
934 (rassq 'spores trees)
937 Note that `rassq' cannot search for a value stored in the CAR of
938 the CDR of an element:
940 (setq colors '((rose red) (lily white) (buttercup yellow)))
942 (rassq 'white colors)
945 In this case, the CDR of the association `(lily white)' is not the
946 symbol `white', but rather the list `(white)'. This becomes
947 clearer if the association is written in dotted pair notation:
949 (lily white) == (lily . (white))
951 - Function: remassoc key alist
952 This function deletes by side effect any associations with key KEY
953 in ALIST--i.e. it removes any elements from ALIST whose `car' is
954 `equal' to KEY. The modified ALIST is returned.
956 If the first member of ALIST has a `car' that is `equal' to KEY,
957 there is no way to remove it by side effect; therefore, write
958 `(setq foo (remassoc key foo))' to be sure of changing the value
961 - Function: remassq key alist
962 This function deletes by side effect any associations with key KEY
963 in ALIST--i.e. it removes any elements from ALIST whose `car' is
964 `eq' to KEY. The modified ALIST is returned.
966 This function is exactly like `remassoc', but comparisons between
967 KEY and keys in ALIST are done using `eq' instead of `equal'.
969 - Function: remrassoc value alist
970 This function deletes by side effect any associations with value
971 VALUE in ALIST--i.e. it removes any elements from ALIST whose
972 `cdr' is `equal' to VALUE. The modified ALIST is returned.
974 If the first member of ALIST has a `car' that is `equal' to VALUE,
975 there is no way to remove it by side effect; therefore, write
976 `(setq foo (remassoc value foo))' to be sure of changing the value
979 `remrassoc' is like `remassoc' except that it compares the CDR of
980 each ALIST association instead of the CAR. You can think of this
981 as "reverse `remassoc'", removing an association based on its
982 value instead of its key.
984 - Function: remrassq value alist
985 This function deletes by side effect any associations with value
986 VALUE in ALIST--i.e. it removes any elements from ALIST whose
987 `cdr' is `eq' to VALUE. The modified ALIST is returned.
989 This function is exactly like `remrassoc', but comparisons between
990 VALUE and values in ALIST are done using `eq' instead of `equal'.
992 - Function: copy-alist alist
993 This function returns a two-level deep copy of ALIST: it creates a
994 new copy of each association, so that you can alter the
995 associations of the new alist without changing the old one.
997 (setq needles-per-cluster
998 '((2 . ("Austrian Pine" "Red Pine"))
1000 (5 . ("White Pine"))))
1002 ((2 "Austrian Pine" "Red Pine")
1006 (setq copy (copy-alist needles-per-cluster))
1008 ((2 "Austrian Pine" "Red Pine")
1012 (eq needles-per-cluster copy)
1014 (equal needles-per-cluster copy)
1016 (eq (car needles-per-cluster) (car copy))
1018 (cdr (car (cdr needles-per-cluster)))
1020 (eq (cdr (car (cdr needles-per-cluster)))
1021 (cdr (car (cdr copy))))
1024 This example shows how `copy-alist' makes it possible to change
1025 the associations of one copy without affecting the other:
1027 (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
1028 (cdr (assq 3 needles-per-cluster))
1031 ---------- Footnotes ----------
1033 (1) This usage of "key" is not related to the term "key sequence";
1034 it means a value used to look up an item in a table. In this case, the
1035 table is the alist, and the alist associations are the items.
1038 File: lispref.info, Node: Property Lists, Next: Weak Lists, Prev: Association Lists, Up: Lists
1043 A "property list" (or "plist") is another way of representing a
1044 mapping from keys to values. Instead of the list consisting of conses
1045 of a key and a value, the keys and values alternate as successive
1046 entries in the list. Thus, the association list
1048 ((a . 1) (b . 2) (c . 3))
1050 has the equivalent property list form
1054 Property lists are used to represent the properties associated with
1055 various sorts of objects, such as symbols, strings, frames, etc. The
1056 convention is that property lists can be modified in-place, while
1057 association lists generally are not.
1059 Plists come in two varieties: "normal" plists, whose keys are
1060 compared with `eq', and "lax" plists, whose keys are compared with
1063 - Function: valid-plist-p plist
1064 Given a plist, this function returns non-`nil' if its format is
1065 correct. If it returns `nil', `check-valid-plist' will signal an
1066 error when given the plist; that means it's a malformed or circular
1067 plist or has non-symbols as keywords.
1069 - Function: check-valid-plist plist
1070 Given a plist, this function signals an error if there is anything
1071 wrong with it. This means that it's a malformed or circular plist.
1075 * Working With Normal Plists:: Functions for normal plists.
1076 * Working With Lax Plists:: Functions for lax plists.
1077 * Converting Plists To/From Alists:: Alist to plist and vice-versa.
1080 File: lispref.info, Node: Working With Normal Plists, Next: Working With Lax Plists, Up: Property Lists
1082 Working With Normal Plists
1083 --------------------------
1085 - Function: plist-get plist prop &optional default
1086 This function extracts a value from a property list. The function
1087 returns the value corresponding to the given PROP, or DEFAULT if
1088 PROP is not one of the properties on the list.
1090 - Function: plist-put plist prop val
1091 This function changes the value in PLIST of PROP to VAL. If PROP
1092 is already a property on the list, its value is set to VAL,
1093 otherwise the new PROP VAL pair is added. The new plist is
1094 returned; use `(setq x (plist-put x prop val))' to be sure to use
1095 the new value. The PLIST is modified by side effects.
1097 - Function: plist-remprop plist prop
1098 This function removes from PLIST the property PROP and its value.
1099 The new plist is returned; use `(setq x (plist-remprop x prop
1100 val))' to be sure to use the new value. The PLIST is modified by
1103 - Function: plist-member plist prop
1104 This function returns `t' if PROP has a value specified in PLIST.
1106 In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
1107 non-`nil', then a property with a `nil' value is ignored or removed.
1108 This feature is a virus that has infected old Lisp implementations (and
1109 thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
1110 used except for backward compatibility.
1112 - Function: plists-eq a b &optional nil-means-not-present
1113 This function returns non-`nil' if property lists A and B are `eq'
1114 (i.e. their values are `eq').
1116 - Function: plists-equal a b &optional nil-means-not-present
1117 This function returns non-`nil' if property lists A and B are
1118 `equal' (i.e. their values are `equal'; their keys are still
1119 compared using `eq').
1121 - Function: canonicalize-plist plist &optional nil-means-not-present
1122 This function destructively removes any duplicate entries from a
1123 plist. In such cases, the first entry applies.
1125 The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
1126 return value may not be `eq' to the passed-in value, so make sure
1127 to `setq' the value back into where it came from.
1130 File: lispref.info, Node: Working With Lax Plists, Next: Converting Plists To/From Alists, Prev: Working With Normal Plists, Up: Property Lists
1132 Working With Lax Plists
1133 -----------------------
1135 Recall that a "lax plist" is a property list whose keys are compared
1136 using `equal' instead of `eq'.
1138 - Function: lax-plist-get lax-plist prop &optional default
1139 This function extracts a value from a lax property list. The
1140 function returns the value corresponding to the given PROP, or
1141 DEFAULT if PROP is not one of the properties on the list.
1143 - Function: lax-plist-put lax-plist prop val
1144 This function changes the value in LAX-PLIST of PROP to VAL.
1146 - Function: lax-plist-remprop lax-plist prop
1147 This function removes from LAX-PLIST the property PROP and its
1148 value. The new plist is returned; use `(setq x (lax-plist-remprop
1149 x prop val))' to be sure to use the new value. The LAX-PLIST is
1150 modified by side effects.
1152 - Function: lax-plist-member lax-plist prop
1153 This function returns `t' if PROP has a value specified in
1156 In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
1157 non-`nil', then a property with a `nil' value is ignored or removed.
1158 This feature is a virus that has infected old Lisp implementations (and
1159 thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
1160 used except for backward compatibility.
1162 - Function: lax-plists-eq a b &optional nil-means-not-present
1163 This function returns non-`nil' if lax property lists A and B are
1164 `eq' (i.e. their values are `eq'; their keys are still compared
1167 - Function: lax-plists-equal a b &optional nil-means-not-present
1168 This function returns non-`nil' if lax property lists A and B are
1169 `equal' (i.e. their values are `equal').
1171 - Function: canonicalize-lax-plist lax-plist &optional
1172 nil-means-not-present
1173 This function destructively removes any duplicate entries from a
1174 lax plist. In such cases, the first entry applies.
1176 The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
1177 return value may not be `eq' to the passed-in value, so make sure
1178 to `setq' the value back into where it came from.
1181 File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists
1183 Converting Plists To/From Alists
1184 --------------------------------
1186 - Function: alist-to-plist alist
1187 This function converts association list ALIST into the equivalent
1188 property-list form. The plist is returned. This converts from
1190 ((a . 1) (b . 2) (c . 3))
1196 The original alist is not modified.
1198 - Function: plist-to-alist plist
1199 This function converts property list PLIST into the equivalent
1200 association-list form. The alist is returned. This converts from
1206 ((a . 1) (b . 2) (c . 3))
1208 The original plist is not modified.
1210 The following two functions are equivalent to the preceding two
1211 except that they destructively modify their arguments, using cons cells
1212 from the original list to form the new list rather than allocating new
1215 - Function: destructive-alist-to-plist alist
1216 This function destructively converts association list ALIST into
1217 the equivalent property-list form. The plist is returned.
1219 - Function: destructive-plist-to-alist plist
1220 This function destructively converts property list PLIST into the
1221 equivalent association-list form. The alist is returned.
1224 File: lispref.info, Node: Weak Lists, Prev: Property Lists, Up: Lists
1229 A "weak list" is a special sort of list whose members are not counted
1230 as references for the purpose of garbage collection. This means that,
1231 for any object in the list, if there are no references to the object
1232 anywhere outside of the list (or other weak list or weak hash table),
1233 that object will disappear the next time a garbage collection happens.
1234 Weak lists can be useful for keeping track of things such as unobtrusive
1235 lists of another function's buffers or markers. When that function is
1236 done with the elements, they will automatically disappear from the list.
1238 Weak lists are used internally, for example, to manage the list
1239 holding the children of an extent--an extent that is unused but has a
1240 parent will still be reclaimed, and will automatically be removed from
1241 its parent's list of children.
1243 Weak lists are similar to weak hash tables (*note Weak Hash
1246 - Function: weak-list-p object
1247 This function returns non-`nil' if OBJECT is a weak list.
1249 Weak lists come in one of four types:
1252 Objects in the list disappear if not referenced outside of the
1256 Objects in the list disappear if they are conses and either the
1257 car or the cdr of the cons is not referenced outside of the list.
1260 Objects in the list disappear if they are conses and the car is not
1261 referenced outside of the list.
1264 Objects in the list disappear if they are conses and the cdr is not
1265 referenced outside of the list.
1267 - Function: make-weak-list &optional type
1268 This function creates a new weak list of type TYPE. TYPE is a
1269 symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
1270 as described above) and defaults to `simple'.
1272 - Function: weak-list-type weak
1273 This function returns the type of the given weak-list object.
1275 - Function: weak-list-list weak
1276 This function returns the list contained in a weak-list object.
1278 - Function: set-weak-list-list weak new-list
1279 This function changes the list contained in a weak-list object.
1282 File: lispref.info, Node: Sequences Arrays Vectors, Next: Symbols, Prev: Lists, Up: Top
1284 Sequences, Arrays, and Vectors
1285 ******************************
1287 Recall that the "sequence" type is the union of four other Lisp
1288 types: lists, vectors, bit vectors, and strings. In other words, any
1289 list is a sequence, any vector is a sequence, any bit vector is a
1290 sequence, and any string is a sequence. The common property that all
1291 sequences have is that each is an ordered collection of elements.
1293 An "array" is a single primitive object that has a slot for each
1294 elements. All the elements are accessible in constant time, but the
1295 length of an existing array cannot be changed. Strings, vectors, and
1296 bit vectors are the three types of arrays.
1298 A list is a sequence of elements, but it is not a single primitive
1299 object; it is made of cons cells, one cell per element. Finding the
1300 Nth element requires looking through N cons cells, so elements farther
1301 from the beginning of the list take longer to access. But it is
1302 possible to add elements to the list, or remove elements.
1304 The following diagram shows the relationship between these types:
1306 ___________________________________
1309 | ______ ______________________ |
1311 | | List | | Array | |
1312 | | | | ________ _______ | |
1313 | |______| | | | | | | |
1314 | | | Vector | | String| | |
1315 | | |________| |_______| | |
1316 | | __________________ | |
1318 | | | Bit Vector | | |
1319 | | |__________________| | |
1320 | |______________________| |
1321 |___________________________________|
1323 The elements of vectors and lists may be any Lisp objects. The
1324 elements of strings are all characters. The elements of bit vectors
1325 are the numbers 0 and 1.
1329 * Sequence Functions:: Functions that accept any kind of sequence.
1330 * Arrays:: Characteristics of arrays in XEmacs Lisp.
1331 * Array Functions:: Functions specifically for arrays.
1332 * Vectors:: Special characteristics of XEmacs Lisp vectors.
1333 * Vector Functions:: Functions specifically for vectors.
1334 * Bit Vectors:: Special characteristics of XEmacs Lisp bit vectors.
1335 * Bit Vector Functions:: Functions specifically for bit vectors.