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