Mercurial > emacs
annotate lispref/lists.texi @ 27114:4efa5e54e9a9
(Qunspecified_fg, Qunspecified_bg): Remove.
(syms_of_xfaces): Remove their staticpro's.
(tty_color_name): Return Lisp strings for unspecified fore- and
back-ground colors.
(Finternal_set_lisp_face_attribute): Remove the special treatment
for Qunspecified_{f,b}g.
(realize_default_face): Replace Qunspecified_{f,b}g with a Lisp
string.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Mon, 03 Jan 2000 16:52:52 +0000 |
parents | d00d63002726 |
children | f6b52258db6a |
rev | line source |
---|---|
6558 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. |
6558 | 4 @c See the file elisp.texi for copying conditions. |
5 @setfilename ../info/lists | |
6 @node Lists, Sequences Arrays Vectors, Strings and Characters, Top | |
7 @chapter Lists | |
8 @cindex list | |
9 @cindex element (of list) | |
10 | |
11 A @dfn{list} represents a sequence of zero or more elements (which may | |
12 be any Lisp objects). The important difference between lists and | |
13 vectors is that two or more lists can share part of their structure; in | |
14 addition, you can insert or delete elements in a list without copying | |
15 the whole list. | |
16 | |
17 @menu | |
18 * Cons Cells:: How lists are made out of cons cells. | |
19 * Lists as Boxes:: Graphical notation to explain lists. | |
20 * List-related Predicates:: Is this object a list? Comparing two lists. | |
21 * List Elements:: Extracting the pieces of a list. | |
22 * Building Lists:: Creating list structure. | |
23 * Modifying Lists:: Storing new pieces into an existing list. | |
24 * Sets And Lists:: A list can represent a finite mathematical set. | |
25 * Association Lists:: A list can represent a finite relation or mapping. | |
26 @end menu | |
27 | |
28 @node Cons Cells | |
29 @section Lists and Cons Cells | |
30 @cindex lists and cons cells | |
31 @cindex @code{nil} and lists | |
32 | |
33 Lists in Lisp are not a primitive data type; they are built up from | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
34 @dfn{cons cells}. A cons cell is a data object that represents an |
27068
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
35 ordered pair. That is, it has two slots, and each slot @dfn{holds}, or |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
36 @dfn{refers to}, some Lisp object. One slot is known as the @sc{car}, |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
37 and the other is known as the @sc{cdr}. (These names are traditional; |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
38 see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.'' |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
39 |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
40 We say that ``the @sc{car} of this cons cell is'' whatever object |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
41 its @sc{car} slot currently holds, and likewise for the @sc{cdr}. |
6558 | 42 |
27068
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
43 A list is a series of cons cells ``chained together,'' so that each |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
44 cell refers to the next one. There one cons cell for each element of |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
45 the list. By convention, the @sc{car}s of the cons cells hold the |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
46 elements of the list, and the @sc{cdr}s are used to chain the list: the |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
47 @sc{cdr} slot of each cons cell refers to the following cons cell. The |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
48 @sc{cdr} of the last cons cell is @code{nil}. This asymmetry between |
d00d63002726
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
49 the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the |
6558 | 50 level of cons cells, the @sc{car} and @sc{cdr} slots have the same |
51 characteristics. | |
52 | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
53 @cindex list structure |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
54 Because most cons cells are used as part of lists, the phrase |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
55 @dfn{list structure} has come to mean any structure made out of cons |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
56 cells. |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
57 |
6558 | 58 The symbol @code{nil} is considered a list as well as a symbol; it is |
59 the list with no elements. For convenience, the symbol @code{nil} is | |
60 considered to have @code{nil} as its @sc{cdr} (and also as its | |
61 @sc{car}). | |
62 | |
63 The @sc{cdr} of any nonempty list @var{l} is a list containing all the | |
64 elements of @var{l} except the first. | |
65 | |
66 @node Lists as Boxes | |
67 @comment node-name, next, previous, up | |
68 @section Lists as Linked Pairs of Boxes | |
69 @cindex box representation for lists | |
70 @cindex lists represented as boxes | |
71 @cindex cons cell as box | |
72 | |
73 A cons cell can be illustrated as a pair of boxes. The first box | |
74 represents the @sc{car} and the second box represents the @sc{cdr}. | |
75 Here is an illustration of the two-element list, @code{(tulip lily)}, | |
76 made from two cons cells: | |
77 | |
78 @example | |
79 @group | |
80 --------------- --------------- | |
81 | car | cdr | | car | cdr | | |
82 | tulip | o---------->| lily | nil | | |
83 | | | | | | | |
84 --------------- --------------- | |
85 @end group | |
86 @end example | |
87 | |
88 Each pair of boxes represents a cons cell. Each box ``refers to'', | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22961
diff
changeset
|
89 ``points to'' or ``holds'' a Lisp object. (These terms are |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
90 synonymous.) The first box, which describes the @sc{car} of the first |
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
91 cons cell, contains the symbol @code{tulip}. The arrow from the |
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
92 @sc{cdr} box of the first cons cell to the second cons cell indicates |
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
93 that the @sc{cdr} of the first cons cell is the second cons cell. |
6558 | 94 |
95 The same list can be illustrated in a different sort of box notation | |
96 like this: | |
97 | |
98 @example | |
99 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
100 --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
101 | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
102 --- --- --- --- |
6558 | 103 | | |
104 | | | |
105 --> tulip --> lily | |
106 @end group | |
107 @end example | |
108 | |
109 Here is a more complex illustration, showing the three-element list, | |
110 @code{((pine needles) oak maple)}, the first element of which is a | |
111 two-element list: | |
112 | |
113 @example | |
114 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
115 --- --- --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
116 | | |--> | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
117 --- --- --- --- --- --- |
6558 | 118 | | | |
119 | | | | |
120 | --> oak --> maple | |
121 | | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
122 | --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
123 --> | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
124 --- --- --- --- |
6558 | 125 | | |
126 | | | |
127 --> pine --> needles | |
128 @end group | |
129 @end example | |
130 | |
131 The same list represented in the first box notation looks like this: | |
132 | |
133 @example | |
134 @group | |
135 -------------- -------------- -------------- | |
136 | car | cdr | | car | cdr | | car | cdr | | |
137 | o | o------->| oak | o------->| maple | nil | | |
138 | | | | | | | | | | | |
139 -- | --------- -------------- -------------- | |
140 | | |
141 | | |
142 | -------------- ---------------- | |
143 | | car | cdr | | car | cdr | | |
144 ------>| pine | o------->| needles | nil | | |
145 | | | | | | | |
146 -------------- ---------------- | |
147 @end group | |
148 @end example | |
149 | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
150 @xref{Cons Cell Type}, for the read and print syntax of cons cells and |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
151 lists, and for more ``box and arrow'' illustrations of lists. |
6558 | 152 |
153 @node List-related Predicates | |
154 @section Predicates on Lists | |
155 | |
156 The following predicates test whether a Lisp object is an atom, is a | |
157 cons cell or is a list, or whether it is the distinguished object | |
158 @code{nil}. (Many of these predicates can be defined in terms of the | |
159 others, but they are used so often that it is worth having all of them.) | |
160 | |
161 @defun consp object | |
162 This function returns @code{t} if @var{object} is a cons cell, @code{nil} | |
163 otherwise. @code{nil} is not a cons cell, although it @emph{is} a list. | |
164 @end defun | |
165 | |
166 @defun atom object | |
167 @cindex atoms | |
168 This function returns @code{t} if @var{object} is an atom, @code{nil} | |
169 otherwise. All objects except cons cells are atoms. The symbol | |
170 @code{nil} is an atom and is also a list; it is the only Lisp object | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
171 that is both. |
6558 | 172 |
173 @example | |
174 (atom @var{object}) @equiv{} (not (consp @var{object})) | |
175 @end example | |
176 @end defun | |
177 | |
178 @defun listp object | |
179 This function returns @code{t} if @var{object} is a cons cell or | |
180 @code{nil}. Otherwise, it returns @code{nil}. | |
181 | |
182 @example | |
183 @group | |
184 (listp '(1)) | |
185 @result{} t | |
186 @end group | |
187 @group | |
188 (listp '()) | |
189 @result{} t | |
190 @end group | |
191 @end example | |
192 @end defun | |
193 | |
194 @defun nlistp object | |
195 This function is the opposite of @code{listp}: it returns @code{t} if | |
196 @var{object} is not a list. Otherwise, it returns @code{nil}. | |
197 | |
198 @example | |
199 (listp @var{object}) @equiv{} (not (nlistp @var{object})) | |
200 @end example | |
201 @end defun | |
202 | |
203 @defun null object | |
204 This function returns @code{t} if @var{object} is @code{nil}, and | |
205 returns @code{nil} otherwise. This function is identical to @code{not}, | |
206 but as a matter of clarity we use @code{null} when @var{object} is | |
207 considered a list and @code{not} when it is considered a truth value | |
208 (see @code{not} in @ref{Combining Conditions}). | |
209 | |
210 @example | |
211 @group | |
212 (null '(1)) | |
213 @result{} nil | |
214 @end group | |
215 @group | |
216 (null '()) | |
217 @result{} t | |
218 @end group | |
219 @end example | |
220 @end defun | |
221 | |
7734 | 222 @need 2000 |
6558 | 223 |
224 @node List Elements | |
225 @section Accessing Elements of Lists | |
226 @cindex list elements | |
227 | |
228 @defun car cons-cell | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22961
diff
changeset
|
229 This function returns the value referred to by the first slot of the |
6558 | 230 cons cell @var{cons-cell}. Expressed another way, this function |
231 returns the @sc{car} of @var{cons-cell}. | |
232 | |
233 As a special case, if @var{cons-cell} is @code{nil}, then @code{car} | |
234 is defined to return @code{nil}; therefore, any list is a valid argument | |
235 for @code{car}. An error is signaled if the argument is not a cons cell | |
236 or @code{nil}. | |
237 | |
238 @example | |
239 @group | |
240 (car '(a b c)) | |
241 @result{} a | |
242 @end group | |
243 @group | |
244 (car '()) | |
245 @result{} nil | |
246 @end group | |
247 @end example | |
248 @end defun | |
249 | |
250 @defun cdr cons-cell | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22961
diff
changeset
|
251 This function returns the value referred to by the second slot of |
6558 | 252 the cons cell @var{cons-cell}. Expressed another way, this function |
253 returns the @sc{cdr} of @var{cons-cell}. | |
254 | |
255 As a special case, if @var{cons-cell} is @code{nil}, then @code{cdr} | |
256 is defined to return @code{nil}; therefore, any list is a valid argument | |
257 for @code{cdr}. An error is signaled if the argument is not a cons cell | |
258 or @code{nil}. | |
259 | |
260 @example | |
261 @group | |
262 (cdr '(a b c)) | |
263 @result{} (b c) | |
264 @end group | |
265 @group | |
266 (cdr '()) | |
267 @result{} nil | |
268 @end group | |
269 @end example | |
270 @end defun | |
271 | |
272 @defun car-safe object | |
273 This function lets you take the @sc{car} of a cons cell while avoiding | |
274 errors for other data types. It returns the @sc{car} of @var{object} if | |
275 @var{object} is a cons cell, @code{nil} otherwise. This is in contrast | |
276 to @code{car}, which signals an error if @var{object} is not a list. | |
277 | |
278 @example | |
279 @group | |
280 (car-safe @var{object}) | |
281 @equiv{} | |
282 (let ((x @var{object})) | |
283 (if (consp x) | |
284 (car x) | |
285 nil)) | |
286 @end group | |
287 @end example | |
288 @end defun | |
289 | |
290 @defun cdr-safe object | |
291 This function lets you take the @sc{cdr} of a cons cell while | |
292 avoiding errors for other data types. It returns the @sc{cdr} of | |
293 @var{object} if @var{object} is a cons cell, @code{nil} otherwise. | |
294 This is in contrast to @code{cdr}, which signals an error if | |
295 @var{object} is not a list. | |
296 | |
297 @example | |
298 @group | |
299 (cdr-safe @var{object}) | |
300 @equiv{} | |
301 (let ((x @var{object})) | |
302 (if (consp x) | |
303 (cdr x) | |
304 nil)) | |
305 @end group | |
306 @end example | |
307 @end defun | |
308 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
309 @tindex pop |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
310 @defmac pop listname |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
311 This macro is a way of examining the @sc{car} of a list, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
312 and taking it off the list, all at once. It is new in Emacs 21. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
313 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
314 It operates on the list which is stored in the symbol @var{listname}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
315 It removes this element from the list by setting @var{listname} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
316 to the @sc{cdr} of its old value---but it also returns the @sc{car} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
317 of that list, which is the element being removed. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
318 |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
319 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
320 x |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
321 @result{} (a b c) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
322 (pop x) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
323 @result{} a |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
324 x |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
325 @result{} (b c) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
326 @end example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
327 @end defmac |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
328 |
6558 | 329 @defun nth n list |
330 This function returns the @var{n}th element of @var{list}. Elements | |
331 are numbered starting with zero, so the @sc{car} of @var{list} is | |
332 element number zero. If the length of @var{list} is @var{n} or less, | |
333 the value is @code{nil}. | |
334 | |
335 If @var{n} is negative, @code{nth} returns the first element of | |
336 @var{list}. | |
337 | |
338 @example | |
339 @group | |
340 (nth 2 '(1 2 3 4)) | |
341 @result{} 3 | |
342 @end group | |
343 @group | |
344 (nth 10 '(1 2 3 4)) | |
345 @result{} nil | |
346 @end group | |
347 @group | |
348 (nth -3 '(1 2 3 4)) | |
349 @result{} 1 | |
350 | |
351 (nth n x) @equiv{} (car (nthcdr n x)) | |
352 @end group | |
353 @end example | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
354 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
355 The function @code{elt} is similar, but applies to any kind of sequence. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
356 For historical reasons, it takes its arguments in the opposite order. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
357 @xref{Sequence Functions}. |
6558 | 358 @end defun |
359 | |
360 @defun nthcdr n list | |
361 This function returns the @var{n}th @sc{cdr} of @var{list}. In other | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
362 words, it skips past the first @var{n} links of @var{list} and returns |
6558 | 363 what follows. |
364 | |
365 If @var{n} is zero or negative, @code{nthcdr} returns all of | |
366 @var{list}. If the length of @var{list} is @var{n} or less, | |
367 @code{nthcdr} returns @code{nil}. | |
368 | |
369 @example | |
370 @group | |
371 (nthcdr 1 '(1 2 3 4)) | |
372 @result{} (2 3 4) | |
373 @end group | |
374 @group | |
375 (nthcdr 10 '(1 2 3 4)) | |
376 @result{} nil | |
377 @end group | |
378 @group | |
379 (nthcdr -3 '(1 2 3 4)) | |
380 @result{} (1 2 3 4) | |
381 @end group | |
382 @end example | |
383 @end defun | |
384 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
385 @defun safe-length list |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
386 @tindex safe-length |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
387 This function returns the length of @var{list}, with no risk |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
388 of either an error or an infinite loop. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
389 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
390 If @var{list} is not really a list, @code{safe-length} returns 0. If |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
391 @var{list} is circular, it returns a finite value which is at least the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
392 number of distinct elements. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
393 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
394 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
395 The most common way to compute the length of a list, when you are not |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
396 worried that it may be circular, is with @code{length}. @xref{Sequence |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
397 Functions}. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
398 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
399 @defun caar cons-cell |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
400 @tindex caar |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
401 This is the same as @code{(car (car @var{cons-cell}))}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
402 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
403 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
404 @defun cadr cons-cell |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
405 @tindex cadr |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
406 This is the same as @code{(car (cdr @var{cons-cell}))} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
407 or @code{(nth 1 @var{cons-cell})}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
408 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
409 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
410 @defun cdar cons-cell |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
411 @tindex cdar |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
412 This is the same as @code{(cdr (car @var{cons-cell}))}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
413 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
414 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
415 @defun cddr cons-cell |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
416 @tindex cddr |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
417 This is the same as @code{(cdr (cdr @var{cons-cell}))} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
418 or @code{(nthcdr 2 @var{cons-cell})}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
419 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
420 |
6558 | 421 @node Building Lists |
422 @comment node-name, next, previous, up | |
423 @section Building Cons Cells and Lists | |
424 @cindex cons cells | |
425 @cindex building lists | |
426 | |
427 Many functions build lists, as lists reside at the very heart of Lisp. | |
428 @code{cons} is the fundamental list-building function; however, it is | |
429 interesting to note that @code{list} is used more times in the source | |
430 code for Emacs than @code{cons}. | |
431 | |
432 @defun cons object1 object2 | |
433 This function is the fundamental function used to build new list | |
434 structure. It creates a new cons cell, making @var{object1} the | |
435 @sc{car}, and @var{object2} the @sc{cdr}. It then returns the new cons | |
436 cell. The arguments @var{object1} and @var{object2} may be any Lisp | |
437 objects, but most often @var{object2} is a list. | |
438 | |
439 @example | |
440 @group | |
441 (cons 1 '(2)) | |
442 @result{} (1 2) | |
443 @end group | |
444 @group | |
445 (cons 1 '()) | |
446 @result{} (1) | |
447 @end group | |
448 @group | |
449 (cons 1 2) | |
450 @result{} (1 . 2) | |
451 @end group | |
452 @end example | |
453 | |
454 @cindex consing | |
455 @code{cons} is often used to add a single element to the front of a | |
456 list. This is called @dfn{consing the element onto the list}. For | |
457 example: | |
458 | |
459 @example | |
460 (setq list (cons newelt list)) | |
461 @end example | |
462 | |
463 Note that there is no conflict between the variable named @code{list} | |
464 used in this example and the function named @code{list} described below; | |
465 any symbol can serve both purposes. | |
466 @end defun | |
467 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
468 @tindex push |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
469 @defmac push newelt listname |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
470 This macro provides an alternative way to write |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
471 @code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
472 It is new in Emacs 21. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
473 @end defmac |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
474 |
6558 | 475 @defun list &rest objects |
476 This function creates a list with @var{objects} as its elements. The | |
477 resulting list is always @code{nil}-terminated. If no @var{objects} | |
478 are given, the empty list is returned. | |
479 | |
480 @example | |
481 @group | |
482 (list 1 2 3 4 5) | |
483 @result{} (1 2 3 4 5) | |
484 @end group | |
485 @group | |
486 (list 1 2 '(3 4 5) 'foo) | |
487 @result{} (1 2 (3 4 5) foo) | |
488 @end group | |
489 @group | |
490 (list) | |
491 @result{} nil | |
492 @end group | |
493 @end example | |
494 @end defun | |
495 | |
496 @defun make-list length object | |
497 This function creates a list of length @var{length}, in which all the | |
498 elements have the identical value @var{object}. Compare | |
499 @code{make-list} with @code{make-string} (@pxref{Creating Strings}). | |
500 | |
501 @example | |
502 @group | |
503 (make-list 3 'pigs) | |
504 @result{} (pigs pigs pigs) | |
505 @end group | |
506 @group | |
507 (make-list 0 'pigs) | |
508 @result{} nil | |
509 @end group | |
510 @end example | |
511 @end defun | |
512 | |
513 @defun append &rest sequences | |
514 @cindex copying lists | |
515 This function returns a list containing all the elements of | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
516 @var{sequences}. The @var{sequences} may be lists, vectors, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
517 bool-vectors, or strings, but the last one should usually be a list. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
518 All arguments except the last one are copied, so none of the arguments |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
519 is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
520 lists with no copying.) |
6558 | 521 |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
522 More generally, the final argument to @code{append} may be any Lisp |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
523 object. The final argument is not copied or converted; it becomes the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
524 @sc{cdr} of the last cons cell in the new list. If the final argument |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
525 is itself a list, then its elements become in effect elements of the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
526 result list. If the final element is not a list, the result is a |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
527 ``dotted list'' since its final @sc{cdr} is not @code{nil} as required |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
528 in a true list. |
6558 | 529 |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
530 The @code{append} function also allows integers as arguments. It |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
531 converts them to strings of digits, making up the decimal print |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
532 representation of the integer, and then uses the strings instead of the |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
533 original integers. @strong{Don't use this feature; we plan to eliminate |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
534 it. If you already use this feature, change your programs now!} The |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
535 proper way to convert an integer to a decimal number in this way is with |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
536 @code{format} (@pxref{Formatting Strings}) or @code{number-to-string} |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
537 (@pxref{String Conversion}). |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
538 @end defun |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
539 |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
540 Here is an example of using @code{append}: |
6558 | 541 |
542 @example | |
543 @group | |
544 (setq trees '(pine oak)) | |
545 @result{} (pine oak) | |
546 (setq more-trees (append '(maple birch) trees)) | |
547 @result{} (maple birch pine oak) | |
548 @end group | |
549 | |
550 @group | |
551 trees | |
552 @result{} (pine oak) | |
553 more-trees | |
554 @result{} (maple birch pine oak) | |
555 @end group | |
556 @group | |
557 (eq trees (cdr (cdr more-trees))) | |
558 @result{} t | |
559 @end group | |
560 @end example | |
561 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
562 You can see how @code{append} works by looking at a box diagram. The |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
563 variable @code{trees} is set to the list @code{(pine oak)} and then the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
564 variable @code{more-trees} is set to the list @code{(maple birch pine |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
565 oak)}. However, the variable @code{trees} continues to refer to the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
566 original list: |
6558 | 567 |
568 @smallexample | |
569 @group | |
570 more-trees trees | |
571 | | | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
572 | --- --- --- --- -> --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
573 --> | | |--> | | |--> | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
574 --- --- --- --- --- --- --- --- |
6558 | 575 | | | | |
576 | | | | | |
577 --> maple -->birch --> pine --> oak | |
578 @end group | |
579 @end smallexample | |
580 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
581 An empty sequence contributes nothing to the value returned by |
6558 | 582 @code{append}. As a consequence of this, a final @code{nil} argument |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
583 forces a copy of the previous argument: |
6558 | 584 |
585 @example | |
586 @group | |
587 trees | |
588 @result{} (pine oak) | |
589 @end group | |
590 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
591 (setq wood (append trees nil)) |
6558 | 592 @result{} (pine oak) |
593 @end group | |
594 @group | |
595 wood | |
596 @result{} (pine oak) | |
597 @end group | |
598 @group | |
599 (eq wood trees) | |
600 @result{} nil | |
601 @end group | |
602 @end example | |
603 | |
604 @noindent | |
605 This once was the usual way to copy a list, before the function | |
606 @code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. | |
607 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
608 Here we show the use of vectors and strings as arguments to @code{append}: |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
609 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
610 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
611 @group |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
612 (append [a b] "cd" nil) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
613 @result{} (a b 99 100) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
614 @end group |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
615 @end example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
616 |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
617 With the help of @code{apply} (@pxref{Calling Functions}), we can append |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
618 all the lists in a list of lists: |
6558 | 619 |
620 @example | |
621 @group | |
622 (apply 'append '((a b c) nil (x y z) nil)) | |
623 @result{} (a b c x y z) | |
624 @end group | |
625 @end example | |
626 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
627 If no @var{sequences} are given, @code{nil} is returned: |
6558 | 628 |
629 @example | |
630 @group | |
631 (append) | |
632 @result{} nil | |
633 @end group | |
634 @end example | |
635 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
636 Here are some examples where the final argument is not a list: |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
637 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
638 @example |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
639 (append '(x y) 'z) |
12098 | 640 @result{} (x y . z) |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
641 (append '(x y) [z]) |
12098 | 642 @result{} (x y . [z]) |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
643 @end example |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
644 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
645 @noindent |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
646 The second example shows that when the final argument is a sequence but |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
647 not a list, the sequence's elements do not become elements of the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
648 resulting list. Instead, the sequence becomes the final @sc{cdr}, like |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
649 any other non-list final argument. |
6558 | 650 |
651 @defun reverse list | |
652 This function creates a new list whose elements are the elements of | |
653 @var{list}, but in reverse order. The original argument @var{list} is | |
654 @emph{not} altered. | |
655 | |
656 @example | |
657 @group | |
658 (setq x '(1 2 3 4)) | |
659 @result{} (1 2 3 4) | |
660 @end group | |
661 @group | |
662 (reverse x) | |
663 @result{} (4 3 2 1) | |
664 x | |
665 @result{} (1 2 3 4) | |
666 @end group | |
667 @end example | |
668 @end defun | |
669 | |
670 @node Modifying Lists | |
671 @section Modifying Existing List Structure | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
672 @cindex destructive list operations |
6558 | 673 |
674 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
675 primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
676 operations because they change existing list structure. |
6558 | 677 |
678 @cindex CL note---@code{rplaca} vrs @code{setcar} | |
679 @quotation | |
680 @findex rplaca | |
681 @findex rplacd | |
682 @b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and | |
683 @code{rplacd} to alter list structure; they change structure the same | |
684 way as @code{setcar} and @code{setcdr}, but the Common Lisp functions | |
685 return the cons cell while @code{setcar} and @code{setcdr} return the | |
686 new @sc{car} or @sc{cdr}. | |
687 @end quotation | |
688 | |
689 @menu | |
690 * Setcar:: Replacing an element in a list. | |
691 * Setcdr:: Replacing part of the list backbone. | |
692 This can be used to remove or add elements. | |
693 * Rearrangement:: Reordering the elements in a list; combining lists. | |
694 @end menu | |
695 | |
696 @node Setcar | |
697 @subsection Altering List Elements with @code{setcar} | |
698 | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
699 Changing the @sc{car} of a cons cell is done with @code{setcar}. When |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
700 used on a list, @code{setcar} replaces one element of a list with a |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
701 different element. |
6558 | 702 |
703 @defun setcar cons object | |
704 This function stores @var{object} as the new @sc{car} of @var{cons}, | |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
705 replacing its previous @sc{car}. In other words, it changes the |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22961
diff
changeset
|
706 @sc{car} slot of @var{cons} to refer to @var{object}. It returns the |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
707 value @var{object}. For example: |
6558 | 708 |
709 @example | |
710 @group | |
711 (setq x '(1 2)) | |
712 @result{} (1 2) | |
713 @end group | |
714 @group | |
715 (setcar x 4) | |
716 @result{} 4 | |
717 @end group | |
718 @group | |
719 x | |
720 @result{} (4 2) | |
721 @end group | |
722 @end example | |
723 @end defun | |
724 | |
725 When a cons cell is part of the shared structure of several lists, | |
726 storing a new @sc{car} into the cons changes one element of each of | |
727 these lists. Here is an example: | |
728 | |
729 @example | |
730 @group | |
731 ;; @r{Create two lists that are partly shared.} | |
732 (setq x1 '(a b c)) | |
733 @result{} (a b c) | |
734 (setq x2 (cons 'z (cdr x1))) | |
735 @result{} (z b c) | |
736 @end group | |
737 | |
738 @group | |
739 ;; @r{Replace the @sc{car} of a shared link.} | |
740 (setcar (cdr x1) 'foo) | |
741 @result{} foo | |
742 x1 ; @r{Both lists are changed.} | |
743 @result{} (a foo c) | |
744 x2 | |
745 @result{} (z foo c) | |
746 @end group | |
747 | |
748 @group | |
749 ;; @r{Replace the @sc{car} of a link that is not shared.} | |
750 (setcar x1 'baz) | |
751 @result{} baz | |
752 x1 ; @r{Only one list is changed.} | |
753 @result{} (baz foo c) | |
754 x2 | |
755 @result{} (z foo c) | |
756 @end group | |
757 @end example | |
758 | |
759 Here is a graphical depiction of the shared structure of the two lists | |
760 in the variables @code{x1} and @code{x2}, showing why replacing @code{b} | |
761 changes them both: | |
762 | |
763 @example | |
764 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
765 --- --- --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
766 x1---> | | |----> | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
767 --- --- --- --- --- --- |
6558 | 768 | --> | | |
769 | | | | | |
770 --> a | --> b --> c | |
771 | | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
772 --- --- | |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
773 x2--> | | |-- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
774 --- --- |
6558 | 775 | |
776 | | |
777 --> z | |
778 @end group | |
779 @end example | |
780 | |
781 Here is an alternative form of box diagram, showing the same relationship: | |
782 | |
783 @example | |
784 @group | |
785 x1: | |
786 -------------- -------------- -------------- | |
787 | car | cdr | | car | cdr | | car | cdr | | |
788 | a | o------->| b | o------->| c | nil | | |
789 | | | -->| | | | | | | |
790 -------------- | -------------- -------------- | |
791 | | |
792 x2: | | |
793 -------------- | | |
794 | car | cdr | | | |
795 | z | o---- | |
796 | | | | |
797 -------------- | |
798 @end group | |
799 @end example | |
800 | |
801 @node Setcdr | |
802 @subsection Altering the CDR of a List | |
803 | |
804 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: | |
805 | |
806 @defun setcdr cons object | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
807 This function stores @var{object} as the new @sc{cdr} of @var{cons}, |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
808 replacing its previous @sc{cdr}. In other words, it changes the |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22961
diff
changeset
|
809 @sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
810 value @var{object}. |
6558 | 811 @end defun |
812 | |
813 Here is an example of replacing the @sc{cdr} of a list with a | |
814 different list. All but the first element of the list are removed in | |
815 favor of a different sequence of elements. The first element is | |
816 unchanged, because it resides in the @sc{car} of the list, and is not | |
817 reached via the @sc{cdr}. | |
818 | |
819 @example | |
820 @group | |
821 (setq x '(1 2 3)) | |
822 @result{} (1 2 3) | |
823 @end group | |
824 @group | |
825 (setcdr x '(4)) | |
826 @result{} (4) | |
827 @end group | |
828 @group | |
829 x | |
830 @result{} (1 4) | |
831 @end group | |
832 @end example | |
833 | |
834 You can delete elements from the middle of a list by altering the | |
835 @sc{cdr}s of the cons cells in the list. For example, here we delete | |
836 the second element, @code{b}, from the list @code{(a b c)}, by changing | |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
837 the @sc{cdr} of the first cons cell: |
6558 | 838 |
839 @example | |
840 @group | |
841 (setq x1 '(a b c)) | |
842 @result{} (a b c) | |
843 (setcdr x1 (cdr (cdr x1))) | |
844 @result{} (c) | |
845 x1 | |
846 @result{} (a c) | |
847 @end group | |
848 @end example | |
849 | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
850 @need 4000 |
6558 | 851 Here is the result in box notation: |
852 | |
853 @example | |
854 @group | |
855 -------------------- | |
856 | | | |
857 -------------- | -------------- | -------------- | |
858 | car | cdr | | | car | cdr | -->| car | cdr | | |
859 | a | o----- | b | o-------->| c | nil | | |
860 | | | | | | | | | | |
861 -------------- -------------- -------------- | |
862 @end group | |
863 @end example | |
864 | |
865 @noindent | |
866 The second cons cell, which previously held the element @code{b}, still | |
867 exists and its @sc{car} is still @code{b}, but it no longer forms part | |
868 of this list. | |
869 | |
870 It is equally easy to insert a new element by changing @sc{cdr}s: | |
871 | |
872 @example | |
873 @group | |
874 (setq x1 '(a b c)) | |
875 @result{} (a b c) | |
876 (setcdr x1 (cons 'd (cdr x1))) | |
877 @result{} (d b c) | |
878 x1 | |
879 @result{} (a d b c) | |
880 @end group | |
881 @end example | |
882 | |
883 Here is this result in box notation: | |
884 | |
885 @smallexample | |
886 @group | |
887 -------------- ------------- ------------- | |
888 | car | cdr | | car | cdr | | car | cdr | | |
889 | a | o | -->| b | o------->| c | nil | | |
890 | | | | | | | | | | | | |
891 --------- | -- | ------------- ------------- | |
892 | | | |
893 ----- -------- | |
894 | | | |
895 | --------------- | | |
896 | | car | cdr | | | |
897 -->| d | o------ | |
898 | | | | |
899 --------------- | |
900 @end group | |
901 @end smallexample | |
902 | |
903 @node Rearrangement | |
904 @subsection Functions that Rearrange Lists | |
905 @cindex rearrangement of lists | |
906 @cindex modification of lists | |
907 | |
908 Here are some functions that rearrange lists ``destructively'' by | |
909 modifying the @sc{cdr}s of their component cons cells. We call these | |
910 functions ``destructive'' because they chew up the original lists passed | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
911 to them as arguments, relinking their cons cells to form a new list that |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
912 is the returned value. |
6558 | 913 |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
914 @ifinfo |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
915 See @code{delq}, in @ref{Sets And Lists}, for another function |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
916 that modifies cons cells. |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
917 @end ifinfo |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
918 @iftex |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
919 The function @code{delq} in the following section is another example |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
920 of destructive list manipulation. |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
921 @end iftex |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
922 |
6558 | 923 @defun nconc &rest lists |
924 @cindex concatenating lists | |
925 @cindex joining lists | |
926 This function returns a list containing all the elements of @var{lists}. | |
927 Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are | |
928 @emph{not} copied. Instead, the last @sc{cdr} of each of the | |
929 @var{lists} is changed to refer to the following list. The last of the | |
930 @var{lists} is not altered. For example: | |
931 | |
932 @example | |
933 @group | |
934 (setq x '(1 2 3)) | |
935 @result{} (1 2 3) | |
936 @end group | |
937 @group | |
938 (nconc x '(4 5)) | |
939 @result{} (1 2 3 4 5) | |
940 @end group | |
941 @group | |
942 x | |
943 @result{} (1 2 3 4 5) | |
944 @end group | |
945 @end example | |
946 | |
947 Since the last argument of @code{nconc} is not itself modified, it is | |
948 reasonable to use a constant list, such as @code{'(4 5)}, as in the | |
949 above example. For the same reason, the last argument need not be a | |
950 list: | |
951 | |
952 @example | |
953 @group | |
954 (setq x '(1 2 3)) | |
955 @result{} (1 2 3) | |
956 @end group | |
957 @group | |
958 (nconc x 'z) | |
959 @result{} (1 2 3 . z) | |
960 @end group | |
961 @group | |
962 x | |
963 @result{} (1 2 3 . z) | |
964 @end group | |
965 @end example | |
966 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
967 However, the other arguments (all but the last) must be lists. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
968 |
6558 | 969 A common pitfall is to use a quoted constant list as a non-last |
970 argument to @code{nconc}. If you do this, your program will change | |
971 each time you run it! Here is what happens: | |
972 | |
973 @smallexample | |
974 @group | |
975 (defun add-foo (x) ; @r{We want this function to add} | |
976 (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} | |
977 @end group | |
978 | |
979 @group | |
980 (symbol-function 'add-foo) | |
981 @result{} (lambda (x) (nconc (quote (foo)) x)) | |
982 @end group | |
983 | |
984 @group | |
985 (setq xx (add-foo '(1 2))) ; @r{It seems to work.} | |
986 @result{} (foo 1 2) | |
987 @end group | |
988 @group | |
989 (setq xy (add-foo '(3 4))) ; @r{What happened?} | |
990 @result{} (foo 1 2 3 4) | |
991 @end group | |
992 @group | |
993 (eq xx xy) | |
994 @result{} t | |
995 @end group | |
996 | |
997 @group | |
998 (symbol-function 'add-foo) | |
999 @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) | |
1000 @end group | |
1001 @end smallexample | |
1002 @end defun | |
1003 | |
1004 @defun nreverse list | |
1005 @cindex reversing a list | |
1006 This function reverses the order of the elements of @var{list}. | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1007 Unlike @code{reverse}, @code{nreverse} alters its argument by reversing |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1008 the @sc{cdr}s in the cons cells forming the list. The cons cell that |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1009 used to be the last one in @var{list} becomes the first cons cell of the |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1010 value. |
6558 | 1011 |
1012 For example: | |
1013 | |
1014 @example | |
1015 @group | |
1016 (setq x '(1 2 3 4)) | |
1017 @result{} (1 2 3 4) | |
1018 @end group | |
1019 @group | |
1020 x | |
1021 @result{} (1 2 3 4) | |
1022 (nreverse x) | |
1023 @result{} (4 3 2 1) | |
1024 @end group | |
1025 @group | |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1026 ;; @r{The cons cell that was first is now last.} |
6558 | 1027 x |
1028 @result{} (1) | |
1029 @end group | |
1030 @end example | |
1031 | |
1032 To avoid confusion, we usually store the result of @code{nreverse} | |
1033 back in the same variable which held the original list: | |
1034 | |
1035 @example | |
1036 (setq x (nreverse x)) | |
1037 @end example | |
1038 | |
1039 Here is the @code{nreverse} of our favorite example, @code{(a b c)}, | |
1040 presented graphically: | |
1041 | |
1042 @smallexample | |
1043 @group | |
1044 @r{Original list head:} @r{Reversed list:} | |
1045 ------------- ------------- ------------ | |
1046 | car | cdr | | car | cdr | | car | cdr | | |
1047 | a | nil |<-- | b | o |<-- | c | o | | |
1048 | | | | | | | | | | | | | | |
1049 ------------- | --------- | - | -------- | - | |
1050 | | | | | |
1051 ------------- ------------ | |
1052 @end group | |
1053 @end smallexample | |
1054 @end defun | |
1055 | |
1056 @defun sort list predicate | |
1057 @cindex stable sort | |
1058 @cindex sorting lists | |
1059 This function sorts @var{list} stably, though destructively, and | |
1060 returns the sorted list. It compares elements using @var{predicate}. A | |
1061 stable sort is one in which elements with equal sort keys maintain their | |
1062 relative order before and after the sort. Stability is important when | |
1063 successive sorts are used to order elements according to different | |
1064 criteria. | |
1065 | |
1066 The argument @var{predicate} must be a function that accepts two | |
1067 arguments. It is called with two elements of @var{list}. To get an | |
1068 increasing order sort, the @var{predicate} should return @code{t} if the | |
1069 first element is ``less than'' the second, or @code{nil} if not. | |
1070 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1071 The comparison function @var{predicate} must give reliable results for |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1072 any given pair of arguments, at least within a single call to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1073 @code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1074 less than @var{b}, @var{b} must not be less than @var{a}. It must be |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1075 @dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1076 is less than @var{c}, then @var{a} must be less than @var{c}. If you |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1077 use a comparison function which does not meet these requirements, the |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1078 result of @code{sort} is unpredictable. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1079 |
6558 | 1080 The destructive aspect of @code{sort} is that it rearranges the cons |
1081 cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort | |
1082 function would create new cons cells to store the elements in their | |
1083 sorted order. If you wish to make a sorted copy without destroying the | |
1084 original, copy it first with @code{copy-sequence} and then sort. | |
1085 | |
1086 Sorting does not change the @sc{car}s of the cons cells in @var{list}; | |
1087 the cons cell that originally contained the element @code{a} in | |
1088 @var{list} still has @code{a} in its @sc{car} after sorting, but it now | |
1089 appears in a different position in the list due to the change of | |
1090 @sc{cdr}s. For example: | |
1091 | |
1092 @example | |
1093 @group | |
1094 (setq nums '(1 3 2 6 5 4 0)) | |
1095 @result{} (1 3 2 6 5 4 0) | |
1096 @end group | |
1097 @group | |
1098 (sort nums '<) | |
1099 @result{} (0 1 2 3 4 5 6) | |
1100 @end group | |
1101 @group | |
1102 nums | |
1103 @result{} (1 2 3 4 5 6) | |
1104 @end group | |
1105 @end example | |
1106 | |
1107 @noindent | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1108 @strong{Warning}: Note that the list in @code{nums} no longer contains |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1109 0; this is the same cons cell that it was before, but it is no longer |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1110 the first one in the list. Don't assume a variable that formerly held |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1111 the argument now holds the entire sorted list! Instead, save the result |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1112 of @code{sort} and use that. Most often we store the result back into |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1113 the variable that held the original list: |
6558 | 1114 |
1115 @example | |
1116 (setq nums (sort nums '<)) | |
1117 @end example | |
1118 | |
1119 @xref{Sorting}, for more functions that perform sorting. | |
1120 See @code{documentation} in @ref{Accessing Documentation}, for a | |
1121 useful example of @code{sort}. | |
1122 @end defun | |
1123 | |
1124 @node Sets And Lists | |
1125 @section Using Lists as Sets | |
1126 @cindex lists as sets | |
1127 @cindex sets | |
1128 | |
1129 A list can represent an unordered mathematical set---simply consider a | |
1130 value an element of a set if it appears in the list, and ignore the | |
1131 order of the list. To form the union of two sets, use @code{append} (as | |
1132 long as you don't mind having duplicate elements). Other useful | |
1133 functions for sets include @code{memq} and @code{delq}, and their | |
1134 @code{equal} versions, @code{member} and @code{delete}. | |
1135 | |
13229 | 1136 @cindex CL note---lack @code{union}, @code{intersection} |
6558 | 1137 @quotation |
1138 @b{Common Lisp note:} Common Lisp has functions @code{union} (which | |
1139 avoids duplicate elements) and @code{intersection} for set operations, | |
1140 but GNU Emacs Lisp does not have them. You can write them in Lisp if | |
1141 you wish. | |
1142 @end quotation | |
1143 | |
1144 @defun memq object list | |
1145 @cindex membership in a list | |
1146 This function tests to see whether @var{object} is a member of | |
1147 @var{list}. If it is, @code{memq} returns a list starting with the | |
1148 first occurrence of @var{object}. Otherwise, it returns @code{nil}. | |
1149 The letter @samp{q} in @code{memq} says that it uses @code{eq} to | |
1150 compare @var{object} against the elements of the list. For example: | |
1151 | |
1152 @example | |
1153 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1154 (memq 'b '(a b c b a)) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1155 @result{} (b c b a) |
6558 | 1156 @end group |
1157 @group | |
1158 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} | |
1159 @result{} nil | |
1160 @end group | |
1161 @end example | |
1162 @end defun | |
1163 | |
1164 @defun delq object list | |
1165 @cindex deletion of elements | |
1166 This function destructively removes all elements @code{eq} to | |
1167 @var{object} from @var{list}. The letter @samp{q} in @code{delq} says | |
1168 that it uses @code{eq} to compare @var{object} against the elements of | |
1169 the list, like @code{memq}. | |
1170 @end defun | |
1171 | |
1172 When @code{delq} deletes elements from the front of the list, it does so | |
1173 simply by advancing down the list and returning a sublist that starts | |
1174 after those elements: | |
1175 | |
1176 @example | |
1177 @group | |
1178 (delq 'a '(a b c)) @equiv{} (cdr '(a b c)) | |
1179 @end group | |
1180 @end example | |
1181 | |
1182 When an element to be deleted appears in the middle of the list, | |
1183 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). | |
1184 | |
1185 @example | |
1186 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1187 (setq sample-list '(a b c (4))) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1188 @result{} (a b c (4)) |
6558 | 1189 @end group |
1190 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1191 (delq 'a sample-list) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1192 @result{} (b c (4)) |
6558 | 1193 @end group |
1194 @group | |
1195 sample-list | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1196 @result{} (a b c (4)) |
6558 | 1197 @end group |
1198 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1199 (delq 'c sample-list) |
11628 | 1200 @result{} (a b (4)) |
6558 | 1201 @end group |
1202 @group | |
1203 sample-list | |
11628 | 1204 @result{} (a b (4)) |
6558 | 1205 @end group |
1206 @end example | |
1207 | |
12098 | 1208 Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to |
1209 splice out the third element, but @code{(delq 'a sample-list)} does not | |
6558 | 1210 splice anything---it just returns a shorter list. Don't assume that a |
1211 variable which formerly held the argument @var{list} now has fewer | |
1212 elements, or that it still holds the original list! Instead, save the | |
1213 result of @code{delq} and use that. Most often we store the result back | |
1214 into the variable that held the original list: | |
1215 | |
1216 @example | |
1217 (setq flowers (delq 'rose flowers)) | |
1218 @end example | |
1219 | |
1220 In the following example, the @code{(4)} that @code{delq} attempts to match | |
1221 and the @code{(4)} in the @code{sample-list} are not @code{eq}: | |
1222 | |
1223 @example | |
1224 @group | |
1225 (delq '(4) sample-list) | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1226 @result{} (a c (4)) |
6558 | 1227 @end group |
1228 @end example | |
1229 | |
1230 The following two functions are like @code{memq} and @code{delq} but use | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1231 @code{equal} rather than @code{eq} to compare elements. @xref{Equality |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1232 Predicates}. |
6558 | 1233 |
1234 @defun member object list | |
1235 The function @code{member} tests to see whether @var{object} is a member | |
1236 of @var{list}, comparing members with @var{object} using @code{equal}. | |
1237 If @var{object} is a member, @code{member} returns a list starting with | |
1238 its first occurrence in @var{list}. Otherwise, it returns @code{nil}. | |
1239 | |
1240 Compare this with @code{memq}: | |
1241 | |
1242 @example | |
1243 @group | |
1244 (member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} | |
1245 @result{} ((2)) | |
1246 @end group | |
1247 @group | |
1248 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} | |
1249 @result{} nil | |
1250 @end group | |
1251 @group | |
1252 ;; @r{Two strings with the same contents are @code{equal}.} | |
1253 (member "foo" '("foo" "bar")) | |
1254 @result{} ("foo" "bar") | |
1255 @end group | |
1256 @end example | |
1257 @end defun | |
1258 | |
1259 @defun delete object list | |
1260 This function destructively removes all elements @code{equal} to | |
1261 @var{object} from @var{list}. It is to @code{delq} as @code{member} is | |
1262 to @code{memq}: it uses @code{equal} to compare elements with | |
1263 @var{object}, like @code{member}; when it finds an element that matches, | |
1264 it removes the element just as @code{delq} would. For example: | |
1265 | |
1266 @example | |
1267 @group | |
1268 (delete '(2) '((2) (1) (2))) | |
13229 | 1269 @result{} ((1)) |
6558 | 1270 @end group |
1271 @end example | |
1272 @end defun | |
1273 | |
1274 @quotation | |
1275 @b{Common Lisp note:} The functions @code{member} and @code{delete} in | |
1276 GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common | |
1277 Lisp versions do not use @code{equal} to compare elements. | |
1278 @end quotation | |
1279 | |
12098 | 1280 See also the function @code{add-to-list}, in @ref{Setting Variables}, |
1281 for another way to add an element to a list stored in a variable. | |
1282 | |
6558 | 1283 @node Association Lists |
1284 @section Association Lists | |
1285 @cindex association list | |
1286 @cindex alist | |
1287 | |
1288 An @dfn{association list}, or @dfn{alist} for short, records a mapping | |
1289 from keys to values. It is a list of cons cells called | |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1290 @dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the |
6558 | 1291 @sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' |
1292 is not related to the term ``key sequence''; it means a value used to | |
1293 look up an item in a table. In this case, the table is the alist, and | |
1294 the alist associations are the items.} | |
1295 | |
1296 Here is an example of an alist. The key @code{pine} is associated with | |
1297 the value @code{cones}; the key @code{oak} is associated with | |
1298 @code{acorns}; and the key @code{maple} is associated with @code{seeds}. | |
1299 | |
1300 @example | |
1301 @group | |
1302 '((pine . cones) | |
1303 (oak . acorns) | |
1304 (maple . seeds)) | |
1305 @end group | |
1306 @end example | |
1307 | |
1308 The associated values in an alist may be any Lisp objects; so may the | |
1309 keys. For example, in the following alist, the symbol @code{a} is | |
1310 associated with the number @code{1}, and the string @code{"b"} is | |
1311 associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of | |
1312 the alist element: | |
1313 | |
1314 @example | |
1315 ((a . 1) ("b" 2 3)) | |
1316 @end example | |
1317 | |
1318 Sometimes it is better to design an alist to store the associated | |
1319 value in the @sc{car} of the @sc{cdr} of the element. Here is an | |
1320 example: | |
1321 | |
1322 @example | |
1323 '((rose red) (lily white) (buttercup yellow)) | |
1324 @end example | |
1325 | |
1326 @noindent | |
1327 Here we regard @code{red} as the value associated with @code{rose}. One | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1328 advantage of this kind of alist is that you can store other related |
6558 | 1329 information---even a list of other items---in the @sc{cdr} of the |
1330 @sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see | |
1331 below) to find the element containing a given value. When neither of | |
1332 these considerations is important, the choice is a matter of taste, as | |
1333 long as you are consistent about it for any given alist. | |
1334 | |
1335 Note that the same alist shown above could be regarded as having the | |
1336 associated value in the @sc{cdr} of the element; the value associated | |
1337 with @code{rose} would be the list @code{(red)}. | |
1338 | |
1339 Association lists are often used to record information that you might | |
1340 otherwise keep on a stack, since new associations may be added easily to | |
1341 the front of the list. When searching an association list for an | |
1342 association with a given key, the first one found is returned, if there | |
1343 is more than one. | |
1344 | |
1345 In Emacs Lisp, it is @emph{not} an error if an element of an | |
1346 association list is not a cons cell. The alist search functions simply | |
1347 ignore such elements. Many other versions of Lisp signal errors in such | |
1348 cases. | |
1349 | |
1350 Note that property lists are similar to association lists in several | |
1351 respects. A property list behaves like an association list in which | |
1352 each key can occur only once. @xref{Property Lists}, for a comparison | |
1353 of property lists and association lists. | |
1354 | |
1355 @defun assoc key alist | |
1356 This function returns the first association for @var{key} in | |
1357 @var{alist}. It compares @var{key} against the alist elements using | |
1358 @code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no | |
1359 association in @var{alist} has a @sc{car} @code{equal} to @var{key}. | |
1360 For example: | |
1361 | |
1362 @smallexample | |
1363 (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) | |
1364 @result{} ((pine . cones) (oak . acorns) (maple . seeds)) | |
1365 (assoc 'oak trees) | |
1366 @result{} (oak . acorns) | |
1367 (cdr (assoc 'oak trees)) | |
1368 @result{} acorns | |
1369 (assoc 'birch trees) | |
1370 @result{} nil | |
1371 @end smallexample | |
1372 | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1373 Here is another example, in which the keys and values are not symbols: |
6558 | 1374 |
1375 @smallexample | |
1376 (setq needles-per-cluster | |
1377 '((2 "Austrian Pine" "Red Pine") | |
1378 (3 "Pitch Pine") | |
1379 (5 "White Pine"))) | |
1380 | |
1381 (cdr (assoc 3 needles-per-cluster)) | |
1382 @result{} ("Pitch Pine") | |
1383 (cdr (assoc 2 needles-per-cluster)) | |
1384 @result{} ("Austrian Pine" "Red Pine") | |
1385 @end smallexample | |
1386 @end defun | |
1387 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1388 The functions @code{assoc-ignore-representation} and |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1389 @code{assoc-ignore-case} are much like @code{assoc} except using |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1390 @code{compare-strings} to do the comparison. @xref{Text Comparison}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1391 |
12067 | 1392 @defun rassoc value alist |
1393 This function returns the first association with value @var{value} in | |
1394 @var{alist}. It returns @code{nil} if no association in @var{alist} has | |
1395 a @sc{cdr} @code{equal} to @var{value}. | |
1396 | |
1397 @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of | |
1398 each @var{alist} association instead of the @sc{car}. You can think of | |
1399 this as ``reverse @code{assoc}'', finding the key for a given value. | |
1400 @end defun | |
1401 | |
6558 | 1402 @defun assq key alist |
1403 This function is like @code{assoc} in that it returns the first | |
1404 association for @var{key} in @var{alist}, but it makes the comparison | |
1405 using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} | |
1406 if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. | |
1407 This function is used more often than @code{assoc}, since @code{eq} is | |
1408 faster than @code{equal} and most alists use symbols as keys. | |
1409 @xref{Equality Predicates}. | |
1410 | |
1411 @smallexample | |
1412 (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) | |
1413 @result{} ((pine . cones) (oak . acorns) (maple . seeds)) | |
1414 (assq 'pine trees) | |
1415 @result{} (pine . cones) | |
1416 @end smallexample | |
1417 | |
1418 On the other hand, @code{assq} is not usually useful in alists where the | |
1419 keys may not be symbols: | |
1420 | |
1421 @smallexample | |
1422 (setq leaves | |
1423 '(("simple leaves" . oak) | |
1424 ("compound leaves" . horsechestnut))) | |
1425 | |
1426 (assq "simple leaves" leaves) | |
1427 @result{} nil | |
1428 (assoc "simple leaves" leaves) | |
1429 @result{} ("simple leaves" . oak) | |
1430 @end smallexample | |
1431 @end defun | |
1432 | |
1433 @defun rassq value alist | |
1434 This function returns the first association with value @var{value} in | |
1435 @var{alist}. It returns @code{nil} if no association in @var{alist} has | |
1436 a @sc{cdr} @code{eq} to @var{value}. | |
1437 | |
1438 @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of | |
1439 each @var{alist} association instead of the @sc{car}. You can think of | |
1440 this as ``reverse @code{assq}'', finding the key for a given value. | |
1441 | |
1442 For example: | |
1443 | |
1444 @smallexample | |
1445 (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) | |
1446 | |
1447 (rassq 'acorns trees) | |
1448 @result{} (oak . acorns) | |
1449 (rassq 'spores trees) | |
1450 @result{} nil | |
1451 @end smallexample | |
1452 | |
1453 Note that @code{rassq} cannot search for a value stored in the @sc{car} | |
1454 of the @sc{cdr} of an element: | |
1455 | |
1456 @smallexample | |
1457 (setq colors '((rose red) (lily white) (buttercup yellow))) | |
1458 | |
1459 (rassq 'white colors) | |
1460 @result{} nil | |
1461 @end smallexample | |
1462 | |
1463 In this case, the @sc{cdr} of the association @code{(lily white)} is not | |
1464 the symbol @code{white}, but rather the list @code{(white)}. This | |
1465 becomes clearer if the association is written in dotted pair notation: | |
1466 | |
1467 @smallexample | |
1468 (lily white) @equiv{} (lily . (white)) | |
1469 @end smallexample | |
1470 @end defun | |
1471 | |
22961
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1472 @tindex assoc-default |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1473 @defun assoc-default key alist test default |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1474 This function searches @var{alist} for a match for @var{key}. For each |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1475 element of @var{alist}, it compares the element (if it is an atom) or |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1476 the element's @sc{car} (if it is a cons) against @var{key}, by calling |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1477 @var{test} with two arguments: the element or its @sc{car}, and |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1478 @var{key}. The arguments are passed in that order so that you can get |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1479 useful results using @code{string-match} with an alist that contains |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1480 regular expressions (@pxref{Regexp Search}). If @var{test} is omitted |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1481 or @code{nil}, @code{equal} is used for comparison. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1482 |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1483 If an alist element matches @var{key} by this criterion, |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1484 then @code{assoc-default} returns a value based on this element. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1485 If the element is a cons, then the value is the element's @sc{cdr}. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1486 Otherwise, the return value is @var{default}. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1487 |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1488 If no alist element matches @var{key}, @code{assoc-default} returns |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1489 @code{nil}. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1490 @end defun |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1491 |
6558 | 1492 @defun copy-alist alist |
1493 @cindex copying alists | |
1494 This function returns a two-level deep copy of @var{alist}: it creates a | |
1495 new copy of each association, so that you can alter the associations of | |
1496 the new alist without changing the old one. | |
1497 | |
1498 @smallexample | |
1499 @group | |
1500 (setq needles-per-cluster | |
1501 '((2 . ("Austrian Pine" "Red Pine")) | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1502 (3 . ("Pitch Pine")) |
7734 | 1503 @end group |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1504 (5 . ("White Pine")))) |
6558 | 1505 @result{} |
1506 ((2 "Austrian Pine" "Red Pine") | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1507 (3 "Pitch Pine") |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1508 (5 "White Pine")) |
6558 | 1509 |
1510 (setq copy (copy-alist needles-per-cluster)) | |
1511 @result{} | |
1512 ((2 "Austrian Pine" "Red Pine") | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1513 (3 "Pitch Pine") |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1514 (5 "White Pine")) |
6558 | 1515 |
1516 (eq needles-per-cluster copy) | |
1517 @result{} nil | |
1518 (equal needles-per-cluster copy) | |
1519 @result{} t | |
1520 (eq (car needles-per-cluster) (car copy)) | |
1521 @result{} nil | |
1522 (cdr (car (cdr needles-per-cluster))) | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1523 @result{} ("Pitch Pine") |
7734 | 1524 @group |
6558 | 1525 (eq (cdr (car (cdr needles-per-cluster))) |
1526 (cdr (car (cdr copy)))) | |
1527 @result{} t | |
1528 @end group | |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7118
diff
changeset
|
1529 @end smallexample |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1530 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1531 This example shows how @code{copy-alist} makes it possible to change |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1532 the associations of one copy without affecting the other: |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1533 |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7118
diff
changeset
|
1534 @smallexample |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1535 @group |
11137 | 1536 (setcdr (assq 3 copy) '("Martian Vacuum Pine")) |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1537 (cdr (assq 3 needles-per-cluster)) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1538 @result{} ("Pitch Pine") |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1539 @end group |
6558 | 1540 @end smallexample |
1541 @end defun | |
1542 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1543 @defun assoc-delete-all key alist |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1544 @tindex assoc-delete-all |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1545 This function deletes from @var{alist} all the elements whose @sc{car} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1546 is @var{key}. It returns the modified alist. |
6558 | 1547 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1548 @example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1549 (assoc-delete-all 'foo |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1550 '((foo 1) (bar 2) (foo 3) (lose 4))) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1551 @result{} ((bar 2) (lose 4)) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1552 @end example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1553 @end defun |