Mercurial > emacs
annotate lispref/lists.texi @ 44466:f200fce92816
ada-mode no longer supports a different
project file per buffer. This was too complex. Instead, there is now
a single active project file at any given time, and the user can switch
the active one through the Ada menu. This revision also provides
better handling of the Windows command line, and the various available
shells on that platform. ada-mode is now fully integrated with the GNU
visual debugger gvd, see http://libre.act-europe.fr.
(ada-prj-default-comp-opt): Use the new GNAT switch -gnatQ. This is only
available with GNAT 3.14.
(ada-prj-gnatfind-switches, ada-cd-command): New variable.
(ada-quote-cmd): New function.
(ada-initialize-runtime-library): Get the location of the actual
runtime the compiler will be using, including support for
cross-platform environments.
(ada-treat-cmd-string): Add support for the new variable
${full_current} add support for debug-pre-cmd and debug-post-cmd, two
commands to run just prior to running the debugger, and just after
starting it. This provide better support for cross-platform and
remote debugging.
(ada-get-absolute-dir): Remove, replace with expand-file-name.
(ada-gdb-application): New parameter executable-name.
(ada-get-ali-file-name): Better handling of separate packages.
Checkin on behalf of the ada-mode maintainer.
author | Stefan Monnier <monnier@iro.umontreal.ca> |
---|---|
date | Tue, 09 Apr 2002 18:54:20 +0000 |
parents | 5e31d7269106 |
children | 23a1cea22d13 |
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 |
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 |
38786 | 387 This function returns the last link of @var{list}. The |
31131 | 388 @code{car} of this link is the list's last element. If @var{list} is |
389 null, @code{nil} is returned. If @var{n} is non-nil the | |
390 @var{n}-th-to-last link is returned instead, or the whole @var{list} if | |
391 @var{n} is bigger than @var{list}'s length. | |
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 | |
501 (setq l '(a b)) | |
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 |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
571 The @code{append} function also allows integers as arguments. It |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
572 converts them to strings of digits, making up the decimal print |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
573 representation of the integer, and then uses the strings instead of the |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
574 original integers. @strong{Don't use this feature; we plan to eliminate |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
575 it. If you already use this feature, change your programs now!} The |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
576 proper way to convert an integer to a decimal number in this way is with |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
577 @code{format} (@pxref{Formatting Strings}) or @code{number-to-string} |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
578 (@pxref{String Conversion}). |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
579 @end defun |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
580 |
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
581 Here is an example of using @code{append}: |
6558 | 582 |
583 @example | |
584 @group | |
585 (setq trees '(pine oak)) | |
586 @result{} (pine oak) | |
587 (setq more-trees (append '(maple birch) trees)) | |
588 @result{} (maple birch pine oak) | |
589 @end group | |
590 | |
591 @group | |
592 trees | |
593 @result{} (pine oak) | |
594 more-trees | |
595 @result{} (maple birch pine oak) | |
596 @end group | |
597 @group | |
598 (eq trees (cdr (cdr more-trees))) | |
599 @result{} t | |
600 @end group | |
601 @end example | |
602 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
603 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
|
604 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
|
605 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
|
606 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
|
607 original list: |
6558 | 608 |
609 @smallexample | |
610 @group | |
611 more-trees trees | |
612 | | | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
613 | --- --- --- --- -> --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
614 --> | | |--> | | |--> | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
615 --- --- --- --- --- --- --- --- |
6558 | 616 | | | | |
617 | | | | | |
618 --> maple -->birch --> pine --> oak | |
619 @end group | |
620 @end smallexample | |
621 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
622 An empty sequence contributes nothing to the value returned by |
6558 | 623 @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
|
624 forces a copy of the previous argument: |
6558 | 625 |
626 @example | |
627 @group | |
628 trees | |
629 @result{} (pine oak) | |
630 @end group | |
631 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
632 (setq wood (append trees nil)) |
6558 | 633 @result{} (pine oak) |
634 @end group | |
635 @group | |
636 wood | |
637 @result{} (pine oak) | |
638 @end group | |
639 @group | |
640 (eq wood trees) | |
641 @result{} nil | |
642 @end group | |
643 @end example | |
644 | |
645 @noindent | |
646 This once was the usual way to copy a list, before the function | |
647 @code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. | |
648 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
649 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
|
650 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
651 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
652 @group |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
653 (append [a b] "cd" nil) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
654 @result{} (a b 99 100) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
655 @end group |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
656 @end example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
657 |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
658 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
|
659 all the lists in a list of lists: |
6558 | 660 |
661 @example | |
662 @group | |
663 (apply 'append '((a b c) nil (x y z) nil)) | |
664 @result{} (a b c x y z) | |
665 @end group | |
666 @end example | |
667 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
668 If no @var{sequences} are given, @code{nil} is returned: |
6558 | 669 |
670 @example | |
671 @group | |
672 (append) | |
673 @result{} nil | |
674 @end group | |
675 @end example | |
676 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22271
diff
changeset
|
677 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
|
678 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
679 @example |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
680 (append '(x y) 'z) |
12098 | 681 @result{} (x y . z) |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
682 (append '(x y) [z]) |
12098 | 683 @result{} (x y . [z]) |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
684 @end example |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
685 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
686 @noindent |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
687 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
|
688 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
|
689 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
|
690 any other non-list final argument. |
6558 | 691 |
692 @defun reverse list | |
693 This function creates a new list whose elements are the elements of | |
694 @var{list}, but in reverse order. The original argument @var{list} is | |
695 @emph{not} altered. | |
696 | |
697 @example | |
698 @group | |
699 (setq x '(1 2 3 4)) | |
700 @result{} (1 2 3 4) | |
701 @end group | |
702 @group | |
703 (reverse x) | |
704 @result{} (4 3 2 1) | |
705 x | |
706 @result{} (1 2 3 4) | |
707 @end group | |
708 @end example | |
709 @end defun | |
710 | |
30808 | 711 @defun remq object list |
712 This function returns a copy of @var{list}, with all elements removed | |
713 which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} | |
714 says that it uses @code{eq} to compare @var{object} against the elements | |
715 of @code{list}. | |
716 | |
717 @example | |
718 @group | |
719 (setq sample-list '(a b c a b c)) | |
720 @result{} (a b c a b c) | |
721 @end group | |
722 @group | |
723 (remq 'a sample-list) | |
724 @result{} (b c b c) | |
725 @end group | |
726 @group | |
727 sample-list | |
728 @result{} (a b c a b c) | |
729 @end group | |
730 @end example | |
731 @noindent | |
732 The function @code{delq} offers a way to perform this operation | |
733 destructively. See @ref{Sets And Lists}. | |
734 @end defun | |
735 | |
6558 | 736 @node Modifying Lists |
737 @section Modifying Existing List Structure | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
738 @cindex destructive list operations |
6558 | 739 |
740 You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the | |
22271
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
741 primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' |
71f954d59214
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22253
diff
changeset
|
742 operations because they change existing list structure. |
6558 | 743 |
744 @cindex CL note---@code{rplaca} vrs @code{setcar} | |
745 @quotation | |
746 @findex rplaca | |
747 @findex rplacd | |
748 @b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and | |
749 @code{rplacd} to alter list structure; they change structure the same | |
750 way as @code{setcar} and @code{setcdr}, but the Common Lisp functions | |
751 return the cons cell while @code{setcar} and @code{setcdr} return the | |
752 new @sc{car} or @sc{cdr}. | |
753 @end quotation | |
754 | |
755 @menu | |
756 * Setcar:: Replacing an element in a list. | |
757 * Setcdr:: Replacing part of the list backbone. | |
758 This can be used to remove or add elements. | |
759 * Rearrangement:: Reordering the elements in a list; combining lists. | |
760 @end menu | |
761 | |
762 @node Setcar | |
763 @subsection Altering List Elements with @code{setcar} | |
764 | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
765 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
|
766 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
|
767 different element. |
6558 | 768 |
769 @defun setcar cons object | |
770 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
|
771 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
|
772 @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
|
773 value @var{object}. For example: |
6558 | 774 |
775 @example | |
776 @group | |
777 (setq x '(1 2)) | |
778 @result{} (1 2) | |
779 @end group | |
780 @group | |
781 (setcar x 4) | |
782 @result{} 4 | |
783 @end group | |
784 @group | |
785 x | |
786 @result{} (4 2) | |
787 @end group | |
788 @end example | |
789 @end defun | |
790 | |
791 When a cons cell is part of the shared structure of several lists, | |
792 storing a new @sc{car} into the cons changes one element of each of | |
793 these lists. Here is an example: | |
794 | |
795 @example | |
796 @group | |
797 ;; @r{Create two lists that are partly shared.} | |
798 (setq x1 '(a b c)) | |
799 @result{} (a b c) | |
800 (setq x2 (cons 'z (cdr x1))) | |
801 @result{} (z b c) | |
802 @end group | |
803 | |
804 @group | |
805 ;; @r{Replace the @sc{car} of a shared link.} | |
806 (setcar (cdr x1) 'foo) | |
807 @result{} foo | |
808 x1 ; @r{Both lists are changed.} | |
809 @result{} (a foo c) | |
810 x2 | |
811 @result{} (z foo c) | |
812 @end group | |
813 | |
814 @group | |
815 ;; @r{Replace the @sc{car} of a link that is not shared.} | |
816 (setcar x1 'baz) | |
817 @result{} baz | |
818 x1 ; @r{Only one list is changed.} | |
819 @result{} (baz foo c) | |
820 x2 | |
821 @result{} (z foo c) | |
822 @end group | |
823 @end example | |
824 | |
825 Here is a graphical depiction of the shared structure of the two lists | |
826 in the variables @code{x1} and @code{x2}, showing why replacing @code{b} | |
827 changes them both: | |
828 | |
829 @example | |
830 @group | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
831 --- --- --- --- --- --- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
832 x1---> | | |----> | | |--> | | |--> nil |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
833 --- --- --- --- --- --- |
6558 | 834 | --> | | |
835 | | | | | |
836 --> a | --> b --> c | |
837 | | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
838 --- --- | |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
839 x2--> | | |-- |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
840 --- --- |
6558 | 841 | |
842 | | |
843 --> z | |
844 @end group | |
845 @end example | |
846 | |
847 Here is an alternative form of box diagram, showing the same relationship: | |
848 | |
849 @example | |
850 @group | |
851 x1: | |
852 -------------- -------------- -------------- | |
853 | car | cdr | | car | cdr | | car | cdr | | |
854 | a | o------->| b | o------->| c | nil | | |
855 | | | -->| | | | | | | |
856 -------------- | -------------- -------------- | |
857 | | |
858 x2: | | |
859 -------------- | | |
860 | car | cdr | | | |
861 | z | o---- | |
862 | | | | |
863 -------------- | |
864 @end group | |
865 @end example | |
866 | |
867 @node Setcdr | |
868 @subsection Altering the CDR of a List | |
869 | |
870 The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: | |
871 | |
872 @defun setcdr cons object | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
873 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
|
874 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
|
875 @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
|
876 value @var{object}. |
6558 | 877 @end defun |
878 | |
879 Here is an example of replacing the @sc{cdr} of a list with a | |
880 different list. All but the first element of the list are removed in | |
881 favor of a different sequence of elements. The first element is | |
882 unchanged, because it resides in the @sc{car} of the list, and is not | |
883 reached via the @sc{cdr}. | |
884 | |
885 @example | |
886 @group | |
887 (setq x '(1 2 3)) | |
888 @result{} (1 2 3) | |
889 @end group | |
890 @group | |
891 (setcdr x '(4)) | |
892 @result{} (4) | |
893 @end group | |
894 @group | |
895 x | |
896 @result{} (1 4) | |
897 @end group | |
898 @end example | |
899 | |
900 You can delete elements from the middle of a list by altering the | |
901 @sc{cdr}s of the cons cells in the list. For example, here we delete | |
902 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
|
903 the @sc{cdr} of the first cons cell: |
6558 | 904 |
905 @example | |
906 @group | |
907 (setq x1 '(a b c)) | |
908 @result{} (a b c) | |
909 (setcdr x1 (cdr (cdr x1))) | |
910 @result{} (c) | |
911 x1 | |
912 @result{} (a c) | |
913 @end group | |
914 @end example | |
915 | |
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
|
916 @need 4000 |
6558 | 917 Here is the result in box notation: |
918 | |
919 @example | |
920 @group | |
921 -------------------- | |
922 | | | |
923 -------------- | -------------- | -------------- | |
924 | car | cdr | | | car | cdr | -->| car | cdr | | |
925 | a | o----- | b | o-------->| c | nil | | |
926 | | | | | | | | | | |
927 -------------- -------------- -------------- | |
928 @end group | |
929 @end example | |
930 | |
931 @noindent | |
932 The second cons cell, which previously held the element @code{b}, still | |
933 exists and its @sc{car} is still @code{b}, but it no longer forms part | |
934 of this list. | |
935 | |
936 It is equally easy to insert a new element by changing @sc{cdr}s: | |
937 | |
938 @example | |
939 @group | |
940 (setq x1 '(a b c)) | |
941 @result{} (a b c) | |
942 (setcdr x1 (cons 'd (cdr x1))) | |
943 @result{} (d b c) | |
944 x1 | |
945 @result{} (a d b c) | |
946 @end group | |
947 @end example | |
948 | |
949 Here is this result in box notation: | |
950 | |
951 @smallexample | |
952 @group | |
953 -------------- ------------- ------------- | |
954 | car | cdr | | car | cdr | | car | cdr | | |
955 | a | o | -->| b | o------->| c | nil | | |
956 | | | | | | | | | | | | |
957 --------- | -- | ------------- ------------- | |
958 | | | |
959 ----- -------- | |
960 | | | |
961 | --------------- | | |
962 | | car | cdr | | | |
963 -->| d | o------ | |
964 | | | | |
965 --------------- | |
966 @end group | |
967 @end smallexample | |
968 | |
969 @node Rearrangement | |
970 @subsection Functions that Rearrange Lists | |
971 @cindex rearrangement of lists | |
972 @cindex modification of lists | |
973 | |
974 Here are some functions that rearrange lists ``destructively'' by | |
975 modifying the @sc{cdr}s of their component cons cells. We call these | |
976 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
|
977 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
|
978 is the returned value. |
6558 | 979 |
27193 | 980 @ifnottex |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
981 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
|
982 that modifies cons cells. |
27193 | 983 @end ifnottex |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
984 @iftex |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
985 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
|
986 of destructive list manipulation. |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
987 @end iftex |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
988 |
6558 | 989 @defun nconc &rest lists |
990 @cindex concatenating lists | |
991 @cindex joining lists | |
992 This function returns a list containing all the elements of @var{lists}. | |
993 Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are | |
994 @emph{not} copied. Instead, the last @sc{cdr} of each of the | |
995 @var{lists} is changed to refer to the following list. The last of the | |
996 @var{lists} is not altered. For example: | |
997 | |
998 @example | |
999 @group | |
1000 (setq x '(1 2 3)) | |
1001 @result{} (1 2 3) | |
1002 @end group | |
1003 @group | |
1004 (nconc x '(4 5)) | |
1005 @result{} (1 2 3 4 5) | |
1006 @end group | |
1007 @group | |
1008 x | |
1009 @result{} (1 2 3 4 5) | |
1010 @end group | |
1011 @end example | |
1012 | |
1013 Since the last argument of @code{nconc} is not itself modified, it is | |
1014 reasonable to use a constant list, such as @code{'(4 5)}, as in the | |
1015 above example. For the same reason, the last argument need not be a | |
1016 list: | |
1017 | |
1018 @example | |
1019 @group | |
1020 (setq x '(1 2 3)) | |
1021 @result{} (1 2 3) | |
1022 @end group | |
1023 @group | |
1024 (nconc x 'z) | |
1025 @result{} (1 2 3 . z) | |
1026 @end group | |
1027 @group | |
1028 x | |
1029 @result{} (1 2 3 . z) | |
1030 @end group | |
1031 @end example | |
1032 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1033 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
|
1034 |
6558 | 1035 A common pitfall is to use a quoted constant list as a non-last |
1036 argument to @code{nconc}. If you do this, your program will change | |
1037 each time you run it! Here is what happens: | |
1038 | |
1039 @smallexample | |
1040 @group | |
1041 (defun add-foo (x) ; @r{We want this function to add} | |
1042 (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} | |
1043 @end group | |
1044 | |
1045 @group | |
1046 (symbol-function 'add-foo) | |
1047 @result{} (lambda (x) (nconc (quote (foo)) x)) | |
1048 @end group | |
1049 | |
1050 @group | |
1051 (setq xx (add-foo '(1 2))) ; @r{It seems to work.} | |
1052 @result{} (foo 1 2) | |
1053 @end group | |
1054 @group | |
1055 (setq xy (add-foo '(3 4))) ; @r{What happened?} | |
1056 @result{} (foo 1 2 3 4) | |
1057 @end group | |
1058 @group | |
1059 (eq xx xy) | |
1060 @result{} t | |
1061 @end group | |
1062 | |
1063 @group | |
1064 (symbol-function 'add-foo) | |
1065 @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) | |
1066 @end group | |
1067 @end smallexample | |
1068 @end defun | |
1069 | |
1070 @defun nreverse list | |
1071 @cindex reversing a list | |
1072 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
|
1073 Unlike @code{reverse}, @code{nreverse} alters its argument by reversing |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1074 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
|
1075 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
|
1076 value. |
6558 | 1077 |
1078 For example: | |
1079 | |
1080 @example | |
1081 @group | |
38786 | 1082 (setq x '(a b c)) |
1083 @result{} (a b c) | |
6558 | 1084 @end group |
1085 @group | |
1086 x | |
38786 | 1087 @result{} (a b c) |
6558 | 1088 (nreverse x) |
38786 | 1089 @result{} (c b a) |
6558 | 1090 @end group |
1091 @group | |
22253
ed6b191416cf
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
1092 ;; @r{The cons cell that was first is now last.} |
6558 | 1093 x |
38786 | 1094 @result{} (a) |
6558 | 1095 @end group |
1096 @end example | |
1097 | |
1098 To avoid confusion, we usually store the result of @code{nreverse} | |
1099 back in the same variable which held the original list: | |
1100 | |
1101 @example | |
1102 (setq x (nreverse x)) | |
1103 @end example | |
1104 | |
1105 Here is the @code{nreverse} of our favorite example, @code{(a b c)}, | |
1106 presented graphically: | |
1107 | |
1108 @smallexample | |
1109 @group | |
1110 @r{Original list head:} @r{Reversed list:} | |
1111 ------------- ------------- ------------ | |
1112 | car | cdr | | car | cdr | | car | cdr | | |
1113 | a | nil |<-- | b | o |<-- | c | o | | |
1114 | | | | | | | | | | | | | | |
1115 ------------- | --------- | - | -------- | - | |
1116 | | | | | |
1117 ------------- ------------ | |
1118 @end group | |
1119 @end smallexample | |
1120 @end defun | |
1121 | |
1122 @defun sort list predicate | |
1123 @cindex stable sort | |
1124 @cindex sorting lists | |
1125 This function sorts @var{list} stably, though destructively, and | |
1126 returns the sorted list. It compares elements using @var{predicate}. A | |
1127 stable sort is one in which elements with equal sort keys maintain their | |
1128 relative order before and after the sort. Stability is important when | |
1129 successive sorts are used to order elements according to different | |
1130 criteria. | |
1131 | |
1132 The argument @var{predicate} must be a function that accepts two | |
1133 arguments. It is called with two elements of @var{list}. To get an | |
1134 increasing order sort, the @var{predicate} should return @code{t} if the | |
1135 first element is ``less than'' the second, or @code{nil} if not. | |
1136 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1137 The comparison function @var{predicate} must give reliable results for |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1138 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
|
1139 @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
|
1140 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
|
1141 @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
|
1142 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
|
1143 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
|
1144 result of @code{sort} is unpredictable. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1145 |
6558 | 1146 The destructive aspect of @code{sort} is that it rearranges the cons |
1147 cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort | |
1148 function would create new cons cells to store the elements in their | |
1149 sorted order. If you wish to make a sorted copy without destroying the | |
1150 original, copy it first with @code{copy-sequence} and then sort. | |
1151 | |
1152 Sorting does not change the @sc{car}s of the cons cells in @var{list}; | |
1153 the cons cell that originally contained the element @code{a} in | |
1154 @var{list} still has @code{a} in its @sc{car} after sorting, but it now | |
1155 appears in a different position in the list due to the change of | |
1156 @sc{cdr}s. For example: | |
1157 | |
1158 @example | |
1159 @group | |
1160 (setq nums '(1 3 2 6 5 4 0)) | |
1161 @result{} (1 3 2 6 5 4 0) | |
1162 @end group | |
1163 @group | |
1164 (sort nums '<) | |
1165 @result{} (0 1 2 3 4 5 6) | |
1166 @end group | |
1167 @group | |
1168 nums | |
1169 @result{} (1 2 3 4 5 6) | |
1170 @end group | |
1171 @end example | |
1172 | |
1173 @noindent | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
1174 @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
|
1175 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
|
1176 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
|
1177 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
|
1178 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
|
1179 the variable that held the original list: |
6558 | 1180 |
1181 @example | |
1182 (setq nums (sort nums '<)) | |
1183 @end example | |
1184 | |
1185 @xref{Sorting}, for more functions that perform sorting. | |
1186 See @code{documentation} in @ref{Accessing Documentation}, for a | |
1187 useful example of @code{sort}. | |
1188 @end defun | |
1189 | |
1190 @node Sets And Lists | |
1191 @section Using Lists as Sets | |
1192 @cindex lists as sets | |
1193 @cindex sets | |
1194 | |
1195 A list can represent an unordered mathematical set---simply consider a | |
1196 value an element of a set if it appears in the list, and ignore the | |
1197 order of the list. To form the union of two sets, use @code{append} (as | |
1198 long as you don't mind having duplicate elements). Other useful | |
1199 functions for sets include @code{memq} and @code{delq}, and their | |
1200 @code{equal} versions, @code{member} and @code{delete}. | |
1201 | |
13229 | 1202 @cindex CL note---lack @code{union}, @code{intersection} |
6558 | 1203 @quotation |
1204 @b{Common Lisp note:} Common Lisp has functions @code{union} (which | |
1205 avoids duplicate elements) and @code{intersection} for set operations, | |
1206 but GNU Emacs Lisp does not have them. You can write them in Lisp if | |
1207 you wish. | |
1208 @end quotation | |
1209 | |
1210 @defun memq object list | |
1211 @cindex membership in a list | |
1212 This function tests to see whether @var{object} is a member of | |
1213 @var{list}. If it is, @code{memq} returns a list starting with the | |
1214 first occurrence of @var{object}. Otherwise, it returns @code{nil}. | |
1215 The letter @samp{q} in @code{memq} says that it uses @code{eq} to | |
1216 compare @var{object} against the elements of the list. For example: | |
1217 | |
1218 @example | |
1219 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1220 (memq 'b '(a b c b a)) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1221 @result{} (b c b a) |
6558 | 1222 @end group |
1223 @group | |
1224 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} | |
1225 @result{} nil | |
1226 @end group | |
1227 @end example | |
1228 @end defun | |
1229 | |
39200
5e31d7269106
(Sets And Lists): Document member-ignore-case.
Eli Zaretskii <eliz@gnu.org>
parents:
38786
diff
changeset
|
1230 @defun member-ignore-case object list |
5e31d7269106
(Sets And Lists): Document member-ignore-case.
Eli Zaretskii <eliz@gnu.org>
parents:
38786
diff
changeset
|
1231 This function is like @code{member}, except that it ignores |
5e31d7269106
(Sets And Lists): Document member-ignore-case.
Eli Zaretskii <eliz@gnu.org>
parents:
38786
diff
changeset
|
1232 differences in letter-case and text representation: upper-case and |
5e31d7269106
(Sets And Lists): Document member-ignore-case.
Eli Zaretskii <eliz@gnu.org>
parents:
38786
diff
changeset
|
1233 lower-case letters are treated as equal, and unibyte strings are |
5e31d7269106
(Sets And Lists): Document member-ignore-case.
Eli Zaretskii <eliz@gnu.org>
parents:
38786
diff
changeset
|
1234 converted to multibyte prior to comparison. |
5e31d7269106
(Sets And Lists): Document member-ignore-case.
Eli Zaretskii <eliz@gnu.org>
parents:
38786
diff
changeset
|
1235 @end defun |
5e31d7269106
(Sets And Lists): Document member-ignore-case.
Eli Zaretskii <eliz@gnu.org>
parents:
38786
diff
changeset
|
1236 |
6558 | 1237 @defun delq object list |
1238 @cindex deletion of elements | |
1239 This function destructively removes all elements @code{eq} to | |
1240 @var{object} from @var{list}. The letter @samp{q} in @code{delq} says | |
1241 that it uses @code{eq} to compare @var{object} against the elements of | |
30808 | 1242 the list, like @code{memq} and @code{remq}. |
6558 | 1243 @end defun |
1244 | |
1245 When @code{delq} deletes elements from the front of the list, it does so | |
1246 simply by advancing down the list and returning a sublist that starts | |
1247 after those elements: | |
1248 | |
1249 @example | |
1250 @group | |
1251 (delq 'a '(a b c)) @equiv{} (cdr '(a b c)) | |
1252 @end group | |
1253 @end example | |
1254 | |
1255 When an element to be deleted appears in the middle of the list, | |
1256 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). | |
1257 | |
1258 @example | |
1259 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1260 (setq sample-list '(a b c (4))) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1261 @result{} (a b c (4)) |
6558 | 1262 @end group |
1263 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1264 (delq 'a sample-list) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1265 @result{} (b c (4)) |
6558 | 1266 @end group |
1267 @group | |
1268 sample-list | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1269 @result{} (a b c (4)) |
6558 | 1270 @end group |
1271 @group | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1272 (delq 'c sample-list) |
11628 | 1273 @result{} (a b (4)) |
6558 | 1274 @end group |
1275 @group | |
1276 sample-list | |
11628 | 1277 @result{} (a b (4)) |
6558 | 1278 @end group |
1279 @end example | |
1280 | |
12098 | 1281 Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to |
1282 splice out the third element, but @code{(delq 'a sample-list)} does not | |
6558 | 1283 splice anything---it just returns a shorter list. Don't assume that a |
1284 variable which formerly held the argument @var{list} now has fewer | |
1285 elements, or that it still holds the original list! Instead, save the | |
1286 result of @code{delq} and use that. Most often we store the result back | |
1287 into the variable that held the original list: | |
1288 | |
1289 @example | |
1290 (setq flowers (delq 'rose flowers)) | |
1291 @end example | |
1292 | |
1293 In the following example, the @code{(4)} that @code{delq} attempts to match | |
1294 and the @code{(4)} in the @code{sample-list} are not @code{eq}: | |
1295 | |
1296 @example | |
1297 @group | |
1298 (delq '(4) sample-list) | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1299 @result{} (a c (4)) |
6558 | 1300 @end group |
1301 @end example | |
1302 | |
1303 The following two functions are like @code{memq} and @code{delq} but use | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1304 @code{equal} rather than @code{eq} to compare elements. @xref{Equality |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
1305 Predicates}. |
6558 | 1306 |
1307 @defun member object list | |
1308 The function @code{member} tests to see whether @var{object} is a member | |
1309 of @var{list}, comparing members with @var{object} using @code{equal}. | |
1310 If @var{object} is a member, @code{member} returns a list starting with | |
1311 its first occurrence in @var{list}. Otherwise, it returns @code{nil}. | |
1312 | |
1313 Compare this with @code{memq}: | |
1314 | |
1315 @example | |
1316 @group | |
1317 (member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} | |
1318 @result{} ((2)) | |
1319 @end group | |
1320 @group | |
1321 (memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} | |
1322 @result{} nil | |
1323 @end group | |
1324 @group | |
1325 ;; @r{Two strings with the same contents are @code{equal}.} | |
1326 (member "foo" '("foo" "bar")) | |
1327 @result{} ("foo" "bar") | |
1328 @end group | |
1329 @end example | |
1330 @end defun | |
1331 | |
30808 | 1332 @defun delete object sequence |
1333 If @code{sequence} is a list, this function destructively removes all | |
1334 elements @code{equal} to @var{object} from @var{sequence}. For lists, | |
1335 @code{delete} is to @code{delq} as @code{member} is to @code{memq}: it | |
1336 uses @code{equal} to compare elements with @var{object}, like | |
1337 @code{member}; when it finds an element that matches, it removes the | |
1338 element just as @code{delq} would. | |
1339 | |
1340 If @code{sequence} is a vector or string, @code{delete} returns a copy | |
1341 of @code{sequence} with all elements @code{equal} to @code{object} | |
1342 removed. | |
1343 | |
1344 For example: | |
6558 | 1345 |
1346 @example | |
1347 @group | |
1348 (delete '(2) '((2) (1) (2))) | |
13229 | 1349 @result{} ((1)) |
6558 | 1350 @end group |
30808 | 1351 @group |
1352 (delete '(2) [(2) (1) (2)]) | |
1353 @result{} [(1)] | |
1354 @end group | |
1355 @end example | |
1356 @end defun | |
1357 | |
1358 @defun remove object sequence | |
1359 This function is the non-destructive counterpart of @code{delete}. If | |
1360 returns a copy of @code{sequence}, a list, vector, or string, with | |
1361 elements @code{equal} to @code{object} removed. For example: | |
1362 | |
1363 @example | |
1364 @group | |
1365 (remove '(2) '((2) (1) (2))) | |
1366 @result{} ((1)) | |
1367 @end group | |
1368 @group | |
1369 (remove '(2) [(2) (1) (2)]) | |
1370 @result{} [(1)] | |
1371 @end group | |
6558 | 1372 @end example |
1373 @end defun | |
1374 | |
1375 @quotation | |
30808 | 1376 @b{Common Lisp note:} The functions @code{member}, @code{delete} and |
1377 @code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common | |
1378 Lisp. The Common Lisp versions do not use @code{equal} to compare | |
1379 elements. | |
6558 | 1380 @end quotation |
1381 | |
12098 | 1382 See also the function @code{add-to-list}, in @ref{Setting Variables}, |
1383 for another way to add an element to a list stored in a variable. | |
1384 | |
6558 | 1385 @node Association Lists |
1386 @section Association Lists | |
1387 @cindex association list | |
1388 @cindex alist | |
1389 | |
1390 An @dfn{association list}, or @dfn{alist} for short, records a mapping | |
1391 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
|
1392 @dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the |
6558 | 1393 @sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' |
1394 is not related to the term ``key sequence''; it means a value used to | |
1395 look up an item in a table. In this case, the table is the alist, and | |
1396 the alist associations are the items.} | |
1397 | |
1398 Here is an example of an alist. The key @code{pine} is associated with | |
1399 the value @code{cones}; the key @code{oak} is associated with | |
1400 @code{acorns}; and the key @code{maple} is associated with @code{seeds}. | |
1401 | |
1402 @example | |
1403 @group | |
38786 | 1404 ((pine . cones) |
1405 (oak . acorns) | |
1406 (maple . seeds)) | |
6558 | 1407 @end group |
1408 @end example | |
1409 | |
1410 The associated values in an alist may be any Lisp objects; so may the | |
1411 keys. For example, in the following alist, the symbol @code{a} is | |
1412 associated with the number @code{1}, and the string @code{"b"} is | |
1413 associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of | |
1414 the alist element: | |
1415 | |
1416 @example | |
1417 ((a . 1) ("b" 2 3)) | |
1418 @end example | |
1419 | |
1420 Sometimes it is better to design an alist to store the associated | |
1421 value in the @sc{car} of the @sc{cdr} of the element. Here is an | |
38786 | 1422 example of such an alist: |
6558 | 1423 |
1424 @example | |
38786 | 1425 ((rose red) (lily white) (buttercup yellow)) |
6558 | 1426 @end example |
1427 | |
1428 @noindent | |
1429 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
|
1430 advantage of this kind of alist is that you can store other related |
6558 | 1431 information---even a list of other items---in the @sc{cdr} of the |
1432 @sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see | |
1433 below) to find the element containing a given value. When neither of | |
1434 these considerations is important, the choice is a matter of taste, as | |
1435 long as you are consistent about it for any given alist. | |
1436 | |
1437 Note that the same alist shown above could be regarded as having the | |
1438 associated value in the @sc{cdr} of the element; the value associated | |
1439 with @code{rose} would be the list @code{(red)}. | |
1440 | |
1441 Association lists are often used to record information that you might | |
1442 otherwise keep on a stack, since new associations may be added easily to | |
1443 the front of the list. When searching an association list for an | |
1444 association with a given key, the first one found is returned, if there | |
1445 is more than one. | |
1446 | |
1447 In Emacs Lisp, it is @emph{not} an error if an element of an | |
1448 association list is not a cons cell. The alist search functions simply | |
1449 ignore such elements. Many other versions of Lisp signal errors in such | |
1450 cases. | |
1451 | |
1452 Note that property lists are similar to association lists in several | |
1453 respects. A property list behaves like an association list in which | |
1454 each key can occur only once. @xref{Property Lists}, for a comparison | |
1455 of property lists and association lists. | |
1456 | |
1457 @defun assoc key alist | |
1458 This function returns the first association for @var{key} in | |
1459 @var{alist}. It compares @var{key} against the alist elements using | |
1460 @code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no | |
1461 association in @var{alist} has a @sc{car} @code{equal} to @var{key}. | |
1462 For example: | |
1463 | |
1464 @smallexample | |
1465 (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) | |
1466 @result{} ((pine . cones) (oak . acorns) (maple . seeds)) | |
1467 (assoc 'oak trees) | |
1468 @result{} (oak . acorns) | |
1469 (cdr (assoc 'oak trees)) | |
1470 @result{} acorns | |
1471 (assoc 'birch trees) | |
1472 @result{} nil | |
1473 @end smallexample | |
1474 | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1475 Here is another example, in which the keys and values are not symbols: |
6558 | 1476 |
1477 @smallexample | |
1478 (setq needles-per-cluster | |
1479 '((2 "Austrian Pine" "Red Pine") | |
1480 (3 "Pitch Pine") | |
1481 (5 "White Pine"))) | |
1482 | |
1483 (cdr (assoc 3 needles-per-cluster)) | |
1484 @result{} ("Pitch Pine") | |
1485 (cdr (assoc 2 needles-per-cluster)) | |
1486 @result{} ("Austrian Pine" "Red Pine") | |
1487 @end smallexample | |
1488 @end defun | |
1489 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1490 The functions @code{assoc-ignore-representation} and |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1491 @code{assoc-ignore-case} are much like @code{assoc} except using |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1492 @code{compare-strings} to do the comparison. @xref{Text Comparison}. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
1493 |
12067 | 1494 @defun rassoc value alist |
1495 This function returns the first association with value @var{value} in | |
1496 @var{alist}. It returns @code{nil} if no association in @var{alist} has | |
1497 a @sc{cdr} @code{equal} to @var{value}. | |
1498 | |
1499 @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of | |
1500 each @var{alist} association instead of the @sc{car}. You can think of | |
1501 this as ``reverse @code{assoc}'', finding the key for a given value. | |
1502 @end defun | |
1503 | |
6558 | 1504 @defun assq key alist |
1505 This function is like @code{assoc} in that it returns the first | |
1506 association for @var{key} in @var{alist}, but it makes the comparison | |
1507 using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} | |
1508 if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. | |
1509 This function is used more often than @code{assoc}, since @code{eq} is | |
1510 faster than @code{equal} and most alists use symbols as keys. | |
1511 @xref{Equality Predicates}. | |
1512 | |
1513 @smallexample | |
1514 (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) | |
1515 @result{} ((pine . cones) (oak . acorns) (maple . seeds)) | |
1516 (assq 'pine trees) | |
1517 @result{} (pine . cones) | |
1518 @end smallexample | |
1519 | |
1520 On the other hand, @code{assq} is not usually useful in alists where the | |
1521 keys may not be symbols: | |
1522 | |
1523 @smallexample | |
1524 (setq leaves | |
1525 '(("simple leaves" . oak) | |
1526 ("compound leaves" . horsechestnut))) | |
1527 | |
1528 (assq "simple leaves" leaves) | |
1529 @result{} nil | |
1530 (assoc "simple leaves" leaves) | |
1531 @result{} ("simple leaves" . oak) | |
1532 @end smallexample | |
1533 @end defun | |
1534 | |
1535 @defun rassq value alist | |
1536 This function returns the first association with value @var{value} in | |
1537 @var{alist}. It returns @code{nil} if no association in @var{alist} has | |
1538 a @sc{cdr} @code{eq} to @var{value}. | |
1539 | |
1540 @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of | |
1541 each @var{alist} association instead of the @sc{car}. You can think of | |
1542 this as ``reverse @code{assq}'', finding the key for a given value. | |
1543 | |
1544 For example: | |
1545 | |
1546 @smallexample | |
1547 (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) | |
1548 | |
1549 (rassq 'acorns trees) | |
1550 @result{} (oak . acorns) | |
1551 (rassq 'spores trees) | |
1552 @result{} nil | |
1553 @end smallexample | |
1554 | |
1555 Note that @code{rassq} cannot search for a value stored in the @sc{car} | |
1556 of the @sc{cdr} of an element: | |
1557 | |
1558 @smallexample | |
1559 (setq colors '((rose red) (lily white) (buttercup yellow))) | |
1560 | |
1561 (rassq 'white colors) | |
1562 @result{} nil | |
1563 @end smallexample | |
1564 | |
1565 In this case, the @sc{cdr} of the association @code{(lily white)} is not | |
1566 the symbol @code{white}, but rather the list @code{(white)}. This | |
1567 becomes clearer if the association is written in dotted pair notation: | |
1568 | |
1569 @smallexample | |
1570 (lily white) @equiv{} (lily . (white)) | |
1571 @end smallexample | |
1572 @end defun | |
1573 | |
38786 | 1574 @defun assoc-default key alist &optional test default |
22961
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1575 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
|
1576 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
|
1577 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
|
1578 @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
|
1579 @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
|
1580 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
|
1581 regular expressions (@pxref{Regexp Search}). If @var{test} is omitted |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1582 or @code{nil}, @code{equal} is used for comparison. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1583 |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1584 If an alist element matches @var{key} by this criterion, |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1585 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
|
1586 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
|
1587 Otherwise, the return value is @var{default}. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1588 |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1589 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
|
1590 @code{nil}. |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1591 @end defun |
8159553e2468
Describe assoc-default.
Richard M. Stallman <rms@gnu.org>
parents:
22274
diff
changeset
|
1592 |
6558 | 1593 @defun copy-alist alist |
1594 @cindex copying alists | |
1595 This function returns a two-level deep copy of @var{alist}: it creates a | |
1596 new copy of each association, so that you can alter the associations of | |
1597 the new alist without changing the old one. | |
1598 | |
1599 @smallexample | |
1600 @group | |
1601 (setq needles-per-cluster | |
1602 '((2 . ("Austrian Pine" "Red Pine")) | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1603 (3 . ("Pitch Pine")) |
7734 | 1604 @end group |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1605 (5 . ("White Pine")))) |
6558 | 1606 @result{} |
1607 ((2 "Austrian Pine" "Red Pine") | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1608 (3 "Pitch Pine") |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1609 (5 "White Pine")) |
6558 | 1610 |
1611 (setq copy (copy-alist needles-per-cluster)) | |
1612 @result{} | |
1613 ((2 "Austrian Pine" "Red Pine") | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1614 (3 "Pitch Pine") |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1615 (5 "White Pine")) |
6558 | 1616 |
1617 (eq needles-per-cluster copy) | |
1618 @result{} nil | |
1619 (equal needles-per-cluster copy) | |
1620 @result{} t | |
1621 (eq (car needles-per-cluster) (car copy)) | |
1622 @result{} nil | |
1623 (cdr (car (cdr needles-per-cluster))) | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1624 @result{} ("Pitch Pine") |
7734 | 1625 @group |
6558 | 1626 (eq (cdr (car (cdr needles-per-cluster))) |
1627 (cdr (car (cdr copy)))) | |
1628 @result{} t | |
1629 @end group | |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7118
diff
changeset
|
1630 @end smallexample |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1631 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1632 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
|
1633 the associations of one copy without affecting the other: |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1634 |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7118
diff
changeset
|
1635 @smallexample |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1636 @group |
11137 | 1637 (setcdr (assq 3 copy) '("Martian Vacuum Pine")) |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1638 (cdr (assq 3 needles-per-cluster)) |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1639 @result{} ("Pitch Pine") |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6558
diff
changeset
|
1640 @end group |
6558 | 1641 @end smallexample |
1642 @end defun | |
1643 | |
36872
da90c393ed4e
assq-delete-all <- assoc-delete-all
Dave Love <fx@gnu.org>
parents:
35090
diff
changeset
|
1644 @defun assq-delete-all key alist |
da90c393ed4e
assq-delete-all <- assoc-delete-all
Dave Love <fx@gnu.org>
parents:
35090
diff
changeset
|
1645 @tindex assq-delete-all |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1646 This function deletes from @var{alist} all the elements whose @sc{car} |
38786 | 1647 is @code{eq} to @var{key}. It returns @var{alist}, modified |
1648 in this way. Note that it modifies the original list structure | |
1649 of @var{alist}. | |
6558 | 1650 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1651 @example |
36900
a59daf60cef1
Change assoc-delete-all to assq-delete-all.
Gerd Moellmann <gerd@gnu.org>
parents:
36872
diff
changeset
|
1652 (assq-delete-all 'foo |
a59daf60cef1
Change assoc-delete-all to assq-delete-all.
Gerd Moellmann <gerd@gnu.org>
parents:
36872
diff
changeset
|
1653 '((foo 1) (bar 2) (foo 3) (lose 4))) |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1654 @result{} ((bar 2) (lose 4)) |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1655 @end example |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1656 @end defun |