annotate doc/lispref/lists.texi @ 110866:4b97fee97310

Add doc/ dependencies on emacsver.texi. * doc/misc/Makefile.in ($(infodir)/efaq): Depend on emacsver.texi. * doc/lispref/Makefile.in (srcs): Add emacsver.texi. * doc/emacs/Makefile.in (EMACSSOURCES): Add emacsver.texi.
author Glenn Morris <rgm@gnu.org>
date Fri, 08 Oct 2010 19:09:46 -0700
parents 1d1d5d9bd884
children 376148b31b5e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84080
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
106815
1d1d5d9bd884 Add 2010 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 102183
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
84080
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84080
diff changeset
6 @setfilename ../../info/lists
84080
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @node Lists, Sequences Arrays Vectors, Strings and Characters, Top
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @chapter Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @cindex lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10 @cindex element (of list)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12 A @dfn{list} represents a sequence of zero or more elements (which may
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13 be any Lisp objects). The important difference between lists and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14 vectors is that two or more lists can share part of their structure; in
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15 addition, you can insert or delete elements in a list without copying
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16 the whole list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 @menu
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 * Cons Cells:: How lists are made out of cons cells.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 * List-related Predicates:: Is this object a list? Comparing two lists.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 * List Elements:: Extracting the pieces of a list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 * Building Lists:: Creating list structure.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
23 * List Variables:: Modifying lists stored in variables.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24 * Modifying Lists:: Storing new pieces into an existing list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
25 * Sets And Lists:: A list can represent a finite mathematical set.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
26 * Association Lists:: A list can represent a finite relation or mapping.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
27 * Rings:: Managing a fixed-size ring of objects.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 @end menu
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
29
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
30 @node Cons Cells
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
31 @section Lists and Cons Cells
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 @cindex lists and cons cells
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34 Lists in Lisp are not a primitive data type; they are built up from
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 @dfn{cons cells}. A cons cell is a data object that represents an
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
36 ordered pair. That is, it has two slots, and each slot @dfn{holds}, or
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
37 @dfn{refers to}, some Lisp object. One slot is known as the @sc{car},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
38 and the other is known as the @sc{cdr}. (These names are traditional;
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
39 see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.''
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
40
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 We say that ``the @sc{car} of this cons cell is'' whatever object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44 A list is a series of cons cells ``chained together,'' so that each
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45 cell refers to the next one. There is one cons cell for each element of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46 the list. By convention, the @sc{car}s of the cons cells hold the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 elements of the list, and the @sc{cdr}s are used to chain the list: the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48 @sc{cdr} slot of each cons cell refers to the following cons cell. The
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49 @sc{cdr} of the last cons cell is @code{nil}. This asymmetry between
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51 level of cons cells, the @sc{car} and @sc{cdr} slots have the same
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 characteristics.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54 @cindex true list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55 Since @code{nil} is the conventional value to put in the @sc{cdr} of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
56 the last cons cell in the list, we call that case a @dfn{true list}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
57
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
58 In Lisp, we consider the symbol @code{nil} a list as well as a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
59 symbol; it is the list with no elements. For convenience, the symbol
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60 @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61 as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 true list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
64 @cindex dotted list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
65 @cindex circular list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
66 If the @sc{cdr} of a list's last cons cell is some other value,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
67 neither @code{nil} nor another cons cell, we call the structure a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
68 @dfn{dotted list}, since its printed representation would use
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69 @samp{.}. There is one other possibility: some cons cell's @sc{cdr}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70 could point to one of the previous cons cells in the list. We call
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71 that structure a @dfn{circular list}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
73 For some purposes, it does not matter whether a list is true,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
74 circular or dotted. If the program doesn't look far enough down the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
75 list to see the @sc{cdr} of the final cons cell, it won't care.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76 However, some functions that operate on lists demand true lists and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 signal errors if given a dotted list. Most functions that try to find
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78 the end of a list enter infinite loops if given a circular list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80 @cindex list structure
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
81 Because most cons cells are used as part of lists, the phrase
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
82 @dfn{list structure} has come to mean any structure made out of cons
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
83 cells.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
84
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85 The @sc{cdr} of any nonempty true list @var{l} is a list containing all the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86 elements of @var{l} except the first.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
87
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
88 @xref{Cons Cell Type}, for the read and print syntax of cons cells and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
89 lists, and for ``box and arrow'' illustrations of lists.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
90
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91 @node List-related Predicates
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92 @section Predicates on Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 The following predicates test whether a Lisp object is an atom,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 whether it is a cons cell or is a list, or whether it is the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 distinguished object @code{nil}. (Many of these predicates can be
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97 defined in terms of the others, but they are used so often that it is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 worth having all of them.)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100 @defun consp object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101 This function returns @code{t} if @var{object} is a cons cell, @code{nil}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 otherwise. @code{nil} is not a cons cell, although it @emph{is} a list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 @defun atom object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106 This function returns @code{t} if @var{object} is an atom, @code{nil}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107 otherwise. All objects except cons cells are atoms. The symbol
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108 @code{nil} is an atom and is also a list; it is the only Lisp object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109 that is both.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112 (atom @var{object}) @equiv{} (not (consp @var{object}))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116 @defun listp object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 This function returns @code{t} if @var{object} is a cons cell or
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118 @code{nil}. Otherwise, it returns @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
122 (listp '(1))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
123 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126 (listp '())
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
130 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
131
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
132 @defun nlistp object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
133 This function is the opposite of @code{listp}: it returns @code{t} if
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
134 @var{object} is not a list. Otherwise, it returns @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
135
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
136 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
137 (listp @var{object}) @equiv{} (not (nlistp @var{object}))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
138 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141 @defun null object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142 This function returns @code{t} if @var{object} is @code{nil}, and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 returns @code{nil} otherwise. This function is identical to @code{not},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 but as a matter of clarity we use @code{null} when @var{object} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145 considered a list and @code{not} when it is considered a truth value
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146 (see @code{not} in @ref{Combining Conditions}).
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150 (null '(1))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154 (null '())
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
156 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
157 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161 @node List Elements
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
162 @section Accessing Elements of Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
163 @cindex list elements
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
165 @defun car cons-cell
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
166 This function returns the value referred to by the first slot of the
102183
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
167 cons cell @var{cons-cell}. In other words, it returns the @sc{car} of
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
168 @var{cons-cell}.
84080
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169
102183
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
170 As a special case, if @var{cons-cell} is @code{nil}, this function
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
171 returns @code{nil}. Therefore, any list is a valid argument. An
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
172 error is signaled if the argument is not a cons cell or @code{nil}.
84080
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176 (car '(a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 @result{} a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 (car '())
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186 @defun cdr cons-cell
102183
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
187 This function returns the value referred to by the second slot of the
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
188 cons cell @var{cons-cell}. In other words, it returns the @sc{cdr} of
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
189 @var{cons-cell}.
84080
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190
102183
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
191 As a special case, if @var{cons-cell} is @code{nil}, this function
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
192 returns @code{nil}; therefore, any list is a valid argument. An error
1d59ea1e4daf (List Elements): Copyedits.
Chong Yidong <cyd@stupidchicken.com>
parents: 102179
diff changeset
193 is signaled if the argument is not a cons cell or @code{nil}.
84080
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 (cdr '(a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 @result{} (b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201 (cdr '())
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
203 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
204 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
205 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
206
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
207 @defun car-safe object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 This function lets you take the @sc{car} of a cons cell while avoiding
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
209 errors for other data types. It returns the @sc{car} of @var{object} if
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 @var{object} is a cons cell, @code{nil} otherwise. This is in contrast
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
211 to @code{car}, which signals an error if @var{object} is not a list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
212
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
213 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 (car-safe @var{object})
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216 @equiv{}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 (let ((x @var{object}))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218 (if (consp x)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219 (car x)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 nil))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
224
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225 @defun cdr-safe object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226 This function lets you take the @sc{cdr} of a cons cell while
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 avoiding errors for other data types. It returns the @sc{cdr} of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 @var{object} if @var{object} is a cons cell, @code{nil} otherwise.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 This is in contrast to @code{cdr}, which signals an error if
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230 @var{object} is not a list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234 (cdr-safe @var{object})
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235 @equiv{}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 (let ((x @var{object}))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237 (if (consp x)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238 (cdr x)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 nil))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
242 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
243
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244 @defmac pop listname
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245 This macro is a way of examining the @sc{car} of a list,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 and taking it off the list, all at once.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248 It operates on the list which is stored in the symbol @var{listname}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 It removes this element from the list by setting @var{listname}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 to the @sc{cdr} of its old value---but it also returns the @sc{car}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251 of that list, which is the element being removed.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 @result{} (a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256 (pop x)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257 @result{} a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259 @result{} (b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261 @end defmac
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263 @defun nth n list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 @anchor{Definition of nth}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 This function returns the @var{n}th element of @var{list}. Elements
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 are numbered starting with zero, so the @sc{car} of @var{list} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267 element number zero. If the length of @var{list} is @var{n} or less,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268 the value is @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270 If @var{n} is negative, @code{nth} returns the first element of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 @var{list}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
273 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275 (nth 2 '(1 2 3 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276 @result{} 3
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279 (nth 10 '(1 2 3 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 (nth -3 '(1 2 3 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 @result{} 1
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 (nth n x) @equiv{} (car (nthcdr n x))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 The function @code{elt} is similar, but applies to any kind of sequence.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 For historical reasons, it takes its arguments in the opposite order.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292 @xref{Sequence Functions}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295 @defun nthcdr n list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296 This function returns the @var{n}th @sc{cdr} of @var{list}. In other
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 words, it skips past the first @var{n} links of @var{list} and returns
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298 what follows.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300 If @var{n} is zero or negative, @code{nthcdr} returns all of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301 @var{list}. If the length of @var{list} is @var{n} or less,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 @code{nthcdr} returns @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306 (nthcdr 1 '(1 2 3 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 @result{} (2 3 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310 (nthcdr 10 '(1 2 3 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314 (nthcdr -3 '(1 2 3 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 @result{} (1 2 3 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
319
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
320 @defun last list &optional n
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
321 This function returns the last link of @var{list}. The @code{car} of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
322 this link is the list's last element. If @var{list} is null,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323 @code{nil} is returned. If @var{n} is non-@code{nil}, the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 @var{n}th-to-last link is returned instead, or the whole of @var{list}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 if @var{n} is bigger than @var{list}'s length.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328 @defun safe-length list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329 @anchor{Definition of safe-length}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330 This function returns the length of @var{list}, with no risk of either
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 an error or an infinite loop. It generally returns the number of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
332 distinct cons cells in the list. However, for circular lists,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333 the value is just an upper bound; it is often too large.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
334
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335 If @var{list} is not @code{nil} or a cons cell, @code{safe-length}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
336 returns 0.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
339 The most common way to compute the length of a list, when you are not
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
340 worried that it may be circular, is with @code{length}. @xref{Sequence
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 Functions}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
343 @defun caar cons-cell
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
344 This is the same as @code{(car (car @var{cons-cell}))}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
345 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
346
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
347 @defun cadr cons-cell
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
348 This is the same as @code{(car (cdr @var{cons-cell}))}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
349 or @code{(nth 1 @var{cons-cell})}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352 @defun cdar cons-cell
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 This is the same as @code{(cdr (car @var{cons-cell}))}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
355
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
356 @defun cddr cons-cell
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
357 This is the same as @code{(cdr (cdr @var{cons-cell}))}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
358 or @code{(nthcdr 2 @var{cons-cell})}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
360
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
361 @defun butlast x &optional n
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
362 This function returns the list @var{x} with the last element,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
363 or the last @var{n} elements, removed. If @var{n} is greater
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
364 than zero it makes a copy of the list so as not to damage the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365 original list. In general, @code{(append (butlast @var{x} @var{n})
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366 (last @var{x} @var{n}))} will return a list equal to @var{x}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369 @defun nbutlast x &optional n
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370 This is a version of @code{butlast} that works by destructively
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371 modifying the @code{cdr} of the appropriate element, rather than
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 making a copy of the list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375 @node Building Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 @comment node-name, next, previous, up
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377 @section Building Cons Cells and Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378 @cindex cons cells
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
379 @cindex building lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381 Many functions build lists, as lists reside at the very heart of Lisp.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 @code{cons} is the fundamental list-building function; however, it is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 interesting to note that @code{list} is used more times in the source
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384 code for Emacs than @code{cons}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 @defun cons object1 object2
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 This function is the most basic function for building new list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388 structure. It creates a new cons cell, making @var{object1} the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389 @sc{car}, and @var{object2} the @sc{cdr}. It then returns the new
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 cons cell. The arguments @var{object1} and @var{object2} may be any
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391 Lisp objects, but most often @var{object2} is a list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
395 (cons 1 '(2))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
396 @result{} (1 2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
397 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
398 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
399 (cons 1 '())
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
400 @result{} (1)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
401 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
402 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
403 (cons 1 2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
404 @result{} (1 . 2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
405 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 @cindex consing
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409 @code{cons} is often used to add a single element to the front of a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
410 list. This is called @dfn{consing the element onto the list}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
411 @footnote{There is no strictly equivalent way to add an element to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
412 the end of a list. You can use @code{(append @var{listname} (list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
413 @var{newelt}))}, which creates a whole new list by copying @var{listname}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
414 and adding @var{newelt} to its end. Or you can use @code{(nconc
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
415 @var{listname} (list @var{newelt}))}, which modifies @var{listname}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416 by following all the @sc{cdr}s and then replacing the terminating
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417 @code{nil}. Compare this to adding an element to the beginning of a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
418 list with @code{cons}, which neither copies nor modifies the list.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
419 For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
420
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
421 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
422 (setq list (cons newelt list))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
423 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
424
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
425 Note that there is no conflict between the variable named @code{list}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
426 used in this example and the function named @code{list} described below;
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
427 any symbol can serve both purposes.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
428 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
429
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
430 @defun list &rest objects
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
431 This function creates a list with @var{objects} as its elements. The
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
432 resulting list is always @code{nil}-terminated. If no @var{objects}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
433 are given, the empty list is returned.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
434
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
435 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
436 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
437 (list 1 2 3 4 5)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
438 @result{} (1 2 3 4 5)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
439 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
440 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 (list 1 2 '(3 4 5) 'foo)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442 @result{} (1 2 (3 4 5) foo)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 (list)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
449 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
450
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
451 @defun make-list length object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
452 This function creates a list of @var{length} elements, in which each
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
453 element is @var{object}. Compare @code{make-list} with
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
454 @code{make-string} (@pxref{Creating Strings}).
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
455
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
456 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
457 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
458 (make-list 3 'pigs)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459 @result{} (pigs pigs pigs)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462 (make-list 0 'pigs)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 (setq l (make-list 3 '(a b))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
467 @result{} ((a b) (a b) (a b))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
468 (eq (car l) (cadr l))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
469 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 @defun append &rest sequences
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475 @cindex copying lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 This function returns a list containing all the elements of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
477 @var{sequences}. The @var{sequences} may be lists, vectors,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
478 bool-vectors, or strings, but the last one should usually be a list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
479 All arguments except the last one are copied, so none of the arguments
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480 is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481 lists with no copying.)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
482
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
483 More generally, the final argument to @code{append} may be any Lisp
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
484 object. The final argument is not copied or converted; it becomes the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
485 @sc{cdr} of the last cons cell in the new list. If the final argument
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
486 is itself a list, then its elements become in effect elements of the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487 result list. If the final element is not a list, the result is a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488 dotted list since its final @sc{cdr} is not @code{nil} as required
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489 in a true list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
491
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
492 Here is an example of using @code{append}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
494 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
495 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
496 (setq trees '(pine oak))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
497 @result{} (pine oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
498 (setq more-trees (append '(maple birch) trees))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
499 @result{} (maple birch pine oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
500 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
503 trees
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
504 @result{} (pine oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
505 more-trees
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
506 @result{} (maple birch pine oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509 (eq trees (cdr (cdr more-trees)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
512 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
513
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
514 You can see how @code{append} works by looking at a box diagram. The
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515 variable @code{trees} is set to the list @code{(pine oak)} and then the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
516 variable @code{more-trees} is set to the list @code{(maple birch pine
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
517 oak)}. However, the variable @code{trees} continues to refer to the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
518 original list:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 more-trees trees
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523 | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524 | --- --- --- --- -> --- --- --- ---
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
525 --> | | |--> | | |--> | | |--> | | |--> nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
526 --- --- --- --- --- --- --- ---
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
527 | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
528 | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 --> maple -->birch --> pine --> oak
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
531 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
532
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
533 An empty sequence contributes nothing to the value returned by
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
534 @code{append}. As a consequence of this, a final @code{nil} argument
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
535 forces a copy of the previous argument:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
536
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
537 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
538 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
539 trees
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
540 @result{} (pine oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
541 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
542 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
543 (setq wood (append trees nil))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
544 @result{} (pine oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
545 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
546 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
547 wood
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
548 @result{} (pine oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
549 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
550 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 (eq wood trees)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556 @noindent
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557 This once was the usual way to copy a list, before the function
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558 @code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560 Here we show the use of vectors and strings as arguments to @code{append}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564 (append [a b] "cd" nil)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 @result{} (a b 99 100)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569 With the help of @code{apply} (@pxref{Calling Functions}), we can append
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 all the lists in a list of lists:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574 (apply 'append '((a b c) nil (x y z) nil))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575 @result{} (a b c x y z)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
579 If no @var{sequences} are given, @code{nil} is returned:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
580
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 (append)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
586 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588 Here are some examples where the final argument is not a list:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
590 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
591 (append '(x y) 'z)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
592 @result{} (x y . z)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
593 (append '(x y) [z])
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594 @result{} (x y . [z])
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
596
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
597 @noindent
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
598 The second example shows that when the final argument is a sequence but
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
599 not a list, the sequence's elements do not become elements of the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
600 resulting list. Instead, the sequence becomes the final @sc{cdr}, like
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
601 any other non-list final argument.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
602
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
603 @defun reverse list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
604 This function creates a new list whose elements are the elements of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
605 @var{list}, but in reverse order. The original argument @var{list} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
606 @emph{not} altered.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
607
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
609 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610 (setq x '(1 2 3 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
611 @result{} (1 2 3 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
612 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
613 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
614 (reverse x)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
615 @result{} (4 3 2 1)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
616 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
617 @result{} (1 2 3 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
621
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622 @defun copy-tree tree &optional vecp
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623 This function returns a copy of the tree @code{tree}. If @var{tree} is a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624 cons cell, this makes a new cons cell with the same @sc{car} and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625 @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
626 same way.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
627
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 Normally, when @var{tree} is anything other than a cons cell,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629 @code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
630 non-@code{nil}, it copies vectors too (and operates recursively on
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631 their elements).
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634 @defun number-sequence from &optional to separation
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 This returns a list of numbers starting with @var{from} and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636 incrementing by @var{separation}, and ending at or just before
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637 @var{to}. @var{separation} can be positive or negative and defaults
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638 to 1. If @var{to} is @code{nil} or numerically equal to @var{from},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 the value is the one-element list @code{(@var{from})}. If @var{to} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 less than @var{from} with a positive @var{separation}, or greater than
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641 @var{from} with a negative @var{separation}, the value is @code{nil}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 because those arguments specify an empty sequence.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 If @var{separation} is 0 and @var{to} is neither @code{nil} nor
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645 numerically equal to @var{from}, @code{number-sequence} signals an
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646 error, since those arguments specify an infinite sequence.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648 All arguments can be integers or floating point numbers. However,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649 floating point arguments can be tricky, because floating point
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 arithmetic is inexact. For instance, depending on the machine, it may
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651 quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652 the one element list @code{(0.4)}, whereas
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
653 @code{(number-sequence 0.4 0.8 0.2)} returns a list with three
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
654 elements. The @var{n}th element of the list is computed by the exact
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
655 formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656 one wants to make sure that @var{to} is included in the list, one can
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657 pass an expression of this exact type for @var{to}. Alternatively,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 one can replace @var{to} with a slightly larger value (or a slightly
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
659 more negative value if @var{separation} is negative).
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
660
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
661 Some examples:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
662
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
663 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
664 (number-sequence 4 9)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665 @result{} (4 5 6 7 8 9)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666 (number-sequence 9 4 -1)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667 @result{} (9 8 7 6 5 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 (number-sequence 9 4 -2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 @result{} (9 7 5)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670 (number-sequence 8)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671 @result{} (8)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672 (number-sequence 8 5)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
674 (number-sequence 5 8 -1)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
675 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
676 (number-sequence 1.5 6 2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
677 @result{} (1.5 3.5 5.5)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
678 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
679 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
680
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
681 @node List Variables
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
682 @section Modifying List Variables
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
683
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
684 These functions, and one macro, provide convenient ways
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
685 to modify a list which is stored in a variable.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
686
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
687 @defmac push newelt listname
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
688 This macro provides an alternative way to write
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
689 @code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692 (setq l '(a b))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693 @result{} (a b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694 (push 'c l)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
695 @result{} (c a b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
696 l
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
697 @result{} (c a b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
698 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
699 @end defmac
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
700
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
701 Two functions modify lists that are the values of variables.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
702
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
703 @defun add-to-list symbol element &optional append compare-fn
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
704 This function sets the variable @var{symbol} by consing @var{element}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
705 onto the old value, if @var{element} is not already a member of that
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
706 value. It returns the resulting list, whether updated or not. The
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
707 value of @var{symbol} had better be a list already before the call.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
708 @code{add-to-list} uses @var{compare-fn} to compare @var{element}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709 against existing list members; if @var{compare-fn} is @code{nil}, it
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710 uses @code{equal}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712 Normally, if @var{element} is added, it is added to the front of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
713 @var{symbol}, but if the optional argument @var{append} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
714 non-@code{nil}, it is added at the end.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
715
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 is an ordinary function, like @code{set} and unlike @code{setq}. Quote
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718 the argument yourself if that is what you want.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
719 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
720
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
721 Here's a scenario showing how to use @code{add-to-list}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
722
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
723 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
724 (setq foo '(a b))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
725 @result{} (a b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
726
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
727 (add-to-list 'foo 'c) ;; @r{Add @code{c}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
728 @result{} (c a b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
729
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
730 (add-to-list 'foo 'b) ;; @r{No effect.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
731 @result{} (c a b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
732
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
733 foo ;; @r{@code{foo} was changed.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
734 @result{} (c a b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
735 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
736
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
737 An equivalent expression for @code{(add-to-list '@var{var}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
738 @var{value})} is this:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
739
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
740 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
741 (or (member @var{value} @var{var})
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
742 (setq @var{var} (cons @var{value} @var{var})))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
743 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
744
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
745 @defun add-to-ordered-list symbol element &optional order
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
746 This function sets the variable @var{symbol} by inserting
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
747 @var{element} into the old value, which must be a list, at the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
748 position specified by @var{order}. If @var{element} is already a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
749 member of the list, its position in the list is adjusted according
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
750 to @var{order}. Membership is tested using @code{eq}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
751 This function returns the resulting list, whether updated or not.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753 The @var{order} is typically a number (integer or float), and the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
754 elements of the list are sorted in non-decreasing numerical order.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
755
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
756 @var{order} may also be omitted or @code{nil}. Then the numeric order
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
757 of @var{element} stays unchanged if it already has one; otherwise,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
758 @var{element} has no numeric order. Elements without a numeric list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
759 order are placed at the end of the list, in no particular order.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
760
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
761 Any other value for @var{order} removes the numeric order of @var{element}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
762 if it already has one; otherwise, it is equivalent to @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
763
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
764 The argument @var{symbol} is not implicitly quoted;
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
765 @code{add-to-ordered-list} is an ordinary function, like @code{set}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
766 and unlike @code{setq}. Quote the argument yourself if that is what
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
767 you want.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
768
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
769 The ordering information is stored in a hash table on @var{symbol}'s
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
770 @code{list-order} property.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
771 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
772
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
773 Here's a scenario showing how to use @code{add-to-ordered-list}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
774
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
775 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
776 (setq foo '())
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
777 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
778
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
779 (add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
780 @result{} (a)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
781
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
782 (add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783 @result{} (a c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785 (add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 @result{} (a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
788 (add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
789 @result{} (a c b)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
790
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
791 (add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
792 @result{} (a c b d)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
793
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
794 (add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
795 @result{} (a c b e d)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
797 foo ;; @r{@code{foo} was changed.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
798 @result{} (a c b e d)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
799 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
800
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
801 @node Modifying Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 @section Modifying Existing List Structure
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
803 @cindex destructive list operations
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
804
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806 primitives @code{setcar} and @code{setcdr}. We call these ``destructive''
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807 operations because they change existing list structure.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 @cindex CL note---@code{rplaca} vs @code{setcar}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810 @quotation
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811 @findex rplaca
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812 @findex rplacd
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
813 @b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
814 @code{rplacd} to alter list structure; they change structure the same
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
815 way as @code{setcar} and @code{setcdr}, but the Common Lisp functions
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
816 return the cons cell while @code{setcar} and @code{setcdr} return the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
817 new @sc{car} or @sc{cdr}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
818 @end quotation
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
819
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
820 @menu
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
821 * Setcar:: Replacing an element in a list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
822 * Setcdr:: Replacing part of the list backbone.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
823 This can be used to remove or add elements.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
824 * Rearrangement:: Reordering the elements in a list; combining lists.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
825 @end menu
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
826
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827 @node Setcar
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828 @subsection Altering List Elements with @code{setcar}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
830 Changing the @sc{car} of a cons cell is done with @code{setcar}. When
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
831 used on a list, @code{setcar} replaces one element of a list with a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
832 different element.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
833
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
834 @defun setcar cons object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
835 This function stores @var{object} as the new @sc{car} of @var{cons},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
836 replacing its previous @sc{car}. In other words, it changes the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
837 @sc{car} slot of @var{cons} to refer to @var{object}. It returns the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
838 value @var{object}. For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
839
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
840 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
841 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
842 (setq x '(1 2))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
843 @result{} (1 2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
844 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
845 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
846 (setcar x 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
847 @result{} 4
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
848 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
849 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
850 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
851 @result{} (4 2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
852 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
853 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
854 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
855
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
856 When a cons cell is part of the shared structure of several lists,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
857 storing a new @sc{car} into the cons changes one element of each of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
858 these lists. Here is an example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
859
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
860 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
861 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
862 ;; @r{Create two lists that are partly shared.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
863 (setq x1 '(a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
864 @result{} (a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
865 (setq x2 (cons 'z (cdr x1)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
866 @result{} (z b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
867 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
868
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
869 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
870 ;; @r{Replace the @sc{car} of a shared link.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
871 (setcar (cdr x1) 'foo)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
872 @result{} foo
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
873 x1 ; @r{Both lists are changed.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
874 @result{} (a foo c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
875 x2
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
876 @result{} (z foo c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
877 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
878
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
879 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
880 ;; @r{Replace the @sc{car} of a link that is not shared.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
881 (setcar x1 'baz)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
882 @result{} baz
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
883 x1 ; @r{Only one list is changed.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
884 @result{} (baz foo c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
885 x2
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
886 @result{} (z foo c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
887 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
888 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
889
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
890 Here is a graphical depiction of the shared structure of the two lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
891 in the variables @code{x1} and @code{x2}, showing why replacing @code{b}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
892 changes them both:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
893
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
894 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
895 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
896 --- --- --- --- --- ---
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
897 x1---> | | |----> | | |--> | | |--> nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
898 --- --- --- --- --- ---
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
899 | --> | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
900 | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
901 --> a | --> b --> c
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
902 |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
903 --- --- |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
904 x2--> | | |--
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
905 --- ---
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
906 |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
907 |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
908 --> z
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
909 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
910 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
911
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
912 Here is an alternative form of box diagram, showing the same relationship:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
913
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
914 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
915 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
916 x1:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
917 -------------- -------------- --------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
918 | car | cdr | | car | cdr | | car | cdr |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
919 | a | o------->| b | o------->| c | nil |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
920 | | | -->| | | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
921 -------------- | -------------- --------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
922 |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
923 x2: |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
924 -------------- |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
925 | car | cdr | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
926 | z | o----
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
927 | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
928 --------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
929 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
930 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
931
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
932 @node Setcdr
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
933 @subsection Altering the CDR of a List
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
934
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
935 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
936
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
937 @defun setcdr cons object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
938 This function stores @var{object} as the new @sc{cdr} of @var{cons},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
939 replacing its previous @sc{cdr}. In other words, it changes the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
940 @sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
941 value @var{object}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
942 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
943
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
944 Here is an example of replacing the @sc{cdr} of a list with a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
945 different list. All but the first element of the list are removed in
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
946 favor of a different sequence of elements. The first element is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
947 unchanged, because it resides in the @sc{car} of the list, and is not
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
948 reached via the @sc{cdr}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
949
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
950 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
951 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
952 (setq x '(1 2 3))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
953 @result{} (1 2 3)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
954 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
955 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
956 (setcdr x '(4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
957 @result{} (4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
958 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
959 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
960 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
961 @result{} (1 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
962 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
963 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
964
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
965 You can delete elements from the middle of a list by altering the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
966 @sc{cdr}s of the cons cells in the list. For example, here we delete
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
967 the second element, @code{b}, from the list @code{(a b c)}, by changing
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
968 the @sc{cdr} of the first cons cell:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
969
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
970 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
971 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
972 (setq x1 '(a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
973 @result{} (a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
974 (setcdr x1 (cdr (cdr x1)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
975 @result{} (c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
976 x1
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
977 @result{} (a c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
978 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
979 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
980
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
981 Here is the result in box notation:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
982
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
983 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
984 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
985 --------------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
986 | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
987 -------------- | -------------- | --------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
988 | car | cdr | | | car | cdr | -->| car | cdr |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
989 | a | o----- | b | o-------->| c | nil |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
990 | | | | | | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
991 -------------- -------------- --------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
992 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
993 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
994
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
995 @noindent
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
996 The second cons cell, which previously held the element @code{b}, still
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
997 exists and its @sc{car} is still @code{b}, but it no longer forms part
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
998 of this list.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
999
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1000 It is equally easy to insert a new element by changing @sc{cdr}s:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1001
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1002 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1003 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1004 (setq x1 '(a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1005 @result{} (a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1006 (setcdr x1 (cons 'd (cdr x1)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1007 @result{} (d b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1008 x1
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1009 @result{} (a d b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1010 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1011 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1012
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1013 Here is this result in box notation:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1014
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1015 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1016 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1017 -------------- ------------- -------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1018 | car | cdr | | car | cdr | | car | cdr |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1019 | a | o | -->| b | o------->| c | nil |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1020 | | | | | | | | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1021 --------- | -- | ------------- -------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1022 | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1023 ----- --------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1024 | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1025 | --------------- |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1026 | | car | cdr | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1027 -->| d | o------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1028 | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1029 ---------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1030 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1031 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1032
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1033 @node Rearrangement
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1034 @subsection Functions that Rearrange Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1035 @cindex rearrangement of lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1036 @cindex modification of lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1037
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1038 Here are some functions that rearrange lists ``destructively'' by
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1039 modifying the @sc{cdr}s of their component cons cells. We call these
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1040 functions ``destructive'' because they chew up the original lists passed
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1041 to them as arguments, relinking their cons cells to form a new list that
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1042 is the returned value.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1043
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1044 @ifnottex
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1045 See @code{delq}, in @ref{Sets And Lists}, for another function
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1046 that modifies cons cells.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1047 @end ifnottex
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1048 @iftex
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1049 The function @code{delq} in the following section is another example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1050 of destructive list manipulation.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1051 @end iftex
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1052
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1053 @defun nconc &rest lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1054 @cindex concatenating lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1055 @cindex joining lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1056 This function returns a list containing all the elements of @var{lists}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1057 Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1058 @emph{not} copied. Instead, the last @sc{cdr} of each of the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1059 @var{lists} is changed to refer to the following list. The last of the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1060 @var{lists} is not altered. For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1061
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1062 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1063 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1064 (setq x '(1 2 3))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1065 @result{} (1 2 3)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1066 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1067 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1068 (nconc x '(4 5))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1069 @result{} (1 2 3 4 5)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1070 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1071 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1072 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1073 @result{} (1 2 3 4 5)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1074 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1075 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1076
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1077 Since the last argument of @code{nconc} is not itself modified, it is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1078 reasonable to use a constant list, such as @code{'(4 5)}, as in the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1079 above example. For the same reason, the last argument need not be a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1080 list:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1081
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1082 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1083 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1084 (setq x '(1 2 3))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1085 @result{} (1 2 3)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1086 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1087 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1088 (nconc x 'z)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1089 @result{} (1 2 3 . z)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1090 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1091 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1092 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1093 @result{} (1 2 3 . z)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1094 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1095 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1096
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1097 However, the other arguments (all but the last) must be lists.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1098
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1099 A common pitfall is to use a quoted constant list as a non-last
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1100 argument to @code{nconc}. If you do this, your program will change
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1101 each time you run it! Here is what happens:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1102
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1103 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1104 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1105 (defun add-foo (x) ; @r{We want this function to add}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1106 (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1107 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1108
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1109 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1110 (symbol-function 'add-foo)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1111 @result{} (lambda (x) (nconc (quote (foo)) x))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1112 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1113
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1114 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1115 (setq xx (add-foo '(1 2))) ; @r{It seems to work.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1116 @result{} (foo 1 2)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1117 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1118 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1119 (setq xy (add-foo '(3 4))) ; @r{What happened?}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1120 @result{} (foo 1 2 3 4)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1121 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1122 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1123 (eq xx xy)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1124 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1125 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1126
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1127 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1128 (symbol-function 'add-foo)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1129 @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1130 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1131 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1132 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1133
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1134 @defun nreverse list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1135 @cindex reversing a list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1136 This function reverses the order of the elements of @var{list}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1137 Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1138 the @sc{cdr}s in the cons cells forming the list. The cons cell that
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1139 used to be the last one in @var{list} becomes the first cons cell of the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1140 value.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1141
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1142 For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1143
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1144 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1145 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1146 (setq x '(a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1147 @result{} (a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1148 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1149 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1150 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1151 @result{} (a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1152 (nreverse x)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1153 @result{} (c b a)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1154 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1155 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1156 ;; @r{The cons cell that was first is now last.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1157 x
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1158 @result{} (a)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1159 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1160 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1161
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1162 To avoid confusion, we usually store the result of @code{nreverse}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1163 back in the same variable which held the original list:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1164
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1165 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1166 (setq x (nreverse x))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1167 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1168
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1169 Here is the @code{nreverse} of our favorite example, @code{(a b c)},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1170 presented graphically:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1171
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1172 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1173 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1174 @r{Original list head:} @r{Reversed list:}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1175 ------------- ------------- ------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1176 | car | cdr | | car | cdr | | car | cdr |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1177 | a | nil |<-- | b | o |<-- | c | o |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1178 | | | | | | | | | | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1179 ------------- | --------- | - | -------- | -
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1180 | | | |
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1181 ------------- ------------
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1182 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1183 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1184 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1185
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1186 @defun sort list predicate
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1187 @cindex stable sort
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1188 @cindex sorting lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1189 This function sorts @var{list} stably, though destructively, and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1190 returns the sorted list. It compares elements using @var{predicate}. A
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1191 stable sort is one in which elements with equal sort keys maintain their
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1192 relative order before and after the sort. Stability is important when
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1193 successive sorts are used to order elements according to different
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1194 criteria.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1195
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1196 The argument @var{predicate} must be a function that accepts two
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1197 arguments. It is called with two elements of @var{list}. To get an
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1198 increasing order sort, the @var{predicate} should return non-@code{nil} if the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1199 first element is ``less than'' the second, or @code{nil} if not.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1200
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1201 The comparison function @var{predicate} must give reliable results for
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1202 any given pair of arguments, at least within a single call to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1203 @code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1204 less than @var{b}, @var{b} must not be less than @var{a}. It must be
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1205 @dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1206 is less than @var{c}, then @var{a} must be less than @var{c}. If you
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1207 use a comparison function which does not meet these requirements, the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1208 result of @code{sort} is unpredictable.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1209
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1210 The destructive aspect of @code{sort} is that it rearranges the cons
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1211 cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1212 function would create new cons cells to store the elements in their
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1213 sorted order. If you wish to make a sorted copy without destroying the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1214 original, copy it first with @code{copy-sequence} and then sort.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1215
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1216 Sorting does not change the @sc{car}s of the cons cells in @var{list};
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1217 the cons cell that originally contained the element @code{a} in
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1218 @var{list} still has @code{a} in its @sc{car} after sorting, but it now
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1219 appears in a different position in the list due to the change of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1220 @sc{cdr}s. For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1221
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1222 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1223 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1224 (setq nums '(1 3 2 6 5 4 0))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1225 @result{} (1 3 2 6 5 4 0)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1226 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1227 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1228 (sort nums '<)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1229 @result{} (0 1 2 3 4 5 6)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1230 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1231 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1232 nums
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1233 @result{} (1 2 3 4 5 6)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1234 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1235 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1236
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1237 @noindent
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1238 @strong{Warning}: Note that the list in @code{nums} no longer contains
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1239 0; this is the same cons cell that it was before, but it is no longer
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1240 the first one in the list. Don't assume a variable that formerly held
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1241 the argument now holds the entire sorted list! Instead, save the result
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1242 of @code{sort} and use that. Most often we store the result back into
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1243 the variable that held the original list:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1244
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1245 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1246 (setq nums (sort nums '<))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1247 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1248
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1249 @xref{Sorting}, for more functions that perform sorting.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1250 See @code{documentation} in @ref{Accessing Documentation}, for a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1251 useful example of @code{sort}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1252 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1253
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1254 @node Sets And Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1255 @section Using Lists as Sets
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1256 @cindex lists as sets
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1257 @cindex sets
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1258
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1259 A list can represent an unordered mathematical set---simply consider a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1260 value an element of a set if it appears in the list, and ignore the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1261 order of the list. To form the union of two sets, use @code{append} (as
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1262 long as you don't mind having duplicate elements). You can remove
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1263 @code{equal} duplicates using @code{delete-dups}. Other useful
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1264 functions for sets include @code{memq} and @code{delq}, and their
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1265 @code{equal} versions, @code{member} and @code{delete}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1266
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1267 @cindex CL note---lack @code{union}, @code{intersection}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1268 @quotation
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1269 @b{Common Lisp note:} Common Lisp has functions @code{union} (which
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1270 avoids duplicate elements) and @code{intersection} for set operations,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1271 but GNU Emacs Lisp does not have them. You can write them in Lisp if
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1272 you wish.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1273 @end quotation
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1274
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1275 @defun memq object list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1276 @cindex membership in a list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1277 This function tests to see whether @var{object} is a member of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1278 @var{list}. If it is, @code{memq} returns a list starting with the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1279 first occurrence of @var{object}. Otherwise, it returns @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1280 The letter @samp{q} in @code{memq} says that it uses @code{eq} to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1281 compare @var{object} against the elements of the list. For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1282
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1283 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1284 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1285 (memq 'b '(a b c b a))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1286 @result{} (b c b a)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1287 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1288 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1289 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1290 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1291 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1292 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1293 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1294
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1295 @defun delq object list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1296 @cindex deleting list elements
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1297 This function destructively removes all elements @code{eq} to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1298 @var{object} from @var{list}. The letter @samp{q} in @code{delq} says
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1299 that it uses @code{eq} to compare @var{object} against the elements of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1300 the list, like @code{memq} and @code{remq}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1301 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1302
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1303 When @code{delq} deletes elements from the front of the list, it does so
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1304 simply by advancing down the list and returning a sublist that starts
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1305 after those elements:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1306
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1307 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1308 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1309 (delq 'a '(a b c)) @equiv{} (cdr '(a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1310 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1311 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1312
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1313 When an element to be deleted appears in the middle of the list,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1314 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1315
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1316 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1317 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1318 (setq sample-list '(a b c (4)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1319 @result{} (a b c (4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1320 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1321 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1322 (delq 'a sample-list)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1323 @result{} (b c (4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1324 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1325 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1326 sample-list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1327 @result{} (a b c (4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1328 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1329 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1330 (delq 'c sample-list)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1331 @result{} (a b (4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1332 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1333 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1334 sample-list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1335 @result{} (a b (4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1336 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1337 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1338
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1339 Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1340 splice out the third element, but @code{(delq 'a sample-list)} does not
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1341 splice anything---it just returns a shorter list. Don't assume that a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1342 variable which formerly held the argument @var{list} now has fewer
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1343 elements, or that it still holds the original list! Instead, save the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1344 result of @code{delq} and use that. Most often we store the result back
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1345 into the variable that held the original list:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1346
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1347 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1348 (setq flowers (delq 'rose flowers))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1349 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1350
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1351 In the following example, the @code{(4)} that @code{delq} attempts to match
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1352 and the @code{(4)} in the @code{sample-list} are not @code{eq}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1353
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1354 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1355 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1356 (delq '(4) sample-list)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1357 @result{} (a c (4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1358 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1359
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1360 If you want to delete elements that are @code{equal} to a given value,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1361 use @code{delete} (see below).
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1362 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1363
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1364 @defun remq object list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1365 This function returns a copy of @var{list}, with all elements removed
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1366 which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1367 says that it uses @code{eq} to compare @var{object} against the elements
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1368 of @code{list}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1369
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1370 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1371 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1372 (setq sample-list '(a b c a b c))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1373 @result{} (a b c a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1374 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1375 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1376 (remq 'a sample-list)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1377 @result{} (b c b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1378 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1379 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1380 sample-list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1381 @result{} (a b c a b c)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1382 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1383 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1384 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1385
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1386 @defun memql object list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1387 The function @code{memql} tests to see whether @var{object} is a member
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1388 of @var{list}, comparing members with @var{object} using @code{eql},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1389 so floating point elements are compared by value.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1390 If @var{object} is a member, @code{memql} returns a list starting with
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1391 its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1392
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1393 Compare this with @code{memq}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1394
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1395 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1396 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1397 (memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1398 @result{} (1.2 1.3)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1399 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1400 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1401 (memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1402 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1403 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1404 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1405 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1406
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1407 The following three functions are like @code{memq}, @code{delq} and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1408 @code{remq}, but use @code{equal} rather than @code{eq} to compare
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1409 elements. @xref{Equality Predicates}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1410
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1411 @defun member object list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1412 The function @code{member} tests to see whether @var{object} is a member
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1413 of @var{list}, comparing members with @var{object} using @code{equal}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1414 If @var{object} is a member, @code{member} returns a list starting with
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1415 its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1416
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1417 Compare this with @code{memq}:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1418
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1419 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1420 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1421 (member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1422 @result{} ((2))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1423 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1424 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1425 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1426 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1427 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1428 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1429 ;; @r{Two strings with the same contents are @code{equal}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1430 (member "foo" '("foo" "bar"))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1431 @result{} ("foo" "bar")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1432 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1433 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1434 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1435
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1436 @defun delete object sequence
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1437 If @code{sequence} is a list, this function destructively removes all
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1438 elements @code{equal} to @var{object} from @var{sequence}. For lists,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1439 @code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1440 uses @code{equal} to compare elements with @var{object}, like
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1441 @code{member}; when it finds an element that matches, it cuts the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1442 element out just as @code{delq} would.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1443
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1444 If @code{sequence} is a vector or string, @code{delete} returns a copy
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1445 of @code{sequence} with all elements @code{equal} to @code{object}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1446 removed.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1447
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1448 For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1449
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1450 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1451 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1452 (setq l '((2) (1) (2)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1453 (delete '(2) l)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1454 @result{} ((1))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1455 l
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1456 @result{} ((2) (1))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1457 ;; @r{If you want to change @code{l} reliably,}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1458 ;; @r{write @code{(setq l (delete elt l))}.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1459 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1460 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1461 (setq l '((2) (1) (2)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1462 (delete '(1) l)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1463 @result{} ((2) (2))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1464 l
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1465 @result{} ((2) (2))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1466 ;; @r{In this case, it makes no difference whether you set @code{l},}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1467 ;; @r{but you should do so for the sake of the other case.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1468 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1469 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1470 (delete '(2) [(2) (1) (2)])
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1471 @result{} [(1)]
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1472 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1473 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1474 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1475
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1476 @defun remove object sequence
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1477 This function is the non-destructive counterpart of @code{delete}. It
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1478 returns a copy of @code{sequence}, a list, vector, or string, with
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1479 elements @code{equal} to @code{object} removed. For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1480
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1481 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1482 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1483 (remove '(2) '((2) (1) (2)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1484 @result{} ((1))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1485 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1486 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1487 (remove '(2) [(2) (1) (2)])
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1488 @result{} [(1)]
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1489 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1490 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1491 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1492
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1493 @quotation
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1494 @b{Common Lisp note:} The functions @code{member}, @code{delete} and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1495 @code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1496 Lisp. The Common Lisp versions do not use @code{equal} to compare
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1497 elements.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1498 @end quotation
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1499
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1500 @defun member-ignore-case object list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1501 This function is like @code{member}, except that @var{object} should
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1502 be a string and that it ignores differences in letter-case and text
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1503 representation: upper-case and lower-case letters are treated as
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1504 equal, and unibyte strings are converted to multibyte prior to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1505 comparison.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1506 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1507
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1508 @defun delete-dups list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1509 This function destructively removes all @code{equal} duplicates from
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1510 @var{list}, stores the result in @var{list} and returns it. Of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1511 several @code{equal} occurrences of an element in @var{list},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1512 @code{delete-dups} keeps the first one.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1513 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1514
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1515 See also the function @code{add-to-list}, in @ref{List Variables},
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1516 for a way to add an element to a list stored in a variable and used as a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1517 set.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1518
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1519 @node Association Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1520 @section Association Lists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1521 @cindex association list
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1522 @cindex alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1523
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1524 An @dfn{association list}, or @dfn{alist} for short, records a mapping
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1525 from keys to values. It is a list of cons cells called
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1526 @dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1527 @sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key''
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1528 is not related to the term ``key sequence''; it means a value used to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1529 look up an item in a table. In this case, the table is the alist, and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1530 the alist associations are the items.}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1531
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1532 Here is an example of an alist. The key @code{pine} is associated with
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1533 the value @code{cones}; the key @code{oak} is associated with
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1534 @code{acorns}; and the key @code{maple} is associated with @code{seeds}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1535
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1536 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1537 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1538 ((pine . cones)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1539 (oak . acorns)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1540 (maple . seeds))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1541 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1542 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1543
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1544 Both the values and the keys in an alist may be any Lisp objects.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1545 For example, in the following alist, the symbol @code{a} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1546 associated with the number @code{1}, and the string @code{"b"} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1547 associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1548 the alist element:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1549
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1550 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1551 ((a . 1) ("b" 2 3))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1552 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1553
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1554 Sometimes it is better to design an alist to store the associated
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1555 value in the @sc{car} of the @sc{cdr} of the element. Here is an
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1556 example of such an alist:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1557
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1558 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1559 ((rose red) (lily white) (buttercup yellow))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1560 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1561
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1562 @noindent
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1563 Here we regard @code{red} as the value associated with @code{rose}. One
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1564 advantage of this kind of alist is that you can store other related
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1565 information---even a list of other items---in the @sc{cdr} of the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1566 @sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1567 below) to find the element containing a given value. When neither of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1568 these considerations is important, the choice is a matter of taste, as
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1569 long as you are consistent about it for any given alist.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1570
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1571 The same alist shown above could be regarded as having the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1572 associated value in the @sc{cdr} of the element; the value associated
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1573 with @code{rose} would be the list @code{(red)}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1574
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1575 Association lists are often used to record information that you might
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1576 otherwise keep on a stack, since new associations may be added easily to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1577 the front of the list. When searching an association list for an
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1578 association with a given key, the first one found is returned, if there
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1579 is more than one.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1580
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1581 In Emacs Lisp, it is @emph{not} an error if an element of an
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1582 association list is not a cons cell. The alist search functions simply
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1583 ignore such elements. Many other versions of Lisp signal errors in such
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1584 cases.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1585
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1586 Note that property lists are similar to association lists in several
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1587 respects. A property list behaves like an association list in which
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1588 each key can occur only once. @xref{Property Lists}, for a comparison
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1589 of property lists and association lists.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1590
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1591 @defun assoc key alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1592 This function returns the first association for @var{key} in
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1593 @var{alist}, comparing @var{key} against the alist elements using
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1594 @code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1595 association in @var{alist} has a @sc{car} @code{equal} to @var{key}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1596 For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1597
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1598 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1599 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1600 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1601 (assoc 'oak trees)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1602 @result{} (oak . acorns)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1603 (cdr (assoc 'oak trees))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1604 @result{} acorns
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1605 (assoc 'birch trees)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1606 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1607 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1608
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1609 Here is another example, in which the keys and values are not symbols:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1610
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1611 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1612 (setq needles-per-cluster
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1613 '((2 "Austrian Pine" "Red Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1614 (3 "Pitch Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1615 (5 "White Pine")))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1616
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1617 (cdr (assoc 3 needles-per-cluster))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1618 @result{} ("Pitch Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1619 (cdr (assoc 2 needles-per-cluster))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1620 @result{} ("Austrian Pine" "Red Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1621 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1622 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1623
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1624 The function @code{assoc-string} is much like @code{assoc} except
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1625 that it ignores certain differences between strings. @xref{Text
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1626 Comparison}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1627
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1628 @defun rassoc value alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1629 This function returns the first association with value @var{value} in
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1630 @var{alist}. It returns @code{nil} if no association in @var{alist} has
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1631 a @sc{cdr} @code{equal} to @var{value}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1632
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1633 @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1634 each @var{alist} association instead of the @sc{car}. You can think of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1635 this as ``reverse @code{assoc},'' finding the key for a given value.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1636 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1637
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1638 @defun assq key alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1639 This function is like @code{assoc} in that it returns the first
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1640 association for @var{key} in @var{alist}, but it makes the comparison
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1641 using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1642 if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1643 This function is used more often than @code{assoc}, since @code{eq} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1644 faster than @code{equal} and most alists use symbols as keys.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1645 @xref{Equality Predicates}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1646
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1647 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1648 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1649 @result{} ((pine . cones) (oak . acorns) (maple . seeds))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1650 (assq 'pine trees)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1651 @result{} (pine . cones)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1652 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1653
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1654 On the other hand, @code{assq} is not usually useful in alists where the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1655 keys may not be symbols:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1656
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1657 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1658 (setq leaves
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1659 '(("simple leaves" . oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1660 ("compound leaves" . horsechestnut)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1661
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1662 (assq "simple leaves" leaves)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1663 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1664 (assoc "simple leaves" leaves)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1665 @result{} ("simple leaves" . oak)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1666 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1667 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1668
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1669 @defun rassq value alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1670 This function returns the first association with value @var{value} in
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1671 @var{alist}. It returns @code{nil} if no association in @var{alist} has
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1672 a @sc{cdr} @code{eq} to @var{value}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1673
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1674 @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1675 each @var{alist} association instead of the @sc{car}. You can think of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1676 this as ``reverse @code{assq},'' finding the key for a given value.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1677
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1678 For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1679
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1680 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1681 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1682
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1683 (rassq 'acorns trees)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1684 @result{} (oak . acorns)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1685 (rassq 'spores trees)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1686 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1687 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1688
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1689 @code{rassq} cannot search for a value stored in the @sc{car}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1690 of the @sc{cdr} of an element:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1691
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1692 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1693 (setq colors '((rose red) (lily white) (buttercup yellow)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1694
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1695 (rassq 'white colors)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1696 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1697 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1698
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1699 In this case, the @sc{cdr} of the association @code{(lily white)} is not
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1700 the symbol @code{white}, but rather the list @code{(white)}. This
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1701 becomes clearer if the association is written in dotted pair notation:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1702
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1703 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1704 (lily white) @equiv{} (lily . (white))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1705 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1706 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1707
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1708 @defun assoc-default key alist &optional test default
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1709 This function searches @var{alist} for a match for @var{key}. For each
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1710 element of @var{alist}, it compares the element (if it is an atom) or
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1711 the element's @sc{car} (if it is a cons) against @var{key}, by calling
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1712 @var{test} with two arguments: the element or its @sc{car}, and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1713 @var{key}. The arguments are passed in that order so that you can get
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1714 useful results using @code{string-match} with an alist that contains
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1715 regular expressions (@pxref{Regexp Search}). If @var{test} is omitted
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1716 or @code{nil}, @code{equal} is used for comparison.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1717
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1718 If an alist element matches @var{key} by this criterion,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1719 then @code{assoc-default} returns a value based on this element.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1720 If the element is a cons, then the value is the element's @sc{cdr}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1721 Otherwise, the return value is @var{default}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1722
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1723 If no alist element matches @var{key}, @code{assoc-default} returns
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1724 @code{nil}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1725 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1726
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1727 @defun copy-alist alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1728 @cindex copying alists
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1729 This function returns a two-level deep copy of @var{alist}: it creates a
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1730 new copy of each association, so that you can alter the associations of
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1731 the new alist without changing the old one.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1732
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1733 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1734 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1735 (setq needles-per-cluster
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1736 '((2 . ("Austrian Pine" "Red Pine"))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1737 (3 . ("Pitch Pine"))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1738 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1739 (5 . ("White Pine"))))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1740 @result{}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1741 ((2 "Austrian Pine" "Red Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1742 (3 "Pitch Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1743 (5 "White Pine"))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1744
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1745 (setq copy (copy-alist needles-per-cluster))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1746 @result{}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1747 ((2 "Austrian Pine" "Red Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1748 (3 "Pitch Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1749 (5 "White Pine"))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1750
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1751 (eq needles-per-cluster copy)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1752 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1753 (equal needles-per-cluster copy)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1754 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1755 (eq (car needles-per-cluster) (car copy))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1756 @result{} nil
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1757 (cdr (car (cdr needles-per-cluster)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1758 @result{} ("Pitch Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1759 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1760 (eq (cdr (car (cdr needles-per-cluster)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1761 (cdr (car (cdr copy))))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1762 @result{} t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1763 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1764 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1765
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1766 This example shows how @code{copy-alist} makes it possible to change
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1767 the associations of one copy without affecting the other:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1768
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1769 @smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1770 @group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1771 (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1772 (cdr (assq 3 needles-per-cluster))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1773 @result{} ("Pitch Pine")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1774 @end group
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1775 @end smallexample
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1776 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1777
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1778 @defun assq-delete-all key alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1779 This function deletes from @var{alist} all the elements whose @sc{car}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1780 is @code{eq} to @var{key}, much as if you used @code{delq} to delete
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1781 each such element one by one. It returns the shortened alist, and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1782 often modifies the original list structure of @var{alist}. For
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1783 correct results, use the return value of @code{assq-delete-all} rather
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1784 than looking at the saved value of @var{alist}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1785
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1786 @example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1787 (setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1788 @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1789 (assq-delete-all 'foo alist)
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1790 @result{} ((bar 2) (lose 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1791 alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1792 @result{} ((foo 1) (bar 2) (lose 4))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1793 @end example
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1794 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1795
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1796 @defun rassq-delete-all value alist
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1797 This function deletes from @var{alist} all the elements whose @sc{cdr}
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1798 is @code{eq} to @var{value}. It returns the shortened alist, and
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1799 often modifies the original list structure of @var{alist}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1800 @code{rassq-delete-all} is like @code{assq-delete-all} except that it
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1801 compares the @sc{cdr} of each @var{alist} association instead of the
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1802 @sc{car}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1803 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1804
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1805 @node Rings
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1806 @section Managing a Fixed-Size Ring of Objects
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1807
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1808 @cindex ring data structure
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1809 This section describes functions for operating on rings. A
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1810 @dfn{ring} is a fixed-size data structure that supports insertion,
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1811 deletion, rotation, and modulo-indexed reference and traversal.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1812
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1813 @defun make-ring size
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1814 This returns a new ring capable of holding @var{size} objects.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1815 @var{size} should be an integer.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1816 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1817
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1818 @defun ring-p object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1819 This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1820 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1821
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1822 @defun ring-size ring
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1823 This returns the maximum capacity of the @var{ring}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1824 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1825
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1826 @defun ring-length ring
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1827 This returns the number of objects that @var{ring} currently contains.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1828 The value will never exceed that returned by @code{ring-size}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1829 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1830
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1831 @defun ring-elements ring
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1832 This returns a list of the objects in @var{ring}, in order, newest first.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1833 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1834
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1835 @defun ring-copy ring
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1836 This returns a new ring which is a copy of @var{ring}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1837 The new ring contains the same (@code{eq}) objects as @var{ring}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1838 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1839
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1840 @defun ring-empty-p ring
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1841 This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1842 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1843
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1844 The newest element in the ring always has index 0. Higher indices
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1845 correspond to older elements. Indices are computed modulo the ring
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1846 length. Index @minus{}1 corresponds to the oldest element, @minus{}2
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1847 to the next-oldest, and so forth.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1848
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1849 @defun ring-ref ring index
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1850 This returns the object in @var{ring} found at index @var{index}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1851 @var{index} may be negative or greater than the ring length. If
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1852 @var{ring} is empty, @code{ring-ref} signals an error.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1853 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1854
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1855 @defun ring-insert ring object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1856 This inserts @var{object} into @var{ring}, making it the newest
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1857 element, and returns @var{object}.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1858
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1859 If the ring is full, insertion removes the oldest element to
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1860 make room for the new element.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1861 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1862
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1863 @defun ring-remove ring &optional index
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1864 Remove an object from @var{ring}, and return that object. The
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1865 argument @var{index} specifies which item to remove; if it is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1866 @code{nil}, that means to remove the oldest item. If @var{ring} is
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1867 empty, @code{ring-remove} signals an error.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1868 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1869
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1870 @defun ring-insert-at-beginning ring object
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1871 This inserts @var{object} into @var{ring}, treating it as the oldest
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1872 element. The return value is not significant.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1873
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1874 If the ring is full, this function removes the newest element to make
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1875 room for the inserted element.
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1876 @end defun
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1877
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1878 @cindex fifo data structure
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1879 If you are careful not to exceed the ring size, you can
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1880 use the ring as a first-in-first-out queue. For example:
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1881
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1882 @lisp
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1883 (let ((fifo (make-ring 5)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1884 (mapc (lambda (obj) (ring-insert fifo obj))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1885 '(0 one "two"))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1886 (list (ring-remove fifo) t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1887 (ring-remove fifo) t
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1888 (ring-remove fifo)))
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1889 @result{} (0 t one t "two")
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1890 @end lisp
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1891
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1892 @ignore
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1893 arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
d32aa3b647f3 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1894 @end ignore