1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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.
605 (setq xy (add-foo '(3 4))) ; What happened?
611 (symbol-function 'add-foo)
612 => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
614 - Function: nreverse LIST
615 This function reverses the order of the elements of LIST. Unlike
616 `reverse', `nreverse' alters its argument by reversing the CDRs in
617 the cons cells forming the list. The cons cell that used to be
618 the last one in LIST becomes the first cell of the value.
628 ;; The cell that was first is now last.
632 To avoid confusion, we usually store the result of `nreverse' back
633 in the same variable which held the original list:
635 (setq x (nreverse x))
637 Here is the `nreverse' of our favorite example, `(a b c)',
638 presented graphically:
640 Original list head: Reversed list:
641 ------------- ------------- ------------
642 | car | cdr | | car | cdr | | car | cdr |
643 | a | nil |<-- | b | o |<-- | c | o |
644 | | | | | | | | | | | | |
645 ------------- | --------- | - | -------- | -
647 ------------- ------------
649 - Function: sort LIST PREDICATE
650 This function sorts LIST stably, though destructively, and returns
651 the sorted list. It compares elements using PREDICATE. A stable
652 sort is one in which elements with equal sort keys maintain their
653 relative order before and after the sort. Stability is important
654 when successive sorts are used to order elements according to
657 The argument PREDICATE must be a function that accepts two
658 arguments. It is called with two elements of LIST. To get an
659 increasing order sort, the PREDICATE should return `t' if the
660 first element is "less than" the second, or `nil' if not.
662 The destructive aspect of `sort' is that it rearranges the cons
663 cells forming LIST by changing CDRs. A nondestructive sort
664 function would create new cons cells to store the elements in their
665 sorted order. If you wish to make a sorted copy without
666 destroying the original, copy it first with `copy-sequence' and
669 Sorting does not change the CARs of the cons cells in LIST; the
670 cons cell that originally contained the element `a' in LIST still
671 has `a' in its CAR after sorting, but it now appears in a
672 different position in the list due to the change of CDRs. For
675 (setq nums '(1 3 2 6 5 4 0))
682 Note that the list in `nums' no longer contains 0; this is the same
683 cons cell that it was before, but it is no longer the first one in
684 the list. Don't assume a variable that formerly held the argument
685 now holds the entire sorted list! Instead, save the result of
686 `sort' and use that. Most often we store the result back into the
687 variable that held the original list:
689 (setq nums (sort nums '<))
691 *Note Sorting::, for more functions that perform sorting. See
692 `documentation' in *Note Accessing Documentation::, for a useful
696 File: lispref.info, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists
701 A list can represent an unordered mathematical set--simply consider a
702 value an element of a set if it appears in the list, and ignore the
703 order of the list. To form the union of two sets, use `append' (as
704 long as you don't mind having duplicate elements). Other useful
705 functions for sets include `memq' and `delq', and their `equal'
706 versions, `member' and `delete'.
708 Common Lisp note: Common Lisp has functions `union' (which avoids
709 duplicate elements) and `intersection' for set operations, but
710 XEmacs Lisp does not have them. You can write them in Lisp if you
713 - Function: memq OBJECT LIST
714 This function tests to see whether OBJECT is a member of LIST. If
715 it is, `memq' returns a list starting with the first occurrence of
716 OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq'
717 says that it uses `eq' to compare OBJECT against the elements of
718 the list. For example:
720 (memq 'b '(a b c b a))
722 (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
725 - Function: delq OBJECT LIST
726 This function destructively removes all elements `eq' to OBJECT
727 from LIST. The letter `q' in `delq' says that it uses `eq' to
728 compare OBJECT against the elements of the list, like `memq'.
730 When `delq' deletes elements from the front of the list, it does so
731 simply by advancing down the list and returning a sublist that starts
732 after those elements:
734 (delq 'a '(a b c)) == (cdr '(a b c))
736 When an element to be deleted appears in the middle of the list,
737 removing it involves changing the CDRs (*note Setcdr::.).
739 (setq sample-list '(a b c (4)))
741 (delq 'a sample-list)
745 (delq 'c sample-list)
750 Note that `(delq 'c sample-list)' modifies `sample-list' to splice
751 out the third element, but `(delq 'a sample-list)' does not splice
752 anything--it just returns a shorter list. Don't assume that a variable
753 which formerly held the argument LIST now has fewer elements, or that
754 it still holds the original list! Instead, save the result of `delq'
755 and use that. Most often we store the result back into the variable
756 that held the original list:
758 (setq flowers (delq 'rose flowers))
760 In the following example, the `(4)' that `delq' attempts to match
761 and the `(4)' in the `sample-list' are not `eq':
763 (delq '(4) sample-list)
766 The following two functions are like `memq' and `delq' but use
767 `equal' rather than `eq' to compare elements. They are new in Emacs 19.
769 - Function: member OBJECT LIST
770 The function `member' tests to see whether OBJECT is a member of
771 LIST, comparing members with OBJECT using `equal'. If OBJECT is a
772 member, `member' returns a list starting with its first occurrence
773 in LIST. Otherwise, it returns `nil'.
775 Compare this with `memq':
777 (member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'.
779 (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
781 ;; Two strings with the same contents are `equal'.
782 (member "foo" '("foo" "bar"))
785 - Function: delete OBJECT LIST
786 This function destructively removes all elements `equal' to OBJECT
787 from LIST. It is to `delq' as `member' is to `memq': it uses
788 `equal' to compare elements with OBJECT, like `member'; when it
789 finds an element that matches, it removes the element just as
790 `delq' would. For example:
792 (delete '(2) '((2) (1) (2)))
795 Common Lisp note: The functions `member' and `delete' in XEmacs
796 Lisp are derived from Maclisp, not Common Lisp. The Common Lisp
797 versions do not use `equal' to compare elements.
799 See also the function `add-to-list', in *Note Setting Variables::,
800 for another way to add an element to a list stored in a variable.
803 File: lispref.info, Node: Association Lists, Next: Property Lists, Prev: Sets And Lists, Up: Lists
808 An "association list", or "alist" for short, records a mapping from
809 keys to values. It is a list of cons cells called "associations": the
810 CAR of each cell is the "key", and the CDR is the "associated value".(1)
812 Here is an example of an alist. The key `pine' is associated with
813 the value `cones'; the key `oak' is associated with `acorns'; and the
814 key `maple' is associated with `seeds'.
820 The associated values in an alist may be any Lisp objects; so may the
821 keys. For example, in the following alist, the symbol `a' is
822 associated with the number `1', and the string `"b"' is associated with
823 the *list* `(2 3)', which is the CDR of the alist element:
827 Sometimes it is better to design an alist to store the associated
828 value in the CAR of the CDR of the element. Here is an example:
830 '((rose red) (lily white) (buttercup yellow))
832 Here we regard `red' as the value associated with `rose'. One
833 advantage of this method is that you can store other related
834 information--even a list of other items--in the CDR of the CDR. One
835 disadvantage is that you cannot use `rassq' (see below) to find the
836 element containing a given value. When neither of these considerations
837 is important, the choice is a matter of taste, as long as you are
838 consistent about it for any given alist.
840 Note that the same alist shown above could be regarded as having the
841 associated value in the CDR of the element; the value associated with
842 `rose' would be the list `(red)'.
844 Association lists are often used to record information that you might
845 otherwise keep on a stack, since new associations may be added easily to
846 the front of the list. When searching an association list for an
847 association with a given key, the first one found is returned, if there
850 In XEmacs Lisp, it is *not* an error if an element of an association
851 list is not a cons cell. The alist search functions simply ignore such
852 elements. Many other versions of Lisp signal errors in such cases.
854 Note that property lists are similar to association lists in several
855 respects. A property list behaves like an association list in which
856 each key can occur only once. *Note Property Lists::, for a comparison
857 of property lists and association lists.
859 - Function: assoc KEY ALIST
860 This function returns the first association for KEY in ALIST. It
861 compares KEY against the alist elements using `equal' (*note
862 Equality Predicates::.). It returns `nil' if no association in
863 ALIST has a CAR `equal' to KEY. For example:
865 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
866 => ((pine . cones) (oak . acorns) (maple . seeds))
869 (cdr (assoc 'oak trees))
874 Here is another example, in which the keys and values are not
877 (setq needles-per-cluster
878 '((2 "Austrian Pine" "Red Pine")
882 (cdr (assoc 3 needles-per-cluster))
884 (cdr (assoc 2 needles-per-cluster))
885 => ("Austrian Pine" "Red Pine")
887 - Function: rassoc VALUE ALIST
888 This function returns the first association with value VALUE in
889 ALIST. It returns `nil' if no association in ALIST has a CDR
892 `rassoc' is like `assoc' except that it compares the CDR of each
893 ALIST association instead of the CAR. You can think of this as
894 "reverse `assoc'", finding the key for a given value.
896 - Function: assq KEY ALIST
897 This function is like `assoc' in that it returns the first
898 association for KEY in ALIST, but it makes the comparison using
899 `eq' instead of `equal'. `assq' returns `nil' if no association
900 in ALIST has a CAR `eq' to KEY. This function is used more often
901 than `assoc', since `eq' is faster than `equal' and most alists
902 use symbols as keys. *Note Equality Predicates::.
904 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
905 => ((pine . cones) (oak . acorns) (maple . seeds))
909 On the other hand, `assq' is not usually useful in alists where the
910 keys may not be symbols:
913 '(("simple leaves" . oak)
914 ("compound leaves" . horsechestnut)))
916 (assq "simple leaves" leaves)
918 (assoc "simple leaves" leaves)
919 => ("simple leaves" . oak)
921 - Function: rassq VALUE ALIST
922 This function returns the first association with value VALUE in
923 ALIST. It returns `nil' if no association in ALIST has a CDR `eq'
926 `rassq' is like `assq' except that it compares the CDR of each
927 ALIST association instead of the CAR. You can think of this as
928 "reverse `assq'", finding the key for a given value.
932 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
934 (rassq 'acorns trees)
936 (rassq 'spores trees)
939 Note that `rassq' cannot search for a value stored in the CAR of
940 the CDR of an element:
942 (setq colors '((rose red) (lily white) (buttercup yellow)))
944 (rassq 'white colors)
947 In this case, the CDR of the association `(lily white)' is not the
948 symbol `white', but rather the list `(white)'. This becomes
949 clearer if the association is written in dotted pair notation:
951 (lily white) == (lily . (white))
953 - Function: remassoc KEY ALIST
954 This function deletes by side effect any associations with key KEY
955 in ALIST - i.e. it removes any elements from ALIST whose `car' is
956 `equal' to KEY. The modified ALIST is returned.
958 If the first member of ALIST has a `car' that is `equal' to KEY,
959 there is no way to remove it by side effect; therefore, write
960 `(setq foo (remassoc key foo))' to be sure of changing the value
963 - Function: remassq KEY ALIST
964 This function deletes by side effect any associations with key KEY
965 in ALIST - i.e. it removes any elements from ALIST whose `car' is
966 `eq' to KEY. The modified ALIST is returned.
968 This function is exactly like `remassoc', but comparisons between
969 KEY and keys in ALIST are done using `eq' instead of `equal'.
971 - Function: remrassoc VALUE ALIST
972 This function deletes by side effect any associations with value
973 VALUE in ALIST - i.e. it removes any elements from ALIST whose
974 `cdr' is `equal' to VALUE. The modified ALIST is returned.
976 If the first member of ALIST has a `car' that is `equal' to VALUE,
977 there is no way to remove it by side effect; therefore, write
978 `(setq foo (remassoc value foo))' to be sure of changing the value
981 `remrassoc' is like `remassoc' except that it compares the CDR of
982 each ALIST association instead of the CAR. You can think of this
983 as "reverse `remassoc'", removing an association based on its
984 value instead of its key.
986 - Function: remrassq VALUE ALIST
987 This function deletes by side effect any associations with value
988 VALUE in ALIST - i.e. it removes any elements from ALIST whose
989 `cdr' is `eq' to VALUE. The modified ALIST is returned.
991 This function is exactly like `remrassoc', but comparisons between
992 VALUE and values in ALIST are done using `eq' instead of `equal'.
994 - Function: copy-alist ALIST
995 This function returns a two-level deep copy of ALIST: it creates a
996 new copy of each association, so that you can alter the
997 associations of the new alist without changing the old one.
999 (setq needles-per-cluster
1000 '((2 . ("Austrian Pine" "Red Pine"))
1001 (3 . ("Pitch Pine"))
1002 (5 . ("White Pine"))))
1004 ((2 "Austrian Pine" "Red Pine")
1008 (setq copy (copy-alist needles-per-cluster))
1010 ((2 "Austrian Pine" "Red Pine")
1014 (eq needles-per-cluster copy)
1016 (equal needles-per-cluster copy)
1018 (eq (car needles-per-cluster) (car copy))
1020 (cdr (car (cdr needles-per-cluster)))
1022 (eq (cdr (car (cdr needles-per-cluster)))
1023 (cdr (car (cdr copy))))
1026 This example shows how `copy-alist' makes it possible to change
1027 the associations of one copy without affecting the other:
1029 (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
1030 (cdr (assq 3 needles-per-cluster))
1033 ---------- Footnotes ----------
1035 (1) This usage of "key" is not related to the term "key sequence";
1036 it means a value used to look up an item in a table. In this case, the
1037 table is the alist, and the alist associations are the items.
1040 File: lispref.info, Node: Property Lists, Next: Weak Lists, Prev: Association Lists, Up: Lists
1045 A "property list" (or "plist") is another way of representing a
1046 mapping from keys to values. Instead of the list consisting of conses
1047 of a key and a value, the keys and values alternate as successive
1048 entries in the list. Thus, the association list
1050 ((a . 1) (b . 2) (c . 3))
1052 has the equivalent property list form
1056 Property lists are used to represent the properties associated with
1057 various sorts of objects, such as symbols, strings, frames, etc. The
1058 convention is that property lists can be modified in-place, while
1059 association lists generally are not.
1061 Plists come in two varieties: "normal" plists, whose keys are
1062 compared with `eq', and "lax" plists, whose keys are compared with
1065 - Function: valid-plist-p PLIST
1066 Given a plist, this function returns non-`nil' if its format is
1067 correct. If it returns `nil', `check-valid-plist' will signal an
1068 error when given the plist; that means it's a malformed or circular
1069 plist or has non-symbols as keywords.
1071 - Function: check-valid-plist PLIST
1072 Given a plist, this function signals an error if there is anything
1073 wrong with it. This means that it's a malformed or circular plist.
1077 * Working With Normal Plists:: Functions for normal plists.
1078 * Working With Lax Plists:: Functions for lax plists.
1079 * Converting Plists To/From Alists:: Alist to plist and vice-versa.
1082 File: lispref.info, Node: Working With Normal Plists, Next: Working With Lax Plists, Up: Property Lists
1084 Working With Normal Plists
1085 --------------------------
1087 - Function: plist-get PLIST PROP &optional DEFAULT
1088 This function extracts a value from a property list. The function
1089 returns the value corresponding to the given PROP, or DEFAULT if
1090 PROP is not one of the properties on the list.
1092 - Function: plist-put PLIST PROP VAL
1093 This function changes the value in PLIST of PROP to VAL. If PROP
1094 is already a property on the list, its value is set to VAL,
1095 otherwise the new PROP VAL pair is added. The new plist is
1096 returned; use `(setq x (plist-put x prop val))' to be sure to use
1097 the new value. The PLIST is modified by side effects.
1099 - Function: plist-remprop PLIST PROP
1100 This function removes from PLIST the property PROP and its value.
1101 The new plist is returned; use `(setq x (plist-remprop x prop
1102 val))' to be sure to use the new value. The PLIST is modified by
1105 - Function: plist-member PLIST PROP
1106 This function returns `t' if PROP has a value specified in PLIST.
1108 In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
1109 non-`nil', then a property with a `nil' value is ignored or removed.
1110 This feature is a virus that has infected old Lisp implementations (and
1111 thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
1112 used except for backward compatibility.
1114 - Function: plists-eq A B &optional NIL-MEANS-NOT-PRESENT
1115 This function returns non-`nil' if property lists A and B are `eq'
1116 (i.e. their values are `eq').
1118 - Function: plists-equal A B &optional NIL-MEANS-NOT-PRESENT
1119 This function returns non-`nil' if property lists A and B are
1120 `equal' (i.e. their values are `equal'; their keys are still
1121 compared using `eq').
1123 - Function: canonicalize-plist PLIST &optional NIL-MEANS-NOT-PRESENT
1124 This function destructively removes any duplicate entries from a
1125 plist. In such cases, the first entry applies.
1127 The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
1128 return value may not be `eq' to the passed-in value, so make sure
1129 to `setq' the value back into where it came from.
1132 File: lispref.info, Node: Working With Lax Plists, Next: Converting Plists To/From Alists, Prev: Working With Normal Plists, Up: Property Lists
1134 Working With Lax Plists
1135 -----------------------
1137 Recall that a "lax plist" is a property list whose keys are compared
1138 using `equal' instead of `eq'.
1140 - Function: lax-plist-get LAX-PLIST PROP &optional DEFAULT
1141 This function extracts a value from a lax property list. The
1142 function returns the value corresponding to the given PROP, or
1143 DEFAULT if PROP is not one of the properties on the list.
1145 - Function: lax-plist-put LAX-PLIST PROP VAL
1146 This function changes the value in LAX-PLIST of PROP to VAL.
1148 - Function: lax-plist-remprop LAX-PLIST PROP
1149 This function removes from LAX-PLIST the property PROP and its
1150 value. The new plist is returned; use `(setq x (lax-plist-remprop
1151 x prop val))' to be sure to use the new value. The LAX-PLIST is
1152 modified by side effects.
1154 - Function: lax-plist-member LAX-PLIST PROP
1155 This function returns `t' if PROP has a value specified in
1158 In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
1159 non-`nil', then a property with a `nil' value is ignored or removed.
1160 This feature is a virus that has infected old Lisp implementations (and
1161 thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
1162 used except for backward compatibility.
1164 - Function: lax-plists-eq A B &optional NIL-MEANS-NOT-PRESENT
1165 This function returns non-`nil' if lax property lists A and B are
1166 `eq' (i.e. their values are `eq'; their keys are still compared
1169 - Function: lax-plists-equal A B &optional NIL-MEANS-NOT-PRESENT
1170 This function returns non-`nil' if lax property lists A and B are
1171 `equal' (i.e. their values are `equal').
1173 - Function: canonicalize-lax-plist LAX-PLIST &optional
1174 NIL-MEANS-NOT-PRESENT
1175 This function destructively removes any duplicate entries from a
1176 lax plist. In such cases, the first entry applies.
1178 The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
1179 return value may not be `eq' to the passed-in value, so make sure
1180 to `setq' the value back into where it came from.
1183 File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists
1185 Converting Plists To/From Alists
1186 --------------------------------
1188 - Function: alist-to-plist ALIST
1189 This function converts association list ALIST into the equivalent
1190 property-list form. The plist is returned. This converts from
1192 ((a . 1) (b . 2) (c . 3))
1198 The original alist is not modified.
1200 - Function: plist-to-alist PLIST
1201 This function converts property list PLIST into the equivalent
1202 association-list form. The alist is returned. This converts from
1208 ((a . 1) (b . 2) (c . 3))
1210 The original plist is not modified.
1212 The following two functions are equivalent to the preceding two
1213 except that they destructively modify their arguments, using cons cells
1214 from the original list to form the new list rather than allocating new
1217 - Function: destructive-alist-to-plist ALIST
1218 This function destructively converts association list ALIST into
1219 the equivalent property-list form. The plist is returned.
1221 - Function: destructive-plist-to-alist PLIST
1222 This function destructively converts property list PLIST into the
1223 equivalent association-list form. The alist is returned.
1226 File: lispref.info, Node: Weak Lists, Prev: Property Lists, Up: Lists
1231 A "weak list" is a special sort of list whose members are not counted
1232 as references for the purpose of garbage collection. This means that,
1233 for any object in the list, if there are no references to the object
1234 anywhere outside of the list (or other weak list or weak hash table),
1235 that object will disappear the next time a garbage collection happens.
1236 Weak lists can be useful for keeping track of things such as unobtrusive
1237 lists of another function's buffers or markers. When that function is
1238 done with the elements, they will automatically disappear from the list.
1240 Weak lists are used internally, for example, to manage the list
1241 holding the children of an extent - an extent that is unused but has a
1242 parent will still be reclaimed, and will automatically be removed from
1243 its parent's list of children.
1245 Weak lists are similar to weak hash tables (*note Weak Hash
1248 - Function: weak-list-p OBJECT
1249 This function returns non-`nil' if OBJECT is a weak list.
1251 Weak lists come in one of four types:
1254 Objects in the list disappear if not referenced outside of the
1258 Objects in the list disappear if they are conses and either the
1259 car or the cdr of the cons is not referenced outside of the list.
1262 Objects in the list disappear if they are conses and the car is not
1263 referenced outside of the list.
1266 Objects in the list disappear if they are conses and the cdr is not
1267 referenced outside of the list.
1269 - Function: make-weak-list &optional TYPE
1270 This function creates a new weak list of type TYPE. TYPE is a
1271 symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
1272 as described above) and defaults to `simple'.
1274 - Function: weak-list-type WEAK
1275 This function returns the type of the given weak-list object.
1277 - Function: weak-list-list WEAK
1278 This function returns the list contained in a weak-list object.
1280 - Function: set-weak-list-list WEAK NEW-LIST
1281 This function changes the list contained in a weak-list object.
1284 File: lispref.info, Node: Sequences Arrays Vectors, Next: Symbols, Prev: Lists, Up: Top
1286 Sequences, Arrays, and Vectors
1287 ******************************
1289 Recall that the "sequence" type is the union of four other Lisp
1290 types: lists, vectors, bit vectors, and strings. In other words, any
1291 list is a sequence, any vector is a sequence, any bit vector is a
1292 sequence, and any string is a sequence. The common property that all
1293 sequences have is that each is an ordered collection of elements.
1295 An "array" is a single primitive object that has a slot for each
1296 elements. All the elements are accessible in constant time, but the
1297 length of an existing array cannot be changed. Strings, vectors, and
1298 bit vectors are the three types of arrays.
1300 A list is a sequence of elements, but it is not a single primitive
1301 object; it is made of cons cells, one cell per element. Finding the
1302 Nth element requires looking through N cons cells, so elements farther
1303 from the beginning of the list take longer to access. But it is
1304 possible to add elements to the list, or remove elements.
1306 The following diagram shows the relationship between these types:
1308 ___________________________________
1311 | ______ ______________________ |
1313 | | List | | Array | |
1314 | | | | ________ _______ | |
1315 | |______| | | | | | | |
1316 | | | Vector | | String| | |
1317 | | |________| |_______| | |
1318 | | __________________ | |
1320 | | | Bit Vector | | |
1321 | | |__________________| | |
1322 | |______________________| |
1323 |___________________________________|
1325 The elements of vectors and lists may be any Lisp objects. The
1326 elements of strings are all characters. The elements of bit vectors
1327 are the numbers 0 and 1.
1331 * Sequence Functions:: Functions that accept any kind of sequence.
1332 * Arrays:: Characteristics of arrays in XEmacs Lisp.
1333 * Array Functions:: Functions specifically for arrays.
1334 * Vectors:: Special characteristics of XEmacs Lisp vectors.
1335 * Vector Functions:: Functions specifically for vectors.
1336 * Bit Vectors:: Special characteristics of XEmacs Lisp bit vectors.
1337 * Bit Vector Functions:: Functions specifically for bit vectors.