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