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