2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2017 Free Software
5 @c See the file elisp.texi for copying conditions.
9 @cindex element (of list)
11 A @dfn{list} represents a sequence of zero or more elements (which may
12 be any Lisp objects). The important difference between lists and
13 vectors is that two or more lists can share part of their structure; in
14 addition, you can insert or delete elements in a list without copying
18 * Cons Cells:: How lists are made out of cons cells.
19 * List-related Predicates:: Is this object a list? Comparing two lists.
20 * List Elements:: Extracting the pieces of a list.
21 * Building Lists:: Creating list structure.
22 * List Variables:: Modifying lists stored in variables.
23 * Modifying Lists:: Storing new pieces into an existing list.
24 * Sets And Lists:: A list can represent a finite mathematical set.
25 * Association Lists:: A list can represent a finite relation or mapping.
26 * Property Lists:: A list of paired elements.
30 @section Lists and Cons Cells
31 @cindex lists and cons cells
33 Lists in Lisp are not a primitive data type; they are built up from
34 @dfn{cons cells} (@pxref{Cons Cell Type}). A cons cell is a data
35 object that represents an ordered pair. That is, it has two slots,
36 and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object. One
37 slot is known as the @sc{car}, and the other is known as the @sc{cdr}.
38 (These names are traditional; see @ref{Cons Cell Type}.) @sc{cdr} is
39 pronounced ``could-er''.
41 We say that ``the @sc{car} of this cons cell is'' whatever object
42 its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
44 A list is a series of cons cells chained together, so that each
45 cell refers to the next one. There is one cons cell for each element
46 of the list. By convention, the @sc{car}s of the cons cells hold the
47 elements of the list, and the @sc{cdr}s are used to chain the list
48 (this asymmetry between @sc{car} and @sc{cdr} is entirely a matter of
49 convention; at the level of cons cells, the @sc{car} and @sc{cdr}
50 slots have similar properties). Hence, the @sc{cdr} slot of each cons
51 cell in a list refers to the following cons cell.
54 Also by convention, the @sc{cdr} of the last cons cell in a list is
55 @code{nil}. We call such a @code{nil}-terminated structure a
56 @dfn{true list}. In Emacs Lisp, the symbol @code{nil} is both a
57 symbol and a list with no elements. For convenience, the symbol
58 @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
61 Hence, the @sc{cdr} of a true list is always a true list. The
62 @sc{cdr} of a nonempty true list is a true list containing all the
63 elements except the first.
67 If the @sc{cdr} of a list's last cons cell is some value other than
68 @code{nil}, we call the structure a @dfn{dotted list}, since its
69 printed representation would use dotted pair notation (@pxref{Dotted
70 Pair Notation}). There is one other possibility: some cons cell's
71 @sc{cdr} could point to one of the previous cons cells in the list.
72 We call that structure a @dfn{circular list}.
74 For some purposes, it does not matter whether a list is true,
75 circular or dotted. If a program doesn't look far enough down the
76 list to see the @sc{cdr} of the final cons cell, it won't care.
77 However, some functions that operate on lists demand true lists and
78 signal errors if given a dotted list. Most functions that try to find
79 the end of a list enter infinite loops if given a circular list.
81 @cindex list structure
82 Because most cons cells are used as part of lists, we refer to any
83 structure made out of cons cells as a @dfn{list structure}.
85 @node List-related Predicates
86 @section Predicates on Lists
87 @cindex predicates for lists
88 @cindex list predicates
90 The following predicates test whether a Lisp object is an atom,
91 whether it is a cons cell or is a list, or whether it is the
92 distinguished object @code{nil}. (Many of these predicates can be
93 defined in terms of the others, but they are used so often that it is
97 This function returns @code{t} if @var{object} is a cons cell, @code{nil}
98 otherwise. @code{nil} is not a cons cell, although it @emph{is} a list.
102 This function returns @code{t} if @var{object} is an atom, @code{nil}
103 otherwise. All objects except cons cells are atoms. The symbol
104 @code{nil} is an atom and is also a list; it is the only Lisp object
108 (atom @var{object}) @equiv{} (not (consp @var{object}))
113 This function returns @code{t} if @var{object} is a cons cell or
114 @code{nil}. Otherwise, it returns @code{nil}.
129 This function is the opposite of @code{listp}: it returns @code{t} if
130 @var{object} is not a list. Otherwise, it returns @code{nil}.
133 (listp @var{object}) @equiv{} (not (nlistp @var{object}))
138 This function returns @code{t} if @var{object} is @code{nil}, and
139 returns @code{nil} otherwise. This function is identical to @code{not},
140 but as a matter of clarity we use @code{null} when @var{object} is
141 considered a list and @code{not} when it is considered a truth value
142 (see @code{not} in @ref{Combining Conditions}).
158 @section Accessing Elements of Lists
159 @cindex list elements
162 This function returns the value referred to by the first slot of the
163 cons cell @var{cons-cell}. In other words, it returns the @sc{car} of
166 As a special case, if @var{cons-cell} is @code{nil}, this function
167 returns @code{nil}. Therefore, any list is a valid argument. An
168 error is signaled if the argument is not a cons cell or @code{nil}.
183 This function returns the value referred to by the second slot of the
184 cons cell @var{cons-cell}. In other words, it returns the @sc{cdr} of
187 As a special case, if @var{cons-cell} is @code{nil}, this function
188 returns @code{nil}; therefore, any list is a valid argument. An error
189 is signaled if the argument is not a cons cell or @code{nil}.
203 @defun car-safe object
204 This function lets you take the @sc{car} of a cons cell while avoiding
205 errors for other data types. It returns the @sc{car} of @var{object} if
206 @var{object} is a cons cell, @code{nil} otherwise. This is in contrast
207 to @code{car}, which signals an error if @var{object} is not a list.
211 (car-safe @var{object})
213 (let ((x @var{object}))
221 @defun cdr-safe object
222 This function lets you take the @sc{cdr} of a cons cell while
223 avoiding errors for other data types. It returns the @sc{cdr} of
224 @var{object} if @var{object} is a cons cell, @code{nil} otherwise.
225 This is in contrast to @code{cdr}, which signals an error if
226 @var{object} is not a list.
230 (cdr-safe @var{object})
232 (let ((x @var{object}))
241 This macro provides a convenient way to examine the @sc{car} of a
242 list, and take it off the list, all at once. It operates on the list
243 stored in @var{listname}. It removes the first element from the list,
244 saves the @sc{cdr} into @var{listname}, then returns the removed
247 In the simplest case, @var{listname} is an unquoted symbol naming a
248 list; in that case, this macro is equivalent to @w{@code{(prog1
249 (car listname) (setq listname (cdr listname)))}}.
260 More generally, @var{listname} can be a generalized variable. In that
261 case, this macro saves into @var{listname} using @code{setf}.
262 @xref{Generalized Variables}.
264 For the @code{push} macro, which adds an element to a list,
265 @xref{List Variables}.
269 @anchor{Definition of nth}
270 This function returns the @var{n}th element of @var{list}. Elements
271 are numbered starting with zero, so the @sc{car} of @var{list} is
272 element number zero. If the length of @var{list} is @var{n} or less,
273 the value is @code{nil}.
275 @c Behavior for -ve n undefined since 2013/08; see bug#15059.
277 If @var{n} is negative, @code{nth} returns the first element of @var{list}.
289 (nth n x) @equiv{} (car (nthcdr n x))
293 The function @code{elt} is similar, but applies to any kind of sequence.
294 For historical reasons, it takes its arguments in the opposite order.
295 @xref{Sequence Functions}.
299 This function returns the @var{n}th @sc{cdr} of @var{list}. In other
300 words, it skips past the first @var{n} links of @var{list} and returns
303 @c "or negative" removed 2013/08; see bug#15059.
304 If @var{n} is zero, @code{nthcdr} returns all of
305 @var{list}. If the length of @var{list} is @var{n} or less,
306 @code{nthcdr} returns @code{nil}.
310 (nthcdr 1 '(1 2 3 4))
314 (nthcdr 10 '(1 2 3 4))
318 (nthcdr 0 '(1 2 3 4))
324 @defun last list &optional n
325 This function returns the last link of @var{list}. The @code{car} of
326 this link is the list's last element. If @var{list} is null,
327 @code{nil} is returned. If @var{n} is non-@code{nil}, the
328 @var{n}th-to-last link is returned instead, or the whole of @var{list}
329 if @var{n} is bigger than @var{list}'s length.
332 @defun safe-length list
333 @anchor{Definition of safe-length}
334 This function returns the length of @var{list}, with no risk of either
335 an error or an infinite loop. It generally returns the number of
336 distinct cons cells in the list. However, for circular lists,
337 the value is just an upper bound; it is often too large.
339 If @var{list} is not @code{nil} or a cons cell, @code{safe-length}
343 The most common way to compute the length of a list, when you are not
344 worried that it may be circular, is with @code{length}. @xref{Sequence
347 @defun caar cons-cell
348 This is the same as @code{(car (car @var{cons-cell}))}.
351 @defun cadr cons-cell
352 This is the same as @code{(car (cdr @var{cons-cell}))}
353 or @code{(nth 1 @var{cons-cell})}.
356 @defun cdar cons-cell
357 This is the same as @code{(cdr (car @var{cons-cell}))}.
360 @defun cddr cons-cell
361 This is the same as @code{(cdr (cdr @var{cons-cell}))}
362 or @code{(nthcdr 2 @var{cons-cell})}.
389 In addition to the above, 24 additional compositions of @code{car} and
390 @code{cdr} are defined as @code{c@var{xxx}r} and @code{c@var{xxxx}r},
391 where each @code{@var{x}} is either @code{a} or @code{d}. @code{cadr},
392 @code{caddr}, and @code{cadddr} pick out the second, third or fourth
393 elements of a list, respectively. @file{cl-lib} provides the same
394 under the names @code{cl-second}, @code{cl-third}, and
395 @code{cl-fourth}. @xref{List Functions,,, cl, Common Lisp
398 @defun butlast x &optional n
399 This function returns the list @var{x} with the last element,
400 or the last @var{n} elements, removed. If @var{n} is greater
401 than zero it makes a copy of the list so as not to damage the
402 original list. In general, @code{(append (butlast @var{x} @var{n})
403 (last @var{x} @var{n}))} will return a list equal to @var{x}.
406 @defun nbutlast x &optional n
407 This is a version of @code{butlast} that works by destructively
408 modifying the @code{cdr} of the appropriate element, rather than
409 making a copy of the list.
413 @section Building Cons Cells and Lists
415 @cindex building lists
417 Many functions build lists, as lists reside at the very heart of Lisp.
418 @code{cons} is the fundamental list-building function; however, it is
419 interesting to note that @code{list} is used more times in the source
420 code for Emacs than @code{cons}.
422 @defun cons object1 object2
423 This function is the most basic function for building new list
424 structure. It creates a new cons cell, making @var{object1} the
425 @sc{car}, and @var{object2} the @sc{cdr}. It then returns the new
426 cons cell. The arguments @var{object1} and @var{object2} may be any
427 Lisp objects, but most often @var{object2} is a list.
445 @code{cons} is often used to add a single element to the front of a
446 list. This is called @dfn{consing the element onto the list}.
447 @footnote{There is no strictly equivalent way to add an element to
448 the end of a list. You can use @code{(append @var{listname} (list
449 @var{newelt}))}, which creates a whole new list by copying @var{listname}
450 and adding @var{newelt} to its end. Or you can use @code{(nconc
451 @var{listname} (list @var{newelt}))}, which modifies @var{listname}
452 by following all the @sc{cdr}s and then replacing the terminating
453 @code{nil}. Compare this to adding an element to the beginning of a
454 list with @code{cons}, which neither copies nor modifies the list.}
458 (setq list (cons newelt list))
461 Note that there is no conflict between the variable named @code{list}
462 used in this example and the function named @code{list} described below;
463 any symbol can serve both purposes.
466 @defun list &rest objects
467 This function creates a list with @var{objects} as its elements. The
468 resulting list is always @code{nil}-terminated. If no @var{objects}
469 are given, the empty list is returned.
474 @result{} (1 2 3 4 5)
477 (list 1 2 '(3 4 5) 'foo)
478 @result{} (1 2 (3 4 5) foo)
487 @defun make-list length object
488 This function creates a list of @var{length} elements, in which each
489 element is @var{object}. Compare @code{make-list} with
490 @code{make-string} (@pxref{Creating Strings}).
495 @result{} (pigs pigs pigs)
502 (setq l (make-list 3 '(a b)))
503 @result{} ((a b) (a b) (a b))
504 (eq (car l) (cadr l))
510 @defun append &rest sequences
511 @cindex copying lists
512 This function returns a list containing all the elements of
513 @var{sequences}. The @var{sequences} may be lists, vectors,
514 bool-vectors, or strings, but the last one should usually be a list.
515 All arguments except the last one are copied, so none of the arguments
516 is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join
517 lists with no copying.)
519 More generally, the final argument to @code{append} may be any Lisp
520 object. The final argument is not copied or converted; it becomes the
521 @sc{cdr} of the last cons cell in the new list. If the final argument
522 is itself a list, then its elements become in effect elements of the
523 result list. If the final element is not a list, the result is a
524 dotted list since its final @sc{cdr} is not @code{nil} as required
528 Here is an example of using @code{append}:
532 (setq trees '(pine oak))
534 (setq more-trees (append '(maple birch) trees))
535 @result{} (maple birch pine oak)
542 @result{} (maple birch pine oak)
545 (eq trees (cdr (cdr more-trees)))
550 You can see how @code{append} works by looking at a box diagram. The
551 variable @code{trees} is set to the list @code{(pine oak)} and then the
552 variable @code{more-trees} is set to the list @code{(maple birch pine
553 oak)}. However, the variable @code{trees} continues to refer to the
560 | --- --- --- --- -> --- --- --- ---
561 --> | | |--> | | |--> | | |--> | | |--> nil
562 --- --- --- --- --- --- --- ---
565 --> maple -->birch --> pine --> oak
569 An empty sequence contributes nothing to the value returned by
570 @code{append}. As a consequence of this, a final @code{nil} argument
571 forces a copy of the previous argument:
579 (setq wood (append trees nil))
593 This once was the usual way to copy a list, before the function
594 @code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}.
596 Here we show the use of vectors and strings as arguments to @code{append}:
600 (append [a b] "cd" nil)
601 @result{} (a b 99 100)
605 With the help of @code{apply} (@pxref{Calling Functions}), we can append
606 all the lists in a list of lists:
610 (apply 'append '((a b c) nil (x y z) nil))
611 @result{} (a b c x y z)
615 If no @var{sequences} are given, @code{nil} is returned:
624 Here are some examples where the final argument is not a list:
630 @result{} (x y . [z])
634 The second example shows that when the final argument is a sequence but
635 not a list, the sequence's elements do not become elements of the
636 resulting list. Instead, the sequence becomes the final @sc{cdr}, like
637 any other non-list final argument.
639 @defun copy-tree tree &optional vecp
640 This function returns a copy of the tree @code{tree}. If @var{tree} is a
641 cons cell, this makes a new cons cell with the same @sc{car} and
642 @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
645 Normally, when @var{tree} is anything other than a cons cell,
646 @code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is
647 non-@code{nil}, it copies vectors too (and operates recursively on
651 @defun number-sequence from &optional to separation
652 This returns a list of numbers starting with @var{from} and
653 incrementing by @var{separation}, and ending at or just before
654 @var{to}. @var{separation} can be positive or negative and defaults
655 to 1. If @var{to} is @code{nil} or numerically equal to @var{from},
656 the value is the one-element list @code{(@var{from})}. If @var{to} is
657 less than @var{from} with a positive @var{separation}, or greater than
658 @var{from} with a negative @var{separation}, the value is @code{nil}
659 because those arguments specify an empty sequence.
661 If @var{separation} is 0 and @var{to} is neither @code{nil} nor
662 numerically equal to @var{from}, @code{number-sequence} signals an
663 error, since those arguments specify an infinite sequence.
665 All arguments are numbers.
666 Floating-point arguments can be tricky, because floating-point
667 arithmetic is inexact. For instance, depending on the machine, it may
668 quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
669 the one element list @code{(0.4)}, whereas
670 @code{(number-sequence 0.4 0.8 0.2)} returns a list with three
671 elements. The @var{n}th element of the list is computed by the exact
672 formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if
673 one wants to make sure that @var{to} is included in the list, one can
674 pass an expression of this exact type for @var{to}. Alternatively,
675 one can replace @var{to} with a slightly larger value (or a slightly
676 more negative value if @var{separation} is negative).
681 (number-sequence 4 9)
682 @result{} (4 5 6 7 8 9)
683 (number-sequence 9 4 -1)
684 @result{} (9 8 7 6 5 4)
685 (number-sequence 9 4 -2)
689 (number-sequence 8 5)
691 (number-sequence 5 8 -1)
693 (number-sequence 1.5 6 2)
694 @result{} (1.5 3.5 5.5)
699 @section Modifying List Variables
700 @cindex modify a list
701 @cindex list modification
703 These functions, and one macro, provide convenient ways
704 to modify a list which is stored in a variable.
706 @defmac push element listname
707 This macro creates a new list whose @sc{car} is @var{element} and
708 whose @sc{cdr} is the list specified by @var{listname}, and saves that
709 list in @var{listname}. In the simplest case, @var{listname} is an
710 unquoted symbol naming a list, and this macro is equivalent
711 to @w{@code{(setq @var{listname} (cons @var{element} @var{listname}))}}.
722 More generally, @code{listname} can be a generalized variable. In
723 that case, this macro does the equivalent of @w{@code{(setf
724 @var{listname} (cons @var{element} @var{listname}))}}.
725 @xref{Generalized Variables}.
727 For the @code{pop} macro, which removes the first element from a list,
728 @xref{List Elements}.
731 Two functions modify lists that are the values of variables.
733 @defun add-to-list symbol element &optional append compare-fn
734 This function sets the variable @var{symbol} by consing @var{element}
735 onto the old value, if @var{element} is not already a member of that
736 value. It returns the resulting list, whether updated or not. The
737 value of @var{symbol} had better be a list already before the call.
738 @code{add-to-list} uses @var{compare-fn} to compare @var{element}
739 against existing list members; if @var{compare-fn} is @code{nil}, it
742 Normally, if @var{element} is added, it is added to the front of
743 @var{symbol}, but if the optional argument @var{append} is
744 non-@code{nil}, it is added at the end.
746 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
747 is an ordinary function, like @code{set} and unlike @code{setq}. Quote
748 the argument yourself if that is what you want.
751 Here's a scenario showing how to use @code{add-to-list}:
757 (add-to-list 'foo 'c) ;; @r{Add @code{c}.}
760 (add-to-list 'foo 'b) ;; @r{No effect.}
763 foo ;; @r{@code{foo} was changed.}
767 An equivalent expression for @code{(add-to-list '@var{var}
768 @var{value})} is this:
771 (or (member @var{value} @var{var})
772 (setq @var{var} (cons @var{value} @var{var})))
775 @defun add-to-ordered-list symbol element &optional order
776 This function sets the variable @var{symbol} by inserting
777 @var{element} into the old value, which must be a list, at the
778 position specified by @var{order}. If @var{element} is already a
779 member of the list, its position in the list is adjusted according
780 to @var{order}. Membership is tested using @code{eq}.
781 This function returns the resulting list, whether updated or not.
783 The @var{order} is typically a number (integer or float), and the
784 elements of the list are sorted in non-decreasing numerical order.
786 @var{order} may also be omitted or @code{nil}. Then the numeric order
787 of @var{element} stays unchanged if it already has one; otherwise,
788 @var{element} has no numeric order. Elements without a numeric list
789 order are placed at the end of the list, in no particular order.
791 Any other value for @var{order} removes the numeric order of @var{element}
792 if it already has one; otherwise, it is equivalent to @code{nil}.
794 The argument @var{symbol} is not implicitly quoted;
795 @code{add-to-ordered-list} is an ordinary function, like @code{set}
796 and unlike @code{setq}. Quote the argument yourself if necessary.
798 The ordering information is stored in a hash table on @var{symbol}'s
799 @code{list-order} property.
802 Here's a scenario showing how to use @code{add-to-ordered-list}:
808 (add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.}
811 (add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.}
814 (add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.}
817 (add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.}
820 (add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.}
823 (add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}.
824 @result{} (a c b e d)
826 foo ;; @r{@code{foo} was changed.}
827 @result{} (a c b e d)
830 @node Modifying Lists
831 @section Modifying Existing List Structure
832 @cindex destructive list operations
834 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
835 primitives @code{setcar} and @code{setcdr}. These are destructive
836 operations because they change existing list structure.
838 @cindex CL note---@code{rplaca} vs @code{setcar}
842 @b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and
843 @code{rplacd} to alter list structure; they change structure the same
844 way as @code{setcar} and @code{setcdr}, but the Common Lisp functions
845 return the cons cell while @code{setcar} and @code{setcdr} return the
846 new @sc{car} or @sc{cdr}.
850 * Setcar:: Replacing an element in a list.
851 * Setcdr:: Replacing part of the list backbone.
852 This can be used to remove or add elements.
853 * Rearrangement:: Reordering the elements in a list; combining lists.
857 @subsection Altering List Elements with @code{setcar}
858 @cindex replace list element
859 @cindex list, replace element
861 Changing the @sc{car} of a cons cell is done with @code{setcar}. When
862 used on a list, @code{setcar} replaces one element of a list with a
865 @defun setcar cons object
866 This function stores @var{object} as the new @sc{car} of @var{cons},
867 replacing its previous @sc{car}. In other words, it changes the
868 @sc{car} slot of @var{cons} to refer to @var{object}. It returns the
869 value @var{object}. For example:
887 When a cons cell is part of the shared structure of several lists,
888 storing a new @sc{car} into the cons changes one element of each of
889 these lists. Here is an example:
893 ;; @r{Create two lists that are partly shared.}
896 (setq x2 (cons 'z (cdr x1)))
901 ;; @r{Replace the @sc{car} of a shared link.}
902 (setcar (cdr x1) 'foo)
904 x1 ; @r{Both lists are changed.}
911 ;; @r{Replace the @sc{car} of a link that is not shared.}
914 x1 ; @r{Only one list is changed.}
915 @result{} (baz foo c)
921 Here is a graphical depiction of the shared structure of the two lists
922 in the variables @code{x1} and @code{x2}, showing why replacing @code{b}
927 --- --- --- --- --- ---
928 x1---> | | |----> | | |--> | | |--> nil
929 --- --- --- --- --- ---
943 Here is an alternative form of box diagram, showing the same relationship:
948 -------------- -------------- --------------
949 | car | cdr | | car | cdr | | car | cdr |
950 | a | o------->| b | o------->| c | nil |
952 -------------- | -------------- --------------
964 @subsection Altering the CDR of a List
965 @cindex replace part of list
967 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
969 @defun setcdr cons object
970 This function stores @var{object} as the new @sc{cdr} of @var{cons},
971 replacing its previous @sc{cdr}. In other words, it changes the
972 @sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the
976 Here is an example of replacing the @sc{cdr} of a list with a
977 different list. All but the first element of the list are removed in
978 favor of a different sequence of elements. The first element is
979 unchanged, because it resides in the @sc{car} of the list, and is not
980 reached via the @sc{cdr}.
997 You can delete elements from the middle of a list by altering the
998 @sc{cdr}s of the cons cells in the list. For example, here we delete
999 the second element, @code{b}, from the list @code{(a b c)}, by changing
1000 the @sc{cdr} of the first cons cell:
1006 (setcdr x1 (cdr (cdr x1)))
1013 Here is the result in box notation:
1017 --------------------
1019 -------------- | -------------- | --------------
1020 | car | cdr | | | car | cdr | -->| car | cdr |
1021 | a | o----- | b | o-------->| c | nil |
1023 -------------- -------------- --------------
1028 The second cons cell, which previously held the element @code{b}, still
1029 exists and its @sc{car} is still @code{b}, but it no longer forms part
1032 It is equally easy to insert a new element by changing @sc{cdr}s:
1038 (setcdr x1 (cons 'd (cdr x1)))
1045 Here is this result in box notation:
1049 -------------- ------------- -------------
1050 | car | cdr | | car | cdr | | car | cdr |
1051 | a | o | -->| b | o------->| c | nil |
1052 | | | | | | | | | | |
1053 --------- | -- | ------------- -------------
1066 @subsection Functions that Rearrange Lists
1067 @cindex rearrangement of lists
1068 @cindex reordering, of elements in lists
1069 @cindex modification of lists
1071 Here are some functions that rearrange lists destructively by
1072 modifying the @sc{cdr}s of their component cons cells. These functions
1073 are destructive because they chew up the original lists passed
1074 to them as arguments, relinking their cons cells to form a new list that
1075 is the returned value.
1078 See @code{delq}, in @ref{Sets And Lists}, for another function
1079 that modifies cons cells.
1082 The function @code{delq} in the following section is another example
1083 of destructive list manipulation.
1086 @defun nconc &rest lists
1087 @cindex concatenating lists
1088 @cindex joining lists
1089 This function returns a list containing all the elements of @var{lists}.
1090 Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
1091 @emph{not} copied. Instead, the last @sc{cdr} of each of the
1092 @var{lists} is changed to refer to the following list. The last of the
1093 @var{lists} is not altered. For example:
1102 @result{} (1 2 3 4 5)
1106 @result{} (1 2 3 4 5)
1110 Since the last argument of @code{nconc} is not itself modified, it is
1111 reasonable to use a constant list, such as @code{'(4 5)}, as in the
1112 above example. For the same reason, the last argument need not be a
1122 @result{} (1 2 3 . z)
1126 @result{} (1 2 3 . z)
1130 However, the other arguments (all but the last) must be lists.
1132 A common pitfall is to use a quoted constant list as a non-last
1133 argument to @code{nconc}. If you do this, your program will change
1134 each time you run it! Here is what happens:
1138 (defun add-foo (x) ; @r{We want this function to add}
1139 (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.}
1143 (symbol-function 'add-foo)
1144 @result{} (lambda (x) (nconc (quote (foo)) x))
1148 (setq xx (add-foo '(1 2))) ; @r{It seems to work.}
1152 (setq xy (add-foo '(3 4))) ; @r{What happened?}
1153 @result{} (foo 1 2 3 4)
1161 (symbol-function 'add-foo)
1162 @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
1167 @node Sets And Lists
1168 @section Using Lists as Sets
1169 @cindex lists as sets
1172 A list can represent an unordered mathematical set---simply consider a
1173 value an element of a set if it appears in the list, and ignore the
1174 order of the list. To form the union of two sets, use @code{append} (as
1175 long as you don't mind having duplicate elements). You can remove
1176 @code{equal} duplicates using @code{delete-dups}. Other useful
1177 functions for sets include @code{memq} and @code{delq}, and their
1178 @code{equal} versions, @code{member} and @code{delete}.
1180 @cindex CL note---lack @code{union}, @code{intersection}
1182 @b{Common Lisp note:} Common Lisp has functions @code{union} (which
1183 avoids duplicate elements) and @code{intersection} for set operations.
1184 Although standard GNU Emacs Lisp does not have them, the @file{cl-lib}
1185 library provides versions.
1186 @xref{Lists as Sets,,, cl, Common Lisp Extensions}.
1189 @defun memq object list
1190 @cindex membership in a list
1191 This function tests to see whether @var{object} is a member of
1192 @var{list}. If it is, @code{memq} returns a list starting with the
1193 first occurrence of @var{object}. Otherwise, it returns @code{nil}.
1194 The letter @samp{q} in @code{memq} says that it uses @code{eq} to
1195 compare @var{object} against the elements of the list. For example:
1199 (memq 'b '(a b c b a))
1203 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
1209 @defun delq object list
1210 @cindex deleting list elements
1211 This function destructively removes all elements @code{eq} to
1212 @var{object} from @var{list}, and returns the resulting list. The
1213 letter @samp{q} in @code{delq} says that it uses @code{eq} to compare
1214 @var{object} against the elements of the list, like @code{memq} and
1217 Typically, when you invoke @code{delq}, you should use the return
1218 value by assigning it to the variable which held the original list.
1219 The reason for this is explained below.
1222 The @code{delq} function deletes elements from the front of the list
1223 by simply advancing down the list, and returning a sublist that starts
1224 after those elements. For example:
1228 (delq 'a '(a b c)) @equiv{} (cdr '(a b c))
1233 When an element to be deleted appears in the middle of the list,
1234 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
1238 (setq sample-list '(a b c (4)))
1239 @result{} (a b c (4))
1242 (delq 'a sample-list)
1247 @result{} (a b c (4))
1250 (delq 'c sample-list)
1259 Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to
1260 splice out the third element, but @code{(delq 'a sample-list)} does not
1261 splice anything---it just returns a shorter list. Don't assume that a
1262 variable which formerly held the argument @var{list} now has fewer
1263 elements, or that it still holds the original list! Instead, save the
1264 result of @code{delq} and use that. Most often we store the result back
1265 into the variable that held the original list:
1268 (setq flowers (delq 'rose flowers))
1271 In the following example, the @code{(4)} that @code{delq} attempts to match
1272 and the @code{(4)} in the @code{sample-list} are not @code{eq}:
1276 (delq '(4) sample-list)
1281 If you want to delete elements that are @code{equal} to a given value,
1282 use @code{delete} (see below).
1284 @defun remq object list
1285 This function returns a copy of @var{list}, with all elements removed
1286 which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq}
1287 says that it uses @code{eq} to compare @var{object} against the elements
1292 (setq sample-list '(a b c a b c))
1293 @result{} (a b c a b c)
1296 (remq 'a sample-list)
1301 @result{} (a b c a b c)
1306 @defun memql object list
1307 The function @code{memql} tests to see whether @var{object} is a member
1308 of @var{list}, comparing members with @var{object} using @code{eql},
1309 so floating-point elements are compared by value.
1310 If @var{object} is a member, @code{memql} returns a list starting with
1311 its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
1313 Compare this with @code{memq}:
1317 (memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
1321 (memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
1327 The following three functions are like @code{memq}, @code{delq} and
1328 @code{remq}, but use @code{equal} rather than @code{eq} to compare
1329 elements. @xref{Equality Predicates}.
1331 @defun member object list
1332 The function @code{member} tests to see whether @var{object} is a member
1333 of @var{list}, comparing members with @var{object} using @code{equal}.
1334 If @var{object} is a member, @code{member} returns a list starting with
1335 its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
1337 Compare this with @code{memq}:
1341 (member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
1345 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
1349 ;; @r{Two strings with the same contents are @code{equal}.}
1350 (member "foo" '("foo" "bar"))
1351 @result{} ("foo" "bar")
1356 @defun delete object sequence
1357 This function removes all elements @code{equal} to @var{object} from
1358 @var{sequence}, and returns the resulting sequence.
1360 If @var{sequence} is a list, @code{delete} is to @code{delq} as
1361 @code{member} is to @code{memq}: it uses @code{equal} to compare
1362 elements with @var{object}, like @code{member}; when it finds an
1363 element that matches, it cuts the element out just as @code{delq}
1364 would. As with @code{delq}, you should typically use the return value
1365 by assigning it to the variable which held the original list.
1367 If @code{sequence} is a vector or string, @code{delete} returns a copy
1368 of @code{sequence} with all elements @code{equal} to @code{object}
1375 (setq l '((2) (1) (2)))
1380 ;; @r{If you want to change @code{l} reliably,}
1381 ;; @r{write @code{(setq l (delete '(2) l))}.}
1384 (setq l '((2) (1) (2)))
1389 ;; @r{In this case, it makes no difference whether you set @code{l},}
1390 ;; @r{but you should do so for the sake of the other case.}
1393 (delete '(2) [(2) (1) (2)])
1399 @defun remove object sequence
1400 This function is the non-destructive counterpart of @code{delete}. It
1401 returns a copy of @code{sequence}, a list, vector, or string, with
1402 elements @code{equal} to @code{object} removed. For example:
1406 (remove '(2) '((2) (1) (2)))
1410 (remove '(2) [(2) (1) (2)])
1417 @b{Common Lisp note:} The functions @code{member}, @code{delete} and
1418 @code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
1419 Lisp. The Common Lisp versions do not use @code{equal} to compare
1423 @defun member-ignore-case object list
1424 This function is like @code{member}, except that @var{object} should
1425 be a string and that it ignores differences in letter-case and text
1426 representation: upper-case and lower-case letters are treated as
1427 equal, and unibyte strings are converted to multibyte prior to
1431 @defun delete-dups list
1432 This function destructively removes all @code{equal} duplicates from
1433 @var{list}, stores the result in @var{list} and returns it. Of
1434 several @code{equal} occurrences of an element in @var{list},
1435 @code{delete-dups} keeps the first one.
1438 See also the function @code{add-to-list}, in @ref{List Variables},
1439 for a way to add an element to a list stored in a variable and used as a
1442 @node Association Lists
1443 @section Association Lists
1444 @cindex association list
1447 An @dfn{association list}, or @dfn{alist} for short, records a mapping
1448 from keys to values. It is a list of cons cells called
1449 @dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
1450 @sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key''
1451 is not related to the term ``key sequence''; it means a value used to
1452 look up an item in a table. In this case, the table is the alist, and
1453 the alist associations are the items.}
1455 Here is an example of an alist. The key @code{pine} is associated with
1456 the value @code{cones}; the key @code{oak} is associated with
1457 @code{acorns}; and the key @code{maple} is associated with @code{seeds}.
1467 Both the values and the keys in an alist may be any Lisp objects.
1468 For example, in the following alist, the symbol @code{a} is
1469 associated with the number @code{1}, and the string @code{"b"} is
1470 associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of
1477 Sometimes it is better to design an alist to store the associated
1478 value in the @sc{car} of the @sc{cdr} of the element. Here is an
1479 example of such an alist:
1482 ((rose red) (lily white) (buttercup yellow))
1486 Here we regard @code{red} as the value associated with @code{rose}. One
1487 advantage of this kind of alist is that you can store other related
1488 information---even a list of other items---in the @sc{cdr} of the
1489 @sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see
1490 below) to find the element containing a given value. When neither of
1491 these considerations is important, the choice is a matter of taste, as
1492 long as you are consistent about it for any given alist.
1494 The same alist shown above could be regarded as having the
1495 associated value in the @sc{cdr} of the element; the value associated
1496 with @code{rose} would be the list @code{(red)}.
1498 Association lists are often used to record information that you might
1499 otherwise keep on a stack, since new associations may be added easily to
1500 the front of the list. When searching an association list for an
1501 association with a given key, the first one found is returned, if there
1504 In Emacs Lisp, it is @emph{not} an error if an element of an
1505 association list is not a cons cell. The alist search functions simply
1506 ignore such elements. Many other versions of Lisp signal errors in such
1509 Note that property lists are similar to association lists in several
1510 respects. A property list behaves like an association list in which
1511 each key can occur only once. @xref{Property Lists}, for a comparison
1512 of property lists and association lists.
1514 @defun assoc key alist &optional testfn
1515 This function returns the first association for @var{key} in
1516 @var{alist}, comparing @var{key} against the alist elements using
1517 @var{testfn} if non-nil, or @code{equal} if nil (@pxref{Equality
1518 Predicates}). It returns @code{nil} if no association in @var{alist}
1519 has a @sc{car} equal to @var{key}. For example:
1522 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
1523 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
1525 @result{} (oak . acorns)
1526 (cdr (assoc 'oak trees))
1528 (assoc 'birch trees)
1532 Here is another example, in which the keys and values are not symbols:
1535 (setq needles-per-cluster
1536 '((2 "Austrian Pine" "Red Pine")
1540 (cdr (assoc 3 needles-per-cluster))
1541 @result{} ("Pitch Pine")
1542 (cdr (assoc 2 needles-per-cluster))
1543 @result{} ("Austrian Pine" "Red Pine")
1547 The function @code{assoc-string} is much like @code{assoc} except
1548 that it ignores certain differences between strings. @xref{Text
1551 @defun rassoc value alist
1552 This function returns the first association with value @var{value} in
1553 @var{alist}. It returns @code{nil} if no association in @var{alist} has
1554 a @sc{cdr} @code{equal} to @var{value}.
1556 @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
1557 each @var{alist} association instead of the @sc{car}. You can think of
1558 this as reverse @code{assoc}, finding the key for a given value.
1561 @defun assq key alist
1562 This function is like @code{assoc} in that it returns the first
1563 association for @var{key} in @var{alist}, but it makes the comparison
1564 using @code{eq}. @code{assq} returns @code{nil} if no association in
1565 @var{alist} has a @sc{car} @code{eq} to @var{key}. This function is
1566 used more often than @code{assoc}, since @code{eq} is faster than
1567 @code{equal} and most alists use symbols as keys. @xref{Equality
1571 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
1572 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
1574 @result{} (pine . cones)
1577 On the other hand, @code{assq} is not usually useful in alists where the
1578 keys may not be symbols:
1582 '(("simple leaves" . oak)
1583 ("compound leaves" . horsechestnut)))
1585 (assq "simple leaves" leaves)
1587 (assoc "simple leaves" leaves)
1588 @result{} ("simple leaves" . oak)
1592 @defun alist-get key alist &optional default remove testfn
1593 This function is similar to @code{assq}. It finds the first
1594 association @w{@code{(@var{key} . @var{value})}} by comparing
1595 @var{key} with @var{alist} elements, and, if found, returns the
1596 @var{value} of that association. If no association is found, the
1597 function returns @var{default}. Comparison of @var{key} against
1598 @var{alist} elements uses the function specified by @var{testfn},
1599 defaulting to @code{eq}.
1601 This is a generalized variable (@pxref{Generalized Variables})
1602 that can be used to change a value with @code{setf}. When
1603 using it to set a value, optional argument @var{remove} non-@code{nil}
1604 means to remove @var{key}'s association from @var{alist} if the new
1605 value is @code{eql} to @var{default}.
1608 @defun rassq value alist
1609 This function returns the first association with value @var{value} in
1610 @var{alist}. It returns @code{nil} if no association in @var{alist} has
1611 a @sc{cdr} @code{eq} to @var{value}.
1613 @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
1614 each @var{alist} association instead of the @sc{car}. You can think of
1615 this as reverse @code{assq}, finding the key for a given value.
1620 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
1622 (rassq 'acorns trees)
1623 @result{} (oak . acorns)
1624 (rassq 'spores trees)
1628 @code{rassq} cannot search for a value stored in the @sc{car}
1629 of the @sc{cdr} of an element:
1632 (setq colors '((rose red) (lily white) (buttercup yellow)))
1634 (rassq 'white colors)
1638 In this case, the @sc{cdr} of the association @code{(lily white)} is not
1639 the symbol @code{white}, but rather the list @code{(white)}. This
1640 becomes clearer if the association is written in dotted pair notation:
1643 (lily white) @equiv{} (lily . (white))
1647 @defun assoc-default key alist &optional test default
1648 This function searches @var{alist} for a match for @var{key}. For each
1649 element of @var{alist}, it compares the element (if it is an atom) or
1650 the element's @sc{car} (if it is a cons) against @var{key}, by calling
1651 @var{test} with two arguments: the element or its @sc{car}, and
1652 @var{key}. The arguments are passed in that order so that you can get
1653 useful results using @code{string-match} with an alist that contains
1654 regular expressions (@pxref{Regexp Search}). If @var{test} is omitted
1655 or @code{nil}, @code{equal} is used for comparison.
1657 If an alist element matches @var{key} by this criterion,
1658 then @code{assoc-default} returns a value based on this element.
1659 If the element is a cons, then the value is the element's @sc{cdr}.
1660 Otherwise, the return value is @var{default}.
1662 If no alist element matches @var{key}, @code{assoc-default} returns
1666 @defun copy-alist alist
1667 @cindex copying alists
1668 This function returns a two-level deep copy of @var{alist}: it creates a
1669 new copy of each association, so that you can alter the associations of
1670 the new alist without changing the old one.
1674 (setq needles-per-cluster
1675 '((2 . ("Austrian Pine" "Red Pine"))
1676 (3 . ("Pitch Pine"))
1678 (5 . ("White Pine"))))
1680 ((2 "Austrian Pine" "Red Pine")
1684 (setq copy (copy-alist needles-per-cluster))
1686 ((2 "Austrian Pine" "Red Pine")
1690 (eq needles-per-cluster copy)
1692 (equal needles-per-cluster copy)
1694 (eq (car needles-per-cluster) (car copy))
1696 (cdr (car (cdr needles-per-cluster)))
1697 @result{} ("Pitch Pine")
1699 (eq (cdr (car (cdr needles-per-cluster)))
1700 (cdr (car (cdr copy))))
1705 This example shows how @code{copy-alist} makes it possible to change
1706 the associations of one copy without affecting the other:
1710 (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
1711 (cdr (assq 3 needles-per-cluster))
1712 @result{} ("Pitch Pine")
1717 @defun assq-delete-all key alist
1718 This function deletes from @var{alist} all the elements whose @sc{car}
1719 is @code{eq} to @var{key}, much as if you used @code{delq} to delete
1720 each such element one by one. It returns the shortened alist, and
1721 often modifies the original list structure of @var{alist}. For
1722 correct results, use the return value of @code{assq-delete-all} rather
1723 than looking at the saved value of @var{alist}.
1726 (setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
1727 @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
1728 (assq-delete-all 'foo alist)
1729 @result{} ((bar 2) (lose 4))
1731 @result{} ((foo 1) (bar 2) (lose 4))
1735 @defun rassq-delete-all value alist
1736 This function deletes from @var{alist} all the elements whose @sc{cdr}
1737 is @code{eq} to @var{value}. It returns the shortened alist, and
1738 often modifies the original list structure of @var{alist}.
1739 @code{rassq-delete-all} is like @code{assq-delete-all} except that it
1740 compares the @sc{cdr} of each @var{alist} association instead of the
1744 @node Property Lists
1745 @section Property Lists
1746 @cindex property list
1749 A @dfn{property list} (@dfn{plist} for short) is a list of paired
1750 elements. Each of the pairs associates a property name (usually a
1751 symbol) with a property or value. Here is an example of a property
1755 (pine cones numbers (1 2 3) color "blue")
1759 This property list associates @code{pine} with @code{cones},
1760 @code{numbers} with @code{(1 2 3)}, and @code{color} with
1761 @code{"blue"}. The property names and values can be any Lisp objects,
1762 but the names are usually symbols (as they are in this example).
1764 Property lists are used in several contexts. For instance, the
1765 function @code{put-text-property} takes an argument which is a
1766 property list, specifying text properties and associated values which
1767 are to be applied to text in a string or buffer. @xref{Text
1770 Another prominent use of property lists is for storing symbol
1771 properties. Every symbol possesses a list of properties, used to
1772 record miscellaneous information about the symbol; these properties
1773 are stored in the form of a property list. @xref{Symbol Properties}.
1776 * Plists and Alists:: Comparison of the advantages of property
1777 lists and association lists.
1778 * Plist Access:: Accessing property lists stored elsewhere.
1781 @node Plists and Alists
1782 @subsection Property Lists and Association Lists
1783 @cindex plist vs. alist
1784 @cindex alist vs. plist
1786 @cindex property lists vs association lists
1787 Association lists (@pxref{Association Lists}) are very similar to
1788 property lists. In contrast to association lists, the order of the
1789 pairs in the property list is not significant, since the property
1790 names must be distinct.
1792 Property lists are better than association lists for attaching
1793 information to various Lisp function names or variables. If your
1794 program keeps all such information in one association list, it will
1795 typically need to search that entire list each time it checks for an
1796 association for a particular Lisp function name or variable, which
1797 could be slow. By contrast, if you keep the same information in the
1798 property lists of the function names or variables themselves, each
1799 search will scan only the length of one property list, which is
1800 usually short. This is why the documentation for a variable is
1801 recorded in a property named @code{variable-documentation}. The byte
1802 compiler likewise uses properties to record those functions needing
1805 However, association lists have their own advantages. Depending on
1806 your application, it may be faster to add an association to the front of
1807 an association list than to update a property. All properties for a
1808 symbol are stored in the same property list, so there is a possibility
1809 of a conflict between different uses of a property name. (For this
1810 reason, it is a good idea to choose property names that are probably
1811 unique, such as by beginning the property name with the program's usual
1812 name-prefix for variables and functions.) An association list may be
1813 used like a stack where associations are pushed on the front of the list
1814 and later discarded; this is not possible with a property list.
1817 @subsection Property Lists Outside Symbols
1818 @cindex plist access
1819 @cindex accessing plist properties
1821 The following functions can be used to manipulate property lists.
1822 They all compare property names using @code{eq}.
1824 @defun plist-get plist property
1825 This returns the value of the @var{property} property stored in the
1826 property list @var{plist}. It accepts a malformed @var{plist}
1827 argument. If @var{property} is not found in the @var{plist}, it
1828 returns @code{nil}. For example,
1831 (plist-get '(foo 4) 'foo)
1833 (plist-get '(foo 4 bad) 'foo)
1835 (plist-get '(foo 4 bad) 'bad)
1837 (plist-get '(foo 4 bad) 'bar)
1842 @defun plist-put plist property value
1843 This stores @var{value} as the value of the @var{property} property in
1844 the property list @var{plist}. It may modify @var{plist} destructively,
1845 or it may construct a new list structure without altering the old. The
1846 function returns the modified property list, so you can store that back
1847 in the place where you got @var{plist}. For example,
1850 (setq my-plist '(bar t foo 4))
1851 @result{} (bar t foo 4)
1852 (setq my-plist (plist-put my-plist 'foo 69))
1853 @result{} (bar t foo 69)
1854 (setq my-plist (plist-put my-plist 'quux '(a)))
1855 @result{} (bar t foo 69 quux (a))
1859 @defun lax-plist-get plist property
1860 Like @code{plist-get} except that it compares properties
1861 using @code{equal} instead of @code{eq}.
1864 @defun lax-plist-put plist property value
1865 Like @code{plist-put} except that it compares properties
1866 using @code{equal} instead of @code{eq}.
1869 @defun plist-member plist property
1870 This returns non-@code{nil} if @var{plist} contains the given
1871 @var{property}. Unlike @code{plist-get}, this allows you to distinguish
1872 between a missing property and a property with the value @code{nil}.
1873 The value is actually the tail of @var{plist} whose @code{car} is