2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2015 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})}.
365 @defun butlast x &optional n
366 This function returns the list @var{x} with the last element,
367 or the last @var{n} elements, removed. If @var{n} is greater
368 than zero it makes a copy of the list so as not to damage the
369 original list. In general, @code{(append (butlast @var{x} @var{n})
370 (last @var{x} @var{n}))} will return a list equal to @var{x}.
373 @defun nbutlast x &optional n
374 This is a version of @code{butlast} that works by destructively
375 modifying the @code{cdr} of the appropriate element, rather than
376 making a copy of the list.
380 @section Building Cons Cells and Lists
382 @cindex building lists
384 Many functions build lists, as lists reside at the very heart of Lisp.
385 @code{cons} is the fundamental list-building function; however, it is
386 interesting to note that @code{list} is used more times in the source
387 code for Emacs than @code{cons}.
389 @defun cons object1 object2
390 This function is the most basic function for building new list
391 structure. It creates a new cons cell, making @var{object1} the
392 @sc{car}, and @var{object2} the @sc{cdr}. It then returns the new
393 cons cell. The arguments @var{object1} and @var{object2} may be any
394 Lisp objects, but most often @var{object2} is a list.
412 @code{cons} is often used to add a single element to the front of a
413 list. This is called @dfn{consing the element onto the list}.
414 @footnote{There is no strictly equivalent way to add an element to
415 the end of a list. You can use @code{(append @var{listname} (list
416 @var{newelt}))}, which creates a whole new list by copying @var{listname}
417 and adding @var{newelt} to its end. Or you can use @code{(nconc
418 @var{listname} (list @var{newelt}))}, which modifies @var{listname}
419 by following all the @sc{cdr}s and then replacing the terminating
420 @code{nil}. Compare this to adding an element to the beginning of a
421 list with @code{cons}, which neither copies nor modifies the list.}
425 (setq list (cons newelt list))
428 Note that there is no conflict between the variable named @code{list}
429 used in this example and the function named @code{list} described below;
430 any symbol can serve both purposes.
433 @defun list &rest objects
434 This function creates a list with @var{objects} as its elements. The
435 resulting list is always @code{nil}-terminated. If no @var{objects}
436 are given, the empty list is returned.
441 @result{} (1 2 3 4 5)
444 (list 1 2 '(3 4 5) 'foo)
445 @result{} (1 2 (3 4 5) foo)
454 @defun make-list length object
455 This function creates a list of @var{length} elements, in which each
456 element is @var{object}. Compare @code{make-list} with
457 @code{make-string} (@pxref{Creating Strings}).
462 @result{} (pigs pigs pigs)
469 (setq l (make-list 3 '(a b)))
470 @result{} ((a b) (a b) (a b))
471 (eq (car l) (cadr l))
477 @defun append &rest sequences
478 @cindex copying lists
479 This function returns a list containing all the elements of
480 @var{sequences}. The @var{sequences} may be lists, vectors,
481 bool-vectors, or strings, but the last one should usually be a list.
482 All arguments except the last one are copied, so none of the arguments
483 is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join
484 lists with no copying.)
486 More generally, the final argument to @code{append} may be any Lisp
487 object. The final argument is not copied or converted; it becomes the
488 @sc{cdr} of the last cons cell in the new list. If the final argument
489 is itself a list, then its elements become in effect elements of the
490 result list. If the final element is not a list, the result is a
491 dotted list since its final @sc{cdr} is not @code{nil} as required
495 Here is an example of using @code{append}:
499 (setq trees '(pine oak))
501 (setq more-trees (append '(maple birch) trees))
502 @result{} (maple birch pine oak)
509 @result{} (maple birch pine oak)
512 (eq trees (cdr (cdr more-trees)))
517 You can see how @code{append} works by looking at a box diagram. The
518 variable @code{trees} is set to the list @code{(pine oak)} and then the
519 variable @code{more-trees} is set to the list @code{(maple birch pine
520 oak)}. However, the variable @code{trees} continues to refer to the
527 | --- --- --- --- -> --- --- --- ---
528 --> | | |--> | | |--> | | |--> | | |--> nil
529 --- --- --- --- --- --- --- ---
532 --> maple -->birch --> pine --> oak
536 An empty sequence contributes nothing to the value returned by
537 @code{append}. As a consequence of this, a final @code{nil} argument
538 forces a copy of the previous argument:
546 (setq wood (append trees nil))
560 This once was the usual way to copy a list, before the function
561 @code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}.
563 Here we show the use of vectors and strings as arguments to @code{append}:
567 (append [a b] "cd" nil)
568 @result{} (a b 99 100)
572 With the help of @code{apply} (@pxref{Calling Functions}), we can append
573 all the lists in a list of lists:
577 (apply 'append '((a b c) nil (x y z) nil))
578 @result{} (a b c x y z)
582 If no @var{sequences} are given, @code{nil} is returned:
591 Here are some examples where the final argument is not a list:
597 @result{} (x y . [z])
601 The second example shows that when the final argument is a sequence but
602 not a list, the sequence's elements do not become elements of the
603 resulting list. Instead, the sequence becomes the final @sc{cdr}, like
604 any other non-list final argument.
607 This function creates a new list whose elements are the elements of
608 @var{list}, but in reverse order. The original argument @var{list} is
625 @defun copy-tree tree &optional vecp
626 This function returns a copy of the tree @code{tree}. If @var{tree} is a
627 cons cell, this makes a new cons cell with the same @sc{car} and
628 @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
631 Normally, when @var{tree} is anything other than a cons cell,
632 @code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is
633 non-@code{nil}, it copies vectors too (and operates recursively on
637 @defun number-sequence from &optional to separation
638 This returns a list of numbers starting with @var{from} and
639 incrementing by @var{separation}, and ending at or just before
640 @var{to}. @var{separation} can be positive or negative and defaults
641 to 1. If @var{to} is @code{nil} or numerically equal to @var{from},
642 the value is the one-element list @code{(@var{from})}. If @var{to} is
643 less than @var{from} with a positive @var{separation}, or greater than
644 @var{from} with a negative @var{separation}, the value is @code{nil}
645 because those arguments specify an empty sequence.
647 If @var{separation} is 0 and @var{to} is neither @code{nil} nor
648 numerically equal to @var{from}, @code{number-sequence} signals an
649 error, since those arguments specify an infinite sequence.
651 All arguments are numbers.
652 Floating-point arguments can be tricky, because floating-point
653 arithmetic is inexact. For instance, depending on the machine, it may
654 quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
655 the one element list @code{(0.4)}, whereas
656 @code{(number-sequence 0.4 0.8 0.2)} returns a list with three
657 elements. The @var{n}th element of the list is computed by the exact
658 formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if
659 one wants to make sure that @var{to} is included in the list, one can
660 pass an expression of this exact type for @var{to}. Alternatively,
661 one can replace @var{to} with a slightly larger value (or a slightly
662 more negative value if @var{separation} is negative).
667 (number-sequence 4 9)
668 @result{} (4 5 6 7 8 9)
669 (number-sequence 9 4 -1)
670 @result{} (9 8 7 6 5 4)
671 (number-sequence 9 4 -2)
675 (number-sequence 8 5)
677 (number-sequence 5 8 -1)
679 (number-sequence 1.5 6 2)
680 @result{} (1.5 3.5 5.5)
685 @section Modifying List Variables
686 @cindex modify a list
687 @cindex list modification
689 These functions, and one macro, provide convenient ways
690 to modify a list which is stored in a variable.
692 @defmac push element listname
693 This macro creates a new list whose @sc{car} is @var{element} and
694 whose @sc{cdr} is the list specified by @var{listname}, and saves that
695 list in @var{listname}. In the simplest case, @var{listname} is an
696 unquoted symbol naming a list, and this macro is equivalent
697 to @w{@code{(setq @var{listname} (cons @var{element} @var{listname}))}}.
708 More generally, @code{listname} can be a generalized variable. In
709 that case, this macro does the equivalent of @w{@code{(setf
710 @var{listname} (cons @var{element} @var{listname}))}}.
711 @xref{Generalized Variables}.
713 For the @code{pop} macro, which removes the first element from a list,
714 @xref{List Elements}.
717 Two functions modify lists that are the values of variables.
719 @defun add-to-list symbol element &optional append compare-fn
720 This function sets the variable @var{symbol} by consing @var{element}
721 onto the old value, if @var{element} is not already a member of that
722 value. It returns the resulting list, whether updated or not. The
723 value of @var{symbol} had better be a list already before the call.
724 @code{add-to-list} uses @var{compare-fn} to compare @var{element}
725 against existing list members; if @var{compare-fn} is @code{nil}, it
728 Normally, if @var{element} is added, it is added to the front of
729 @var{symbol}, but if the optional argument @var{append} is
730 non-@code{nil}, it is added at the end.
732 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
733 is an ordinary function, like @code{set} and unlike @code{setq}. Quote
734 the argument yourself if that is what you want.
737 Here's a scenario showing how to use @code{add-to-list}:
743 (add-to-list 'foo 'c) ;; @r{Add @code{c}.}
746 (add-to-list 'foo 'b) ;; @r{No effect.}
749 foo ;; @r{@code{foo} was changed.}
753 An equivalent expression for @code{(add-to-list '@var{var}
754 @var{value})} is this:
757 (or (member @var{value} @var{var})
758 (setq @var{var} (cons @var{value} @var{var})))
761 @defun add-to-ordered-list symbol element &optional order
762 This function sets the variable @var{symbol} by inserting
763 @var{element} into the old value, which must be a list, at the
764 position specified by @var{order}. If @var{element} is already a
765 member of the list, its position in the list is adjusted according
766 to @var{order}. Membership is tested using @code{eq}.
767 This function returns the resulting list, whether updated or not.
769 The @var{order} is typically a number (integer or float), and the
770 elements of the list are sorted in non-decreasing numerical order.
772 @var{order} may also be omitted or @code{nil}. Then the numeric order
773 of @var{element} stays unchanged if it already has one; otherwise,
774 @var{element} has no numeric order. Elements without a numeric list
775 order are placed at the end of the list, in no particular order.
777 Any other value for @var{order} removes the numeric order of @var{element}
778 if it already has one; otherwise, it is equivalent to @code{nil}.
780 The argument @var{symbol} is not implicitly quoted;
781 @code{add-to-ordered-list} is an ordinary function, like @code{set}
782 and unlike @code{setq}. Quote the argument yourself if necessary.
784 The ordering information is stored in a hash table on @var{symbol}'s
785 @code{list-order} property.
788 Here's a scenario showing how to use @code{add-to-ordered-list}:
794 (add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.}
797 (add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.}
800 (add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.}
803 (add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.}
806 (add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.}
809 (add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}.
810 @result{} (a c b e d)
812 foo ;; @r{@code{foo} was changed.}
813 @result{} (a c b e d)
816 @node Modifying Lists
817 @section Modifying Existing List Structure
818 @cindex destructive list operations
820 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
821 primitives @code{setcar} and @code{setcdr}. We call these ``destructive''
822 operations because they change existing list structure.
824 @cindex CL note---@code{rplaca} vs @code{setcar}
828 @b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and
829 @code{rplacd} to alter list structure; they change structure the same
830 way as @code{setcar} and @code{setcdr}, but the Common Lisp functions
831 return the cons cell while @code{setcar} and @code{setcdr} return the
832 new @sc{car} or @sc{cdr}.
836 * Setcar:: Replacing an element in a list.
837 * Setcdr:: Replacing part of the list backbone.
838 This can be used to remove or add elements.
839 * Rearrangement:: Reordering the elements in a list; combining lists.
843 @subsection Altering List Elements with @code{setcar}
844 @cindex replace list element
845 @cindex list, replace element
847 Changing the @sc{car} of a cons cell is done with @code{setcar}. When
848 used on a list, @code{setcar} replaces one element of a list with a
851 @defun setcar cons object
852 This function stores @var{object} as the new @sc{car} of @var{cons},
853 replacing its previous @sc{car}. In other words, it changes the
854 @sc{car} slot of @var{cons} to refer to @var{object}. It returns the
855 value @var{object}. For example:
873 When a cons cell is part of the shared structure of several lists,
874 storing a new @sc{car} into the cons changes one element of each of
875 these lists. Here is an example:
879 ;; @r{Create two lists that are partly shared.}
882 (setq x2 (cons 'z (cdr x1)))
887 ;; @r{Replace the @sc{car} of a shared link.}
888 (setcar (cdr x1) 'foo)
890 x1 ; @r{Both lists are changed.}
897 ;; @r{Replace the @sc{car} of a link that is not shared.}
900 x1 ; @r{Only one list is changed.}
901 @result{} (baz foo c)
907 Here is a graphical depiction of the shared structure of the two lists
908 in the variables @code{x1} and @code{x2}, showing why replacing @code{b}
913 --- --- --- --- --- ---
914 x1---> | | |----> | | |--> | | |--> nil
915 --- --- --- --- --- ---
929 Here is an alternative form of box diagram, showing the same relationship:
934 -------------- -------------- --------------
935 | car | cdr | | car | cdr | | car | cdr |
936 | a | o------->| b | o------->| c | nil |
938 -------------- | -------------- --------------
950 @subsection Altering the CDR of a List
951 @cindex replace part of list
953 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
955 @defun setcdr cons object
956 This function stores @var{object} as the new @sc{cdr} of @var{cons},
957 replacing its previous @sc{cdr}. In other words, it changes the
958 @sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the
962 Here is an example of replacing the @sc{cdr} of a list with a
963 different list. All but the first element of the list are removed in
964 favor of a different sequence of elements. The first element is
965 unchanged, because it resides in the @sc{car} of the list, and is not
966 reached via the @sc{cdr}.
983 You can delete elements from the middle of a list by altering the
984 @sc{cdr}s of the cons cells in the list. For example, here we delete
985 the second element, @code{b}, from the list @code{(a b c)}, by changing
986 the @sc{cdr} of the first cons cell:
992 (setcdr x1 (cdr (cdr x1)))
999 Here is the result in box notation:
1003 --------------------
1005 -------------- | -------------- | --------------
1006 | car | cdr | | | car | cdr | -->| car | cdr |
1007 | a | o----- | b | o-------->| c | nil |
1009 -------------- -------------- --------------
1014 The second cons cell, which previously held the element @code{b}, still
1015 exists and its @sc{car} is still @code{b}, but it no longer forms part
1018 It is equally easy to insert a new element by changing @sc{cdr}s:
1024 (setcdr x1 (cons 'd (cdr x1)))
1031 Here is this result in box notation:
1035 -------------- ------------- -------------
1036 | car | cdr | | car | cdr | | car | cdr |
1037 | a | o | -->| b | o------->| c | nil |
1038 | | | | | | | | | | |
1039 --------- | -- | ------------- -------------
1052 @subsection Functions that Rearrange Lists
1053 @cindex rearrangement of lists
1054 @cindex reordering, of elements in lists
1055 @cindex modification of lists
1057 Here are some functions that rearrange lists ``destructively'' by
1058 modifying the @sc{cdr}s of their component cons cells. We call these
1059 functions ``destructive'' because they chew up the original lists passed
1060 to them as arguments, relinking their cons cells to form a new list that
1061 is the returned value.
1064 See @code{delq}, in @ref{Sets And Lists}, for another function
1065 that modifies cons cells.
1068 The function @code{delq} in the following section is another example
1069 of destructive list manipulation.
1072 @defun nconc &rest lists
1073 @cindex concatenating lists
1074 @cindex joining lists
1075 This function returns a list containing all the elements of @var{lists}.
1076 Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
1077 @emph{not} copied. Instead, the last @sc{cdr} of each of the
1078 @var{lists} is changed to refer to the following list. The last of the
1079 @var{lists} is not altered. For example:
1088 @result{} (1 2 3 4 5)
1092 @result{} (1 2 3 4 5)
1096 Since the last argument of @code{nconc} is not itself modified, it is
1097 reasonable to use a constant list, such as @code{'(4 5)}, as in the
1098 above example. For the same reason, the last argument need not be a
1108 @result{} (1 2 3 . z)
1112 @result{} (1 2 3 . z)
1116 However, the other arguments (all but the last) must be lists.
1118 A common pitfall is to use a quoted constant list as a non-last
1119 argument to @code{nconc}. If you do this, your program will change
1120 each time you run it! Here is what happens:
1124 (defun add-foo (x) ; @r{We want this function to add}
1125 (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.}
1129 (symbol-function 'add-foo)
1130 @result{} (lambda (x) (nconc (quote (foo)) x))
1134 (setq xx (add-foo '(1 2))) ; @r{It seems to work.}
1138 (setq xy (add-foo '(3 4))) ; @r{What happened?}
1139 @result{} (foo 1 2 3 4)
1147 (symbol-function 'add-foo)
1148 @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
1153 @defun nreverse list
1154 @cindex reversing a list
1155 This function reverses the order of the elements of @var{list}.
1156 Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
1157 the @sc{cdr}s in the cons cells forming the list. The cons cell that
1158 used to be the last one in @var{list} becomes the first cons cell of the
1175 ;; @r{The cons cell that was first is now last.}
1181 To avoid confusion, we usually store the result of @code{nreverse}
1182 back in the same variable which held the original list:
1185 (setq x (nreverse x))
1188 Here is the @code{nreverse} of our favorite example, @code{(a b c)},
1189 presented graphically:
1193 @r{Original list head:} @r{Reversed list:}
1194 ------------- ------------- ------------
1195 | car | cdr | | car | cdr | | car | cdr |
1196 | a | nil |<-- | b | o |<-- | c | o |
1197 | | | | | | | | | | | | |
1198 ------------- | --------- | - | -------- | -
1200 ------------- ------------
1205 @defun sort list predicate
1207 @cindex sorting lists
1208 This function sorts @var{list} stably, though destructively, and
1209 returns the sorted list. It compares elements using @var{predicate}. A
1210 stable sort is one in which elements with equal sort keys maintain their
1211 relative order before and after the sort. Stability is important when
1212 successive sorts are used to order elements according to different
1215 The argument @var{predicate} must be a function that accepts two
1216 arguments. It is called with two elements of @var{list}. To get an
1217 increasing order sort, the @var{predicate} should return non-@code{nil} if the
1218 first element is ``less than'' the second, or @code{nil} if not.
1220 The comparison function @var{predicate} must give reliable results for
1221 any given pair of arguments, at least within a single call to
1222 @code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
1223 less than @var{b}, @var{b} must not be less than @var{a}. It must be
1224 @dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
1225 is less than @var{c}, then @var{a} must be less than @var{c}. If you
1226 use a comparison function which does not meet these requirements, the
1227 result of @code{sort} is unpredictable.
1229 The destructive aspect of @code{sort} is that it rearranges the cons
1230 cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort
1231 function would create new cons cells to store the elements in their
1232 sorted order. If you wish to make a sorted copy without destroying the
1233 original, copy it first with @code{copy-sequence} and then sort.
1235 Sorting does not change the @sc{car}s of the cons cells in @var{list};
1236 the cons cell that originally contained the element @code{a} in
1237 @var{list} still has @code{a} in its @sc{car} after sorting, but it now
1238 appears in a different position in the list due to the change of
1239 @sc{cdr}s. For example:
1243 (setq nums '(1 3 2 6 5 4 0))
1244 @result{} (1 3 2 6 5 4 0)
1248 @result{} (0 1 2 3 4 5 6)
1252 @result{} (1 2 3 4 5 6)
1257 @strong{Warning}: Note that the list in @code{nums} no longer contains
1258 0; this is the same cons cell that it was before, but it is no longer
1259 the first one in the list. Don't assume a variable that formerly held
1260 the argument now holds the entire sorted list! Instead, save the result
1261 of @code{sort} and use that. Most often we store the result back into
1262 the variable that held the original list:
1265 (setq nums (sort nums '<))
1268 @xref{Sorting}, for more functions that perform sorting.
1269 See @code{documentation} in @ref{Accessing Documentation}, for a
1270 useful example of @code{sort}.
1273 @node Sets And Lists
1274 @section Using Lists as Sets
1275 @cindex lists as sets
1278 A list can represent an unordered mathematical set---simply consider a
1279 value an element of a set if it appears in the list, and ignore the
1280 order of the list. To form the union of two sets, use @code{append} (as
1281 long as you don't mind having duplicate elements). You can remove
1282 @code{equal} duplicates using @code{delete-dups}. Other useful
1283 functions for sets include @code{memq} and @code{delq}, and their
1284 @code{equal} versions, @code{member} and @code{delete}.
1286 @cindex CL note---lack @code{union}, @code{intersection}
1288 @b{Common Lisp note:} Common Lisp has functions @code{union} (which
1289 avoids duplicate elements) and @code{intersection} for set operations.
1290 Although standard GNU Emacs Lisp does not have them, the @file{cl-lib}
1291 library provides versions.
1292 @xref{Lists as Sets,,, cl, Common Lisp Extensions}.
1295 @defun memq object list
1296 @cindex membership in a list
1297 This function tests to see whether @var{object} is a member of
1298 @var{list}. If it is, @code{memq} returns a list starting with the
1299 first occurrence of @var{object}. Otherwise, it returns @code{nil}.
1300 The letter @samp{q} in @code{memq} says that it uses @code{eq} to
1301 compare @var{object} against the elements of the list. For example:
1305 (memq 'b '(a b c b a))
1309 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
1315 @defun delq object list
1316 @cindex deleting list elements
1317 This function destructively removes all elements @code{eq} to
1318 @var{object} from @var{list}, and returns the resulting list. The
1319 letter @samp{q} in @code{delq} says that it uses @code{eq} to compare
1320 @var{object} against the elements of the list, like @code{memq} and
1323 Typically, when you invoke @code{delq}, you should use the return
1324 value by assigning it to the variable which held the original list.
1325 The reason for this is explained below.
1328 The @code{delq} function deletes elements from the front of the list
1329 by simply advancing down the list, and returning a sublist that starts
1330 after those elements. For example:
1334 (delq 'a '(a b c)) @equiv{} (cdr '(a b c))
1339 When an element to be deleted appears in the middle of the list,
1340 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
1344 (setq sample-list '(a b c (4)))
1345 @result{} (a b c (4))
1348 (delq 'a sample-list)
1353 @result{} (a b c (4))
1356 (delq 'c sample-list)
1365 Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to
1366 splice out the third element, but @code{(delq 'a sample-list)} does not
1367 splice anything---it just returns a shorter list. Don't assume that a
1368 variable which formerly held the argument @var{list} now has fewer
1369 elements, or that it still holds the original list! Instead, save the
1370 result of @code{delq} and use that. Most often we store the result back
1371 into the variable that held the original list:
1374 (setq flowers (delq 'rose flowers))
1377 In the following example, the @code{(4)} that @code{delq} attempts to match
1378 and the @code{(4)} in the @code{sample-list} are not @code{eq}:
1382 (delq '(4) sample-list)
1387 If you want to delete elements that are @code{equal} to a given value,
1388 use @code{delete} (see below).
1390 @defun remq object list
1391 This function returns a copy of @var{list}, with all elements removed
1392 which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq}
1393 says that it uses @code{eq} to compare @var{object} against the elements
1398 (setq sample-list '(a b c a b c))
1399 @result{} (a b c a b c)
1402 (remq 'a sample-list)
1407 @result{} (a b c a b c)
1412 @defun memql object list
1413 The function @code{memql} tests to see whether @var{object} is a member
1414 of @var{list}, comparing members with @var{object} using @code{eql},
1415 so floating-point elements are compared by value.
1416 If @var{object} is a member, @code{memql} returns a list starting with
1417 its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
1419 Compare this with @code{memq}:
1423 (memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
1427 (memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
1433 The following three functions are like @code{memq}, @code{delq} and
1434 @code{remq}, but use @code{equal} rather than @code{eq} to compare
1435 elements. @xref{Equality Predicates}.
1437 @defun member object list
1438 The function @code{member} tests to see whether @var{object} is a member
1439 of @var{list}, comparing members with @var{object} using @code{equal}.
1440 If @var{object} is a member, @code{member} returns a list starting with
1441 its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
1443 Compare this with @code{memq}:
1447 (member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
1451 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
1455 ;; @r{Two strings with the same contents are @code{equal}.}
1456 (member "foo" '("foo" "bar"))
1457 @result{} ("foo" "bar")
1462 @defun delete object sequence
1463 This function removes all elements @code{equal} to @var{object} from
1464 @var{sequence}, and returns the resulting sequence.
1466 If @var{sequence} is a list, @code{delete} is to @code{delq} as
1467 @code{member} is to @code{memq}: it uses @code{equal} to compare
1468 elements with @var{object}, like @code{member}; when it finds an
1469 element that matches, it cuts the element out just as @code{delq}
1470 would. As with @code{delq}, you should typically use the return value
1471 by assigning it to the variable which held the original list.
1473 If @code{sequence} is a vector or string, @code{delete} returns a copy
1474 of @code{sequence} with all elements @code{equal} to @code{object}
1481 (setq l '((2) (1) (2)))
1486 ;; @r{If you want to change @code{l} reliably,}
1487 ;; @r{write @code{(setq l (delete '(2) l))}.}
1490 (setq l '((2) (1) (2)))
1495 ;; @r{In this case, it makes no difference whether you set @code{l},}
1496 ;; @r{but you should do so for the sake of the other case.}
1499 (delete '(2) [(2) (1) (2)])
1505 @defun remove object sequence
1506 This function is the non-destructive counterpart of @code{delete}. It
1507 returns a copy of @code{sequence}, a list, vector, or string, with
1508 elements @code{equal} to @code{object} removed. For example:
1512 (remove '(2) '((2) (1) (2)))
1516 (remove '(2) [(2) (1) (2)])
1523 @b{Common Lisp note:} The functions @code{member}, @code{delete} and
1524 @code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
1525 Lisp. The Common Lisp versions do not use @code{equal} to compare
1529 @defun member-ignore-case object list
1530 This function is like @code{member}, except that @var{object} should
1531 be a string and that it ignores differences in letter-case and text
1532 representation: upper-case and lower-case letters are treated as
1533 equal, and unibyte strings are converted to multibyte prior to
1537 @defun delete-dups list
1538 This function destructively removes all @code{equal} duplicates from
1539 @var{list}, stores the result in @var{list} and returns it. Of
1540 several @code{equal} occurrences of an element in @var{list},
1541 @code{delete-dups} keeps the first one.
1544 See also the function @code{add-to-list}, in @ref{List Variables},
1545 for a way to add an element to a list stored in a variable and used as a
1548 @node Association Lists
1549 @section Association Lists
1550 @cindex association list
1553 An @dfn{association list}, or @dfn{alist} for short, records a mapping
1554 from keys to values. It is a list of cons cells called
1555 @dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
1556 @sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key''
1557 is not related to the term ``key sequence''; it means a value used to
1558 look up an item in a table. In this case, the table is the alist, and
1559 the alist associations are the items.}
1561 Here is an example of an alist. The key @code{pine} is associated with
1562 the value @code{cones}; the key @code{oak} is associated with
1563 @code{acorns}; and the key @code{maple} is associated with @code{seeds}.
1573 Both the values and the keys in an alist may be any Lisp objects.
1574 For example, in the following alist, the symbol @code{a} is
1575 associated with the number @code{1}, and the string @code{"b"} is
1576 associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of
1583 Sometimes it is better to design an alist to store the associated
1584 value in the @sc{car} of the @sc{cdr} of the element. Here is an
1585 example of such an alist:
1588 ((rose red) (lily white) (buttercup yellow))
1592 Here we regard @code{red} as the value associated with @code{rose}. One
1593 advantage of this kind of alist is that you can store other related
1594 information---even a list of other items---in the @sc{cdr} of the
1595 @sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see
1596 below) to find the element containing a given value. When neither of
1597 these considerations is important, the choice is a matter of taste, as
1598 long as you are consistent about it for any given alist.
1600 The same alist shown above could be regarded as having the
1601 associated value in the @sc{cdr} of the element; the value associated
1602 with @code{rose} would be the list @code{(red)}.
1604 Association lists are often used to record information that you might
1605 otherwise keep on a stack, since new associations may be added easily to
1606 the front of the list. When searching an association list for an
1607 association with a given key, the first one found is returned, if there
1610 In Emacs Lisp, it is @emph{not} an error if an element of an
1611 association list is not a cons cell. The alist search functions simply
1612 ignore such elements. Many other versions of Lisp signal errors in such
1615 Note that property lists are similar to association lists in several
1616 respects. A property list behaves like an association list in which
1617 each key can occur only once. @xref{Property Lists}, for a comparison
1618 of property lists and association lists.
1620 @defun assoc key alist
1621 This function returns the first association for @var{key} in
1622 @var{alist}, comparing @var{key} against the alist elements using
1623 @code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no
1624 association in @var{alist} has a @sc{car} @code{equal} to @var{key}.
1628 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
1629 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
1631 @result{} (oak . acorns)
1632 (cdr (assoc 'oak trees))
1634 (assoc 'birch trees)
1638 Here is another example, in which the keys and values are not symbols:
1641 (setq needles-per-cluster
1642 '((2 "Austrian Pine" "Red Pine")
1646 (cdr (assoc 3 needles-per-cluster))
1647 @result{} ("Pitch Pine")
1648 (cdr (assoc 2 needles-per-cluster))
1649 @result{} ("Austrian Pine" "Red Pine")
1653 The function @code{assoc-string} is much like @code{assoc} except
1654 that it ignores certain differences between strings. @xref{Text
1657 @defun rassoc value alist
1658 This function returns the first association with value @var{value} in
1659 @var{alist}. It returns @code{nil} if no association in @var{alist} has
1660 a @sc{cdr} @code{equal} to @var{value}.
1662 @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
1663 each @var{alist} association instead of the @sc{car}. You can think of
1664 this as ``reverse @code{assoc}'', finding the key for a given value.
1667 @defun assq key alist
1668 This function is like @code{assoc} in that it returns the first
1669 association for @var{key} in @var{alist}, but it makes the comparison
1670 using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil}
1671 if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}.
1672 This function is used more often than @code{assoc}, since @code{eq} is
1673 faster than @code{equal} and most alists use symbols as keys.
1674 @xref{Equality Predicates}.
1677 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
1678 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
1680 @result{} (pine . cones)
1683 On the other hand, @code{assq} is not usually useful in alists where the
1684 keys may not be symbols:
1688 '(("simple leaves" . oak)
1689 ("compound leaves" . horsechestnut)))
1691 (assq "simple leaves" leaves)
1693 (assoc "simple leaves" leaves)
1694 @result{} ("simple leaves" . oak)
1698 @defun rassq value alist
1699 This function returns the first association with value @var{value} in
1700 @var{alist}. It returns @code{nil} if no association in @var{alist} has
1701 a @sc{cdr} @code{eq} to @var{value}.
1703 @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
1704 each @var{alist} association instead of the @sc{car}. You can think of
1705 this as ``reverse @code{assq}'', finding the key for a given value.
1710 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
1712 (rassq 'acorns trees)
1713 @result{} (oak . acorns)
1714 (rassq 'spores trees)
1718 @code{rassq} cannot search for a value stored in the @sc{car}
1719 of the @sc{cdr} of an element:
1722 (setq colors '((rose red) (lily white) (buttercup yellow)))
1724 (rassq 'white colors)
1728 In this case, the @sc{cdr} of the association @code{(lily white)} is not
1729 the symbol @code{white}, but rather the list @code{(white)}. This
1730 becomes clearer if the association is written in dotted pair notation:
1733 (lily white) @equiv{} (lily . (white))
1737 @defun assoc-default key alist &optional test default
1738 This function searches @var{alist} for a match for @var{key}. For each
1739 element of @var{alist}, it compares the element (if it is an atom) or
1740 the element's @sc{car} (if it is a cons) against @var{key}, by calling
1741 @var{test} with two arguments: the element or its @sc{car}, and
1742 @var{key}. The arguments are passed in that order so that you can get
1743 useful results using @code{string-match} with an alist that contains
1744 regular expressions (@pxref{Regexp Search}). If @var{test} is omitted
1745 or @code{nil}, @code{equal} is used for comparison.
1747 If an alist element matches @var{key} by this criterion,
1748 then @code{assoc-default} returns a value based on this element.
1749 If the element is a cons, then the value is the element's @sc{cdr}.
1750 Otherwise, the return value is @var{default}.
1752 If no alist element matches @var{key}, @code{assoc-default} returns
1756 @defun copy-alist alist
1757 @cindex copying alists
1758 This function returns a two-level deep copy of @var{alist}: it creates a
1759 new copy of each association, so that you can alter the associations of
1760 the new alist without changing the old one.
1764 (setq needles-per-cluster
1765 '((2 . ("Austrian Pine" "Red Pine"))
1766 (3 . ("Pitch Pine"))
1768 (5 . ("White Pine"))))
1770 ((2 "Austrian Pine" "Red Pine")
1774 (setq copy (copy-alist needles-per-cluster))
1776 ((2 "Austrian Pine" "Red Pine")
1780 (eq needles-per-cluster copy)
1782 (equal needles-per-cluster copy)
1784 (eq (car needles-per-cluster) (car copy))
1786 (cdr (car (cdr needles-per-cluster)))
1787 @result{} ("Pitch Pine")
1789 (eq (cdr (car (cdr needles-per-cluster)))
1790 (cdr (car (cdr copy))))
1795 This example shows how @code{copy-alist} makes it possible to change
1796 the associations of one copy without affecting the other:
1800 (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
1801 (cdr (assq 3 needles-per-cluster))
1802 @result{} ("Pitch Pine")
1807 @defun assq-delete-all key alist
1808 This function deletes from @var{alist} all the elements whose @sc{car}
1809 is @code{eq} to @var{key}, much as if you used @code{delq} to delete
1810 each such element one by one. It returns the shortened alist, and
1811 often modifies the original list structure of @var{alist}. For
1812 correct results, use the return value of @code{assq-delete-all} rather
1813 than looking at the saved value of @var{alist}.
1816 (setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
1817 @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
1818 (assq-delete-all 'foo alist)
1819 @result{} ((bar 2) (lose 4))
1821 @result{} ((foo 1) (bar 2) (lose 4))
1825 @defun rassq-delete-all value alist
1826 This function deletes from @var{alist} all the elements whose @sc{cdr}
1827 is @code{eq} to @var{value}. It returns the shortened alist, and
1828 often modifies the original list structure of @var{alist}.
1829 @code{rassq-delete-all} is like @code{assq-delete-all} except that it
1830 compares the @sc{cdr} of each @var{alist} association instead of the
1834 @node Property Lists
1835 @section Property Lists
1836 @cindex property list
1839 A @dfn{property list} (@dfn{plist} for short) is a list of paired
1840 elements. Each of the pairs associates a property name (usually a
1841 symbol) with a property or value. Here is an example of a property
1845 (pine cones numbers (1 2 3) color "blue")
1849 This property list associates @code{pine} with @code{cones},
1850 @code{numbers} with @code{(1 2 3)}, and @code{color} with
1851 @code{"blue"}. The property names and values can be any Lisp objects,
1852 but the names are usually symbols (as they are in this example).
1854 Property lists are used in several contexts. For instance, the
1855 function @code{put-text-property} takes an argument which is a
1856 property list, specifying text properties and associated values which
1857 are to be applied to text in a string or buffer. @xref{Text
1860 Another prominent use of property lists is for storing symbol
1861 properties. Every symbol possesses a list of properties, used to
1862 record miscellaneous information about the symbol; these properties
1863 are stored in the form of a property list. @xref{Symbol Properties}.
1866 * Plists and Alists:: Comparison of the advantages of property
1867 lists and association lists.
1868 * Plist Access:: Accessing property lists stored elsewhere.
1871 @node Plists and Alists
1872 @subsection Property Lists and Association Lists
1873 @cindex plist vs. alist
1874 @cindex alist vs. plist
1876 @cindex property lists vs association lists
1877 Association lists (@pxref{Association Lists}) are very similar to
1878 property lists. In contrast to association lists, the order of the
1879 pairs in the property list is not significant, since the property
1880 names must be distinct.
1882 Property lists are better than association lists for attaching
1883 information to various Lisp function names or variables. If your
1884 program keeps all such information in one association list, it will
1885 typically need to search that entire list each time it checks for an
1886 association for a particular Lisp function name or variable, which
1887 could be slow. By contrast, if you keep the same information in the
1888 property lists of the function names or variables themselves, each
1889 search will scan only the length of one property list, which is
1890 usually short. This is why the documentation for a variable is
1891 recorded in a property named @code{variable-documentation}. The byte
1892 compiler likewise uses properties to record those functions needing
1895 However, association lists have their own advantages. Depending on
1896 your application, it may be faster to add an association to the front of
1897 an association list than to update a property. All properties for a
1898 symbol are stored in the same property list, so there is a possibility
1899 of a conflict between different uses of a property name. (For this
1900 reason, it is a good idea to choose property names that are probably
1901 unique, such as by beginning the property name with the program's usual
1902 name-prefix for variables and functions.) An association list may be
1903 used like a stack where associations are pushed on the front of the list
1904 and later discarded; this is not possible with a property list.
1907 @subsection Property Lists Outside Symbols
1908 @cindex plist access
1909 @cindex accessing plist properties
1911 The following functions can be used to manipulate property lists.
1912 They all compare property names using @code{eq}.
1914 @defun plist-get plist property
1915 This returns the value of the @var{property} property stored in the
1916 property list @var{plist}. It accepts a malformed @var{plist}
1917 argument. If @var{property} is not found in the @var{plist}, it
1918 returns @code{nil}. For example,
1921 (plist-get '(foo 4) 'foo)
1923 (plist-get '(foo 4 bad) 'foo)
1925 (plist-get '(foo 4 bad) 'bad)
1927 (plist-get '(foo 4 bad) 'bar)
1932 @defun plist-put plist property value
1933 This stores @var{value} as the value of the @var{property} property in
1934 the property list @var{plist}. It may modify @var{plist} destructively,
1935 or it may construct a new list structure without altering the old. The
1936 function returns the modified property list, so you can store that back
1937 in the place where you got @var{plist}. For example,
1940 (setq my-plist '(bar t foo 4))
1941 @result{} (bar t foo 4)
1942 (setq my-plist (plist-put my-plist 'foo 69))
1943 @result{} (bar t foo 69)
1944 (setq my-plist (plist-put my-plist 'quux '(a)))
1945 @result{} (bar t foo 69 quux (a))
1949 @defun lax-plist-get plist property
1950 Like @code{plist-get} except that it compares properties
1951 using @code{equal} instead of @code{eq}.
1954 @defun lax-plist-put plist property value
1955 Like @code{plist-put} except that it compares properties
1956 using @code{equal} instead of @code{eq}.
1959 @defun plist-member plist property
1960 This returns non-@code{nil} if @var{plist} contains the given
1961 @var{property}. Unlike @code{plist-get}, this allows you to distinguish
1962 between a missing property and a property with the value @code{nil}.
1963 The value is actually the tail of @var{plist} whose @code{car} is