(U+9675): Use `->denotational' and `->subsumptive'.
[chise/xemacs-chise.git.1] / man / cl.texi
1 \input texinfo    @c -*-texinfo-*-
2 @setfilename ../info/cl.info
3 @settitle Common Lisp Extensions
4
5 @iftex
6 @finalout
7 @end iftex
8
9 @ifinfo
10 @dircategory XEmacs Editor
11 @direntry
12 * Common Lisp: (cl).            GNU Emacs Common Lisp emulation package.
13 @end direntry
14
15 This file documents the GNU Emacs Common Lisp emulation package.
16
17 Copyright (C) 1993 Free Software Foundation, Inc.
18
19 Permission is granted to make and distribute verbatim copies of this
20 manual provided the copyright notice and this permission notice are
21 preserved on all copies.
22
23 @ignore
24 Permission is granted to process this file through TeX and print the
25 results, provided the printed document carries copying permission notice
26 identical to this one except for the removal of this paragraph (this
27 paragraph not being relevant to the printed manual).
28
29 @end ignore
30 Permission is granted to copy and distribute modified versions of this
31 manual under the conditions for verbatim copying, provided also that the
32 section entitled ``GNU General Public License'' is included exactly as
33 in the original, and provided that the entire resulting derived work is
34 distributed under the terms of a permission notice identical to this one.
35
36 Permission is granted to copy and distribute translations of this manual
37 into another language, under the above conditions for modified versions,
38 except that the section entitled ``GNU General Public License'' may be
39 included in a translation approved by the author instead of in the
40 original English.
41 @end ifinfo
42
43 @titlepage
44 @sp 6
45 @center @titlefont{Common Lisp Extensions}
46 @sp 4
47 @center For GNU Emacs Lisp
48 @sp 1
49 @center Version 2.02
50 @sp 5
51 @center Dave Gillespie
52 @center daveg@@synaptics.com
53 @page
54
55 @vskip 0pt plus 1filll
56 Copyright @copyright{} 1993 Free Software Foundation, Inc.
57
58 Permission is granted to make and distribute verbatim copies of
59 this manual provided the copyright notice and this permission notice
60 are preserved on all copies.
61
62 @ignore
63 Permission is granted to process this file through TeX and print the
64 results, provided the printed document carries copying permission notice
65 identical to this one except for the removal of this paragraph (this
66 paragraph not being relevant to the printed manual).
67
68 @end ignore
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided also that the
71 section entitled ``GNU General Public License'' is included exactly as
72 in the original, and provided that the entire resulting derived work is
73 distributed under the terms of a permission notice identical to this one.
74
75 Permission is granted to copy and distribute translations of this manual
76 into another language, under the above conditions for modified versions,
77 except that the section entitled ``GNU General Public License'' may be
78 included in a translation approved by the author instead of in the
79 original English.
80 @end titlepage
81
82 @node Top, Overview,, (dir)
83 @chapter Common Lisp Extensions
84
85 @noindent
86 This document describes a set of Emacs Lisp facilities borrowed from
87 Common Lisp.  All the facilities are described here in detail; for
88 more discussion and examples, Guy L. Steele's @cite{Common Lisp, the
89 Language}, second edition, is the definitive book on Common Lisp.
90 @iftex
91 Chapter numbers and most section numbers of this document parallel
92 those of Steele's book.
93 @end iftex
94 While this document does not assume any prior knowledge of Common
95 Lisp, it does assume a basic familiarity with Emacs Lisp.
96
97 @menu
98 * Overview::             Installation, usage, etc.
99 * Program Structure::    Arglists, `eval-when', `defalias'
100 * Predicates::           `typep', `eql', and `equalp'
101 * Control Structure::    `setf', `when', `do', `loop', etc.
102 * Macros::               Destructuring, `define-compiler-macro'
103 * Declarations::         `proclaim', `declare', etc.
104 * Symbols::              Property lists, `gensym'
105 * Numbers::              Predicates, functions, random numbers
106 * Sequences::            Mapping, functions, searching, sorting
107 * Lists::                `cadr', `sublis', `member*', `assoc*', etc.
108 * Hash Tables::          `make-hash-table', `gethash', etc.
109 * Structures::           `defstruct'
110 * Assertions::           `check-type', `assert', `ignore-errors'.
111
112 * Efficiency Concerns::         Hints and techniques
113 * Common Lisp Compatibility::   All known differences with Steele
114 * Old CL Compatibility::        All known differences with old cl.el
115 * Porting Common Lisp::         Hints for porting Common Lisp code
116
117 * Function Index::
118 * Variable Index::
119 @end menu
120
121 @node Overview, Program Structure, Top, Top
122 @ifinfo
123 @chapter Overview
124 @end ifinfo
125 @iftex
126 @section Overview
127 @end iftex
128
129 @noindent
130 Common Lisp is a huge language, and Common Lisp systems tend to be
131 massive and extremely complex.  Emacs Lisp, by contrast, is rather
132 minimalist in the choice of Lisp features it offers the programmer.
133 As Emacs Lisp programmers have grown in number, and the applications
134 they write have grown more ambitious, it has become clear that Emacs
135 Lisp could benefit from many of the conveniences of Common Lisp.
136
137 The @dfn{CL} package adds a number of Common Lisp functions and
138 control structures to Emacs Lisp.  While not a 100% complete
139 implementation of Common Lisp, @dfn{CL} adds enough functionality
140 to make Emacs Lisp programming significantly more convenient.
141
142 Some Common Lisp features have been omitted from this package
143 for various reasons:
144
145 @itemize @bullet
146 @item
147 Some features are too complex or bulky relative to their benefit
148 to Emacs Lisp programmers.  CLOS and Common Lisp streams are fine
149 examples of this group.
150
151 @item
152 Other features cannot be implemented without modification to the
153 Emacs Lisp interpreter itself, such as multiple return values,
154 lexical scoping, case-insensitive symbols, and complex numbers.
155 The @dfn{CL} package generally makes no attempt to emulate these
156 features.
157
158 @item
159 Some features conflict with existing things in Emacs Lisp.  For
160 example, Emacs' @code{assoc} function is incompatible with the
161 Common Lisp @code{assoc}.  In such cases, this package usually
162 adds the suffix @samp{*} to the function name of the Common
163 Lisp version of the function (e.g., @code{assoc*}).
164 @end itemize
165
166 The package described here was written by Dave Gillespie,
167 @file{daveg@@synaptics.com}.  It is a total rewrite of the original
168 1986 @file{cl.el} package by Cesar Quiroz.  Most features of
169 the Quiroz package have been retained; any incompatibilities are
170 noted in the descriptions below.  Care has been taken in this
171 version to ensure that each function is defined efficiently,
172 concisely, and with minimal impact on the rest of the Emacs
173 environment.
174
175 @menu
176 * Usage::                How to use the CL package
177 * Organization::         The package's five component files
178 * Installation::         Compiling and installing CL
179 * Naming Conventions::   Notes on CL function names
180 @end menu
181
182 @node Usage, Organization, Overview, Overview
183 @section Usage
184
185 @noindent
186 Lisp code that uses features from the @dfn{CL} package should
187 include at the beginning:
188
189 @example
190 (require 'cl)
191 @end example
192
193 @noindent
194 If you want to ensure that the new (Gillespie) version of @dfn{CL}
195 is the one that is present, add an additional @code{(require 'cl-19)}
196 call:
197
198 @example
199 (require 'cl)
200 (require 'cl-19)
201 @end example
202
203 @noindent
204 The second call will fail (with ``@file{cl-19.el} not found'') if
205 the old @file{cl.el} package was in use.
206
207 It is safe to arrange to load @dfn{CL} at all times, e.g.,
208 in your @file{.emacs} file.  But it's a good idea, for portability,
209 to @code{(require 'cl)} in your code even if you do this.
210
211 @node Organization, Installation, Usage, Overview
212 @section Organization
213
214 @noindent
215 The Common Lisp package is organized into four files:
216
217 @table @file
218 @item cl.el
219 This is the ``main'' file, which contains basic functions
220 and information about the package.  This file is relatively
221 compact---about 700 lines.
222
223 @item cl-extra.el
224 This file contains the larger, more complex or unusual functions.
225 It is kept separate so that packages which only want to use Common
226 Lisp fundamentals like the @code{cadr} function won't need to pay
227 the overhead of loading the more advanced functions.
228
229 @item cl-seq.el
230 This file contains most of the advanced functions for operating
231 on sequences or lists, such as @code{delete-if} and @code{assoc*}.
232
233 @item cl-macs.el
234 This file contains the features of the packages which are macros
235 instead of functions.  Macros expand when the caller is compiled,
236 not when it is run, so the macros generally only need to be
237 present when the byte-compiler is running (or when the macros are
238 used in uncompiled code such as a @file{.emacs} file).  Most of
239 the macros of this package are isolated in @file{cl-macs.el} so
240 that they won't take up memory unless you are compiling.
241 @end table
242
243 The file @file{cl.el} includes all necessary @code{autoload}
244 commands for the functions and macros in the other three files.
245 All you have to do is @code{(require 'cl)}, and @file{cl.el}
246 will take care of pulling in the other files when they are
247 needed.
248
249 There is another file, @file{cl-compat.el}, which defines some
250 routines from the older @file{cl.el} package that are no longer
251 present in the new package.  This includes internal routines
252 like @code{setelt} and @code{zip-lists}, deprecated features
253 like @code{defkeyword}, and an emulation of the old-style
254 multiple-values feature.  @xref{Old CL Compatibility}.
255
256 @node Installation, Naming Conventions, Organization, Overview
257 @section Installation
258
259 @noindent
260 Installation of the @dfn{CL} package is simple:  Just put the
261 byte-compiled files @file{cl.elc}, @file{cl-extra.elc},
262 @file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc}
263 into a directory on your @code{load-path}.
264
265 There are no special requirements to compile this package:
266 The files do not have to be loaded before they are compiled,
267 nor do they need to be compiled in any particular order.
268
269 You may choose to put the files into your main @file{lisp/}
270 directory, replacing the original @file{cl.el} file there.  Or,
271 you could put them into a directory that comes before @file{lisp/}
272 on your @code{load-path} so that the old @file{cl.el} is
273 effectively hidden.
274
275 Also, format the @file{cl.texinfo} file and put the resulting
276 Info files in the @file{info/} directory or another suitable place.
277
278 You may instead wish to leave this package's components all in
279 their own directory, and then add this directory to your
280 @code{load-path} and (Emacs 19 only) @code{Info-directory-list}.
281 Add the directory to the front of the list so the old @dfn{CL}
282 package and its documentation are hidden.
283
284 @node Naming Conventions, , Installation, Overview
285 @section Naming Conventions
286
287 @noindent
288 Except where noted, all functions defined by this package have the
289 same names and calling conventions as their Common Lisp counterparts.
290
291 Following is a complete list of functions whose names were changed
292 from Common Lisp, usually to avoid conflicts with Emacs.  In each
293 case, a @samp{*} has been appended to the Common Lisp name to obtain
294 the Emacs name:
295
296 @example
297 defun*        defsubst*     defmacro*     function*
298 member*       assoc*        rassoc*       remove*
299 delete*       mapcar*       sort*         floor*
300 ceiling*      truncate*     round*        mod*
301 rem*          random*
302 @end example
303
304 Internal function and variable names in the package are prefixed
305 by @code{cl-}.  Here is a complete list of functions @emph{not}
306 prefixed by @code{cl-} which were not taken from Common Lisp:
307
308 @example
309 member        delete        remove        remq
310 rassoc        floatp-safe   lexical-let   lexical-let*
311 callf         callf2        letf          letf*
312 defsubst*     defalias      add-hook      eval-when-compile
313 @end example
314
315 @noindent
316 (Most of these are Emacs 19 features provided to Emacs 18 users,
317 or introduced, like @code{remq}, for reasons of symmetry
318 with similar features.)
319
320 The following simple functions and macros are defined in @file{cl.el};
321 they do not cause other components like @file{cl-extra} to be loaded.
322
323 @example
324 eql           floatp-safe   abs           endp
325 evenp         oddp          plusp         minusp
326 last          butlast       nbutlast      caar .. cddddr
327 list*         ldiff         rest          first .. tenth
328 member [1]    copy-list     subst         mapcar* [2]
329 adjoin [3]    acons         pairlis       when
330 unless        pop [4]       push [4]      pushnew [3,4]
331 incf [4]      decf [4]      proclaim      declaim
332 add-hook
333 @end example
334
335 @noindent
336 [1] This is the Emacs 19-compatible function, not @code{member*}.
337
338 @noindent
339 [2] Only for one sequence argument or two list arguments.
340
341 @noindent
342 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
343 and @code{:key} is not used.
344
345 @noindent
346 [4] Only when @var{place} is a plain variable name.
347
348 @iftex
349 @chapno=4
350 @end iftex
351
352 @node Program Structure, Predicates, Overview, Top
353 @chapter Program Structure
354
355 @noindent
356 This section describes features of the @dfn{CL} package which have to
357 do with programs as a whole: advanced argument lists for functions,
358 and the @code{eval-when} construct.
359
360 @menu
361 * Argument Lists::       `&key', `&aux', `defun*', `defmacro*'.
362 * Time of Evaluation::   The `eval-when' construct.
363 * Function Aliases::     The `defalias' function.
364 @end menu
365
366 @iftex
367 @secno=1
368 @end iftex
369
370 @node Argument Lists, Time of Evaluation, Program Structure, Program Structure
371 @section Argument Lists
372
373 @noindent
374 Emacs Lisp's notation for argument lists of functions is a subset of
375 the Common Lisp notation.  As well as the familiar @code{&optional}
376 and @code{&rest} markers, Common Lisp allows you to specify default
377 values for optional arguments, and it provides the additional markers
378 @code{&key} and @code{&aux}.
379
380 Since argument parsing is built-in to Emacs, there is no way for
381 this package to implement Common Lisp argument lists seamlessly.
382 Instead, this package defines alternates for several Lisp forms
383 which you must use if you need Common Lisp argument lists.
384
385 @defspec defun* name arglist body...
386 This form is identical to the regular @code{defun} form, except
387 that @var{arglist} is allowed to be a full Common Lisp argument
388 list.  Also, the function body is enclosed in an implicit block
389 called @var{name}; @pxref{Blocks and Exits}.
390 @end defspec
391
392 @defspec defsubst* name arglist body...
393 This is just like @code{defun*}, except that the function that
394 is defined is automatically proclaimed @code{inline}, i.e.,
395 calls to it may be expanded into in-line code by the byte compiler.
396 This is analogous to the @code{defsubst} form in Emacs 19;
397 @code{defsubst*} uses a different method (compiler macros) which
398 works in all version of Emacs, and also generates somewhat more
399 efficient inline expansions.  In particular, @code{defsubst*}
400 arranges for the processing of keyword arguments, default values,
401 etc., to be done at compile-time whenever possible.
402 @end defspec
403
404 @defspec defmacro* name arglist body...
405 This is identical to the regular @code{defmacro} form,
406 except that @var{arglist} is allowed to be a full Common Lisp
407 argument list.  The @code{&environment} keyword is supported as
408 described in Steele.  The @code{&whole} keyword is supported only
409 within destructured lists (see below); top-level @code{&whole}
410 cannot be implemented with the current Emacs Lisp interpreter.
411 The macro expander body is enclosed in an implicit block called
412 @var{name}.
413 @end defspec
414
415 @defspec function* symbol-or-lambda
416 This is identical to the regular @code{function} form,
417 except that if the argument is a @code{lambda} form then that
418 form may use a full Common Lisp argument list.
419 @end defspec
420
421 Also, all forms (such as @code{defsetf} and @code{flet}) defined
422 in this package that include @var{arglist}s in their syntax allow
423 full Common Lisp argument lists.
424
425 Note that it is @emph{not} necessary to use @code{defun*} in
426 order to have access to most @dfn{CL} features in your function.
427 These features are always present; @code{defun*}'s only
428 difference from @code{defun} is its more flexible argument
429 lists and its implicit block.
430
431 The full form of a Common Lisp argument list is
432
433 @example
434 (@var{var}...
435  &optional (@var{var} @var{initform} @var{svar})...
436  &rest @var{var}
437  &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
438  &aux (@var{var} @var{initform})...)
439 @end example
440
441 Each of the five argument list sections is optional.  The @var{svar},
442 @var{initform}, and @var{keyword} parts are optional; if they are
443 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
444
445 The first section consists of zero or more @dfn{required} arguments.
446 These arguments must always be specified in a call to the function;
447 there is no difference between Emacs Lisp and Common Lisp as far as
448 required arguments are concerned.
449
450 The second section consists of @dfn{optional} arguments.  These
451 arguments may be specified in the function call; if they are not,
452 @var{initform} specifies the default value used for the argument.
453 (No @var{initform} means to use @code{nil} as the default.)  The
454 @var{initform} is evaluated with the bindings for the preceding
455 arguments already established; @code{(a &optional (b (1+ a)))}
456 matches one or two arguments, with the second argument defaulting
457 to one plus the first argument.  If the @var{svar} is specified,
458 it is an auxiliary variable which is bound to @code{t} if the optional
459 argument was specified, or to @code{nil} if the argument was omitted.
460 If you don't use an @var{svar}, then there will be no way for your
461 function to tell whether it was called with no argument, or with
462 the default value passed explicitly as an argument.
463
464 The third section consists of a single @dfn{rest} argument.  If
465 more arguments were passed to the function than are accounted for
466 by the required and optional arguments, those extra arguments are
467 collected into a list and bound to the ``rest'' argument variable.
468 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
469 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
470 macro contexts; this package accepts it all the time.
471
472 The fourth section consists of @dfn{keyword} arguments.  These
473 are optional arguments which are specified by name rather than
474 positionally in the argument list.  For example,
475
476 @example
477 (defun* foo (a &optional b &key c d (e 17)))
478 @end example
479
480 @noindent
481 defines a function which may be called with one, two, or more
482 arguments.  The first two arguments are bound to @code{a} and
483 @code{b} in the usual way.  The remaining arguments must be
484 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
485 by the value to be bound to the corresponding argument variable.
486 (Symbols whose names begin with a colon are called @dfn{keywords},
487 and they are self-quoting in the same way as @code{nil} and
488 @code{t}.)
489
490 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
491 arguments to 1, 2, 4, 3, and 17, respectively.  If the same keyword
492 appears more than once in the function call, the first occurrence
493 takes precedence over the later ones.  Note that it is not possible
494 to specify keyword arguments without specifying the optional
495 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
496 @code{b} to the keyword @code{:c}, then signal an error because
497 @code{2} is not a valid keyword.
498
499 If a @var{keyword} symbol is explicitly specified in the argument
500 list as shown in the above diagram, then that keyword will be
501 used instead of just the variable name prefixed with a colon.
502 You can specify a @var{keyword} symbol which does not begin with
503 a colon at all, but such symbols will not be self-quoting; you
504 will have to quote them explicitly with an apostrophe in the
505 function call.
506
507 Ordinarily it is an error to pass an unrecognized keyword to
508 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}.  You can ask
509 Lisp to ignore unrecognized keywords, either by adding the
510 marker @code{&allow-other-keys} after the keyword section
511 of the argument list, or by specifying an @code{:allow-other-keys}
512 argument in the call whose value is non-@code{nil}.  If the
513 function uses both @code{&rest} and @code{&key} at the same time,
514 the ``rest'' argument is bound to the keyword list as it appears
515 in the call.  For example:
516
517 @smallexample
518 (defun* find-thing (thing &rest rest &key need &allow-other-keys)
519   (or (apply 'member* thing thing-list :allow-other-keys t rest)
520       (if need (error "Thing not found"))))
521 @end smallexample
522
523 @noindent
524 This function takes a @code{:need} keyword argument, but also
525 accepts other keyword arguments which are passed on to the
526 @code{member*} function.  @code{allow-other-keys} is used to
527 keep both @code{find-thing} and @code{member*} from complaining
528 about each others' keywords in the arguments.
529
530 As a (significant) performance optimization, this package
531 implements the scan for keyword arguments by calling @code{memq}
532 to search for keywords in a ``rest'' argument.  Technically
533 speaking, this is incorrect, since @code{memq} looks at the
534 odd-numbered values as well as the even-numbered keywords.
535 The net effect is that if you happen to pass a keyword symbol
536 as the @emph{value} of another keyword argument, where that
537 keyword symbol happens to equal the name of a valid keyword
538 argument of the same function, then the keyword parser will
539 become confused.  This minor bug can only affect you if you
540 use keyword symbols as general-purpose data in your program;
541 this practice is strongly discouraged in Emacs Lisp.
542
543 The fifth section of the argument list consists of @dfn{auxiliary
544 variables}.  These are not really arguments at all, but simply
545 variables which are bound to @code{nil} or to the specified
546 @var{initforms} during execution of the function.  There is no
547 difference between the following two functions, except for a
548 matter of stylistic taste:
549
550 @example
551 (defun* foo (a b &aux (c (+ a b)) d)
552   @var{body})
553
554 (defun* foo (a b)
555   (let ((c (+ a b)) d)
556     @var{body}))
557 @end example
558
559 Argument lists support @dfn{destructuring}.  In Common Lisp,
560 destructuring is only allowed with @code{defmacro}; this package
561 allows it with @code{defun*} and other argument lists as well.
562 In destructuring, any argument variable (@var{var} in the above
563 diagram) can be replaced by a list of variables, or more generally,
564 a recursive argument list.  The corresponding argument value must
565 be a list whose elements match this recursive argument list.
566 For example:
567
568 @example
569 (defmacro* dolist ((var listform &optional resultform)
570                    &rest body)
571   ...)
572 @end example
573
574 This says that the first argument of @code{dolist} must be a list
575 of two or three items; if there are other arguments as well as this
576 list, they are stored in @code{body}.  All features allowed in
577 regular argument lists are allowed in these recursive argument lists.
578 In addition, the clause @samp{&whole @var{var}} is allowed at the
579 front of a recursive argument list.  It binds @var{var} to the
580 whole list being matched; thus @code{(&whole all a b)} matches
581 a list of two things, with @code{a} bound to the first thing,
582 @code{b} bound to the second thing, and @code{all} bound to the
583 list itself.  (Common Lisp allows @code{&whole} in top-level
584 @code{defmacro} argument lists as well, but Emacs Lisp does not
585 support this usage.)
586
587 One last feature of destructuring is that the argument list may be
588 dotted, so that the argument list @code{(a b . c)} is functionally
589 equivalent to @code{(a b &rest c)}.
590
591 If the optimization quality @code{safety} is set to 0
592 (@pxref{Declarations}), error checking for wrong number of
593 arguments and invalid keyword arguments is disabled.  By default,
594 argument lists are rigorously checked.
595
596 @node Time of Evaluation, Function Aliases, Argument Lists, Program Structure
597 @section Time of Evaluation
598
599 @noindent
600 Normally, the byte-compiler does not actually execute the forms in
601 a file it compiles.  For example, if a file contains @code{(setq foo t)},
602 the act of compiling it will not actually set @code{foo} to @code{t}.
603 This is true even if the @code{setq} was a top-level form (i.e., not
604 enclosed in a @code{defun} or other form).  Sometimes, though, you
605 would like to have certain top-level forms evaluated at compile-time.
606 For example, the compiler effectively evaluates @code{defmacro} forms
607 at compile-time so that later parts of the file can refer to the
608 macros that are defined.
609
610 @defspec eval-when (situations...) forms...
611 This form controls when the body @var{forms} are evaluated.
612 The @var{situations} list may contain any set of the symbols
613 @code{compile}, @code{load}, and @code{eval} (or their long-winded
614 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
615 and @code{:execute}).
616
617 The @code{eval-when} form is handled differently depending on
618 whether or not it is being compiled as a top-level form.
619 Specifically, it gets special treatment if it is being compiled
620 by a command such as @code{byte-compile-file} which compiles files
621 or buffers of code, and it appears either literally at the
622 top level of the file or inside a top-level @code{progn}.
623
624 For compiled top-level @code{eval-when}s, the body @var{forms} are
625 executed at compile-time if @code{compile} is in the @var{situations}
626 list, and the @var{forms} are written out to the file (to be executed
627 at load-time) if @code{load} is in the @var{situations} list.
628
629 For non-compiled-top-level forms, only the @code{eval} situation is
630 relevant.  (This includes forms executed by the interpreter, forms
631 compiled with @code{byte-compile} rather than @code{byte-compile-file},
632 and non-top-level forms.)  The @code{eval-when} acts like a
633 @code{progn} if @code{eval} is specified, and like @code{nil}
634 (ignoring the body @var{forms}) if not.
635
636 The rules become more subtle when @code{eval-when}s are nested;
637 consult Steele (second edition) for the gruesome details (and
638 some gruesome examples).
639
640 Some simple examples:
641
642 @example
643 ;; Top-level forms in foo.el:
644 (eval-when (compile)           (setq foo1 'bar))
645 (eval-when (load)              (setq foo2 'bar))
646 (eval-when (compile load)      (setq foo3 'bar))
647 (eval-when (eval)              (setq foo4 'bar))
648 (eval-when (eval compile)      (setq foo5 'bar))
649 (eval-when (eval load)         (setq foo6 'bar))
650 (eval-when (eval compile load) (setq foo7 'bar))
651 @end example
652
653 When @file{foo.el} is compiled, these variables will be set during
654 the compilation itself:
655
656 @example
657 foo1  foo3  foo5  foo7      ; `compile'
658 @end example
659
660 When @file{foo.elc} is loaded, these variables will be set:
661
662 @example
663 foo2  foo3  foo6  foo7      ; `load'
664 @end example
665
666 And if @file{foo.el} is loaded uncompiled, these variables will
667 be set:
668
669 @example
670 foo4  foo5  foo6  foo7      ; `eval'
671 @end example
672
673 If these seven @code{eval-when}s had been, say, inside a @code{defun},
674 then the first three would have been equivalent to @code{nil} and the
675 last four would have been equivalent to the corresponding @code{setq}s.
676
677 Note that @code{(eval-when (load eval) @dots{})} is equivalent
678 to @code{(progn @dots{})} in all contexts.  The compiler treats
679 certain top-level forms, like @code{defmacro} (sort-of) and
680 @code{require}, as if they were wrapped in @code{(eval-when
681 (compile load eval) @dots{})}.
682 @end defspec
683
684 Emacs 19 includes two special forms related to @code{eval-when}.
685 One of these, @code{eval-when-compile}, is not quite equivalent to
686 any @code{eval-when} construct and is described below.  This package
687 defines a version of @code{eval-when-compile} for the benefit of
688 Emacs 18 users.
689
690 The other form, @code{(eval-and-compile @dots{})}, is exactly
691 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
692 so is not itself defined by this package.
693
694 @defspec eval-when-compile forms...
695 The @var{forms} are evaluated at compile-time; at execution time,
696 this form acts like a quoted constant of the resulting value.  Used
697 at top-level, @code{eval-when-compile} is just like @samp{eval-when
698 (compile eval)}.  In other contexts, @code{eval-when-compile}
699 allows code to be evaluated once at compile-time for efficiency
700 or other reasons.
701
702 This form is similar to the @samp{#.} syntax of true Common Lisp.
703 @end defspec
704
705 @defspec load-time-value form
706 The @var{form} is evaluated at load-time; at execution time,
707 this form acts like a quoted constant of the resulting value.
708
709 Early Common Lisp had a @samp{#,} syntax that was similar to
710 this, but ANSI Common Lisp replaced it with @code{load-time-value}
711 and gave it more well-defined semantics.
712
713 In a compiled file, @code{load-time-value} arranges for @var{form}
714 to be evaluated when the @file{.elc} file is loaded and then used
715 as if it were a quoted constant.  In code compiled by
716 @code{byte-compile} rather than @code{byte-compile-file}, the
717 effect is identical to @code{eval-when-compile}.  In uncompiled
718 code, both @code{eval-when-compile} and @code{load-time-value}
719 act exactly like @code{progn}.
720
721 @example
722 (defun report ()
723   (insert "This function was executed on: "
724           (current-time-string)
725           ", compiled on: "
726           (eval-when-compile (current-time-string))
727           ;; or '#.(current-time-string) in real Common Lisp
728           ", and loaded on: "
729           (load-time-value (current-time-string))))
730 @end example
731
732 @noindent
733 Byte-compiled, the above defun will result in the following code
734 (or its compiled equivalent, of course) in the @file{.elc} file:
735
736 @example
737 (setq --temp-- (current-time-string))
738 (defun report ()
739   (insert "This function was executed on: "
740           (current-time-string)
741           ", compiled on: "
742           '"Wed Jun 23 18:33:43 1993"
743           ", and loaded on: "
744           --temp--))
745 @end example
746 @end defspec
747
748 @node Function Aliases, , Time of Evaluation, Program Structure
749 @section Function Aliases
750
751 @noindent
752 This section describes a feature from GNU Emacs 19 which this
753 package makes available in other versions of Emacs.
754
755 @defun defalias symbol function
756 This function sets @var{symbol}'s function cell to @var{function}.
757 It is equivalent to @code{fset}, except that in GNU Emacs 19 it also
758 records the setting in @code{load-history} so that it can be undone
759 by a later @code{unload-feature}.
760
761 In other versions of Emacs, @code{defalias} is a synonym for
762 @code{fset}.
763 @end defun
764
765 @node Predicates, Control Structure, Program Structure, Top
766 @chapter Predicates
767
768 @noindent
769 This section describes functions for testing whether various
770 facts are true or false.
771
772 @menu
773 * Type Predicates::      `typep', `deftype', and `coerce'
774 * Equality Predicates::  `eql' and `equalp'
775 @end menu
776
777 @node Type Predicates, Equality Predicates, Predicates, Predicates
778 @section Type Predicates
779
780 @noindent
781 The @dfn{CL} package defines a version of the Common Lisp @code{typep}
782 predicate.
783
784 @defun typep object type
785 Check if @var{object} is of type @var{type}, where @var{type} is a
786 (quoted) type name of the sort used by Common Lisp.  For example,
787 @code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}.
788 @end defun
789
790 The @var{type} argument to the above function is either a symbol
791 or a list beginning with a symbol.
792
793 @itemize @bullet
794 @item
795 If the type name is a symbol, Emacs appends @samp{-p} to the
796 symbol name to form the name of a predicate function for testing
797 the type.  (Built-in predicates whose names end in @samp{p} rather
798 than @samp{-p} are used when appropriate.)
799
800 @item
801 The type symbol @code{t} stands for the union of all types.
802 @code{(typep @var{object} t)} is always true.  Likewise, the
803 type symbol @code{nil} stands for nothing at all, and
804 @code{(typep @var{object} nil)} is always false.
805
806 @item
807 The type symbol @code{null} represents the symbol @code{nil}.
808 Thus @code{(typep @var{object} 'null)} is equivalent to
809 @code{(null @var{object})}.
810
811 @item
812 The type symbol @code{real} is a synonym for @code{number}, and
813 @code{fixnum} is a synonym for @code{integer}.
814
815 @item
816 The type symbols @code{character} and @code{string-char} match
817 characters.  In Emacs-19 and XEmacs-19, characters are the same thing as
818 integers in the range 0-255.  In XEmacs-20, where characters are a
819 first-class data type, this checks for actual characters, and
820 @code{(typep @var{8bit-integer} 'character)} will return @code{nil}.
821
822 @item
823 The type symbol @code{float} uses the @code{floatp-safe} predicate
824 defined by this package rather than @code{floatp}, so it will work
825 correctly even in Emacs versions without floating-point support.
826
827 @item
828 The type list @code{(integer @var{low} @var{high})} represents all
829 integers between @var{low} and @var{high}, inclusive.  Either bound
830 may be a list of a single integer to specify an exclusive limit,
831 or a @code{*} to specify no limit.  The type @code{(integer * *)}
832 is thus equivalent to @code{integer}.
833
834 @item
835 Likewise, lists beginning with @code{float}, @code{real}, or
836 @code{number} represent numbers of that type falling in a particular
837 range.
838
839 @item
840 Lists beginning with @code{and}, @code{or}, and @code{not} form
841 combinations of types.  For example, @code{(or integer (float 0 *))}
842 represents all objects that are integers or non-negative floats.
843
844 @item
845 Lists beginning with @code{member} or @code{member*} represent
846 objects @code{eql} to any of the following values.  For example,
847 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
848 and @code{(member nil)} is equivalent to @code{null}.
849
850 @item
851 Lists of the form @code{(satisfies @var{predicate})} represent
852 all objects for which @var{predicate} returns true when called
853 with that object as an argument.
854 @end itemize
855
856 The following function and macro (not technically predicates) are
857 related to @code{typep}.
858
859 @defun coerce object type
860 This function attempts to convert @var{object} to the specified
861 @var{type}.  If @var{object} is already of that type as determined by
862 @code{typep}, it is simply returned.  Otherwise, certain types of
863 conversions will be made:  If @var{type} is any sequence type
864 (@code{string}, @code{list}, etc.) then @var{object} will be
865 converted to that type if possible.  If @var{type} is
866 @code{character}, then strings of length one and symbols with
867 one-character names can be coerced.  If @var{type} is @code{float},
868 then integers can be coerced in versions of Emacs that support
869 floats.  In all other circumstances, @code{coerce} signals an
870 error.
871 @end defun
872
873 @defspec deftype name arglist forms...
874 This macro defines a new type called @var{name}.  It is similar
875 to @code{defmacro} in many ways; when @var{name} is encountered
876 as a type name, the body @var{forms} are evaluated and should
877 return a type specifier that is equivalent to the type.  The
878 @var{arglist} is a Common Lisp argument list of the sort accepted
879 by @code{defmacro*}.  The type specifier @samp{(@var{name} @var{args}...)}
880 is expanded by calling the expander with those arguments; the type
881 symbol @samp{@var{name}} is expanded by calling the expander with
882 no arguments.  The @var{arglist} is processed the same as for
883 @code{defmacro*} except that optional arguments without explicit
884 defaults use @code{*} instead of @code{nil} as the ``default''
885 default.  Some examples:
886
887 @example
888 (deftype null () '(satisfies null))    ; predefined
889 (deftype list () '(or null cons))      ; predefined
890 (deftype unsigned-byte (&optional bits)
891   (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
892 (unsigned-byte 8)  @equiv{}  (integer 0 255)
893 (unsigned-byte)  @equiv{}  (integer 0 *)
894 unsigned-byte  @equiv{}  (integer 0 *)
895 @end example
896
897 @noindent
898 The last example shows how the Common Lisp @code{unsigned-byte}
899 type specifier could be implemented if desired; this package does
900 not implement @code{unsigned-byte} by default.
901 @end defspec
902
903 The @code{typecase} and @code{check-type} macros also use type
904 names.  @xref{Conditionals}.  @xref{Assertions}.  The @code{map},
905 @code{concatenate}, and @code{merge} functions take type-name
906 arguments to specify the type of sequence to return.  @xref{Sequences}.
907
908 @node Equality Predicates, , Type Predicates, Predicates
909 @section Equality Predicates
910
911 @noindent
912 This package defines two Common Lisp predicates, @code{eql} and
913 @code{equalp}.
914
915 @defun eql a b
916 This function is almost the same as @code{eq}, except that if @var{a}
917 and @var{b} are numbers of the same type, it compares them for numeric
918 equality (as if by @code{equal} instead of @code{eq}).  This makes a
919 difference only for versions of Emacs that are compiled with
920 floating-point support, such as Emacs 19.  Emacs floats are allocated
921 objects just like cons cells, which means that @code{(eq 3.0 3.0)}
922 will not necessarily be true---if the two @code{3.0}s were allocated
923 separately, the pointers will be different even though the numbers are
924 the same.  But @code{(eql 3.0 3.0)} will always be true.
925
926 The types of the arguments must match, so @code{(eql 3 3.0)} is
927 still false.
928
929 Note that Emacs integers are ``direct'' rather than allocated, which
930 basically means @code{(eq 3 3)} will always be true.  Thus @code{eq}
931 and @code{eql} behave differently only if floating-point numbers are
932 involved, and are indistinguishable on Emacs versions that don't
933 support floats.
934
935 There is a slight inconsistency with Common Lisp in the treatment of
936 positive and negative zeros.  Some machines, notably those with IEEE
937 standard arithmetic, represent @code{+0} and @code{-0} as distinct
938 values.  Normally this doesn't matter because the standard specifies
939 that @code{(= 0.0 -0.0)} should always be true, and this is indeed
940 what Emacs Lisp and Common Lisp do.  But the Common Lisp standard
941 states that @code{(eql 0.0 -0.0)} and @code{(equal 0.0 -0.0)} should
942 be false on IEEE-like machines; Emacs Lisp does not do this, and in
943 fact the only known way to distinguish between the two zeros in Emacs
944 Lisp is to @code{format} them and check for a minus sign.
945 @end defun
946
947 @defun equalp a b
948 This function is a more flexible version of @code{equal}.  In
949 particular, it compares strings and characters case-insensitively, and
950 it compares numbers without regard to type (so that @code{(equalp 3
951 3.0)} is true).  Vectors and conses are compared recursively.  All other
952 objects are compared as if by @code{equal}.
953
954 This function differs from Common Lisp @code{equalp} in several
955 respects.  In keeping with the idea that strings are less
956 vector-like in Emacs Lisp, this package's @code{equalp} also will not
957 compare strings against vectors of integers.
958 @end defun
959
960 Also note that the Common Lisp functions @code{member} and @code{assoc}
961 use @code{eql} to compare elements, whereas Emacs Lisp follows the
962 MacLisp tradition and uses @code{equal} for these two functions.
963 In Emacs, use @code{member*} and @code{assoc*} to get functions
964 which use @code{eql} for comparisons.
965
966 @node Control Structure, Macros, Predicates, Top
967 @chapter Control Structure
968
969 @noindent
970 The features described in the following sections implement
971 various advanced control structures, including the powerful
972 @code{setf} facility and a number of looping and conditional
973 constructs.
974
975 @menu
976 * Assignment::             The `psetq' form
977 * Generalized Variables::  `setf', `incf', `push', etc.
978 * Variable Bindings::      `progv', `lexical-let', `flet', `macrolet'
979 * Conditionals::           `when', `unless', `case', `typecase'
980 * Blocks and Exits::       `block', `return', `return-from'
981 * Iteration::              `do', `dotimes', `dolist', `do-symbols'
982 * Loop Facility::          The Common Lisp `loop' macro
983 * Multiple Values::        `values', `multiple-value-bind', etc.
984 @end menu
985
986 @node Assignment, Generalized Variables, Control Structure, Control Structure
987 @section Assignment
988
989 @noindent
990 The @code{psetq} form is just like @code{setq}, except that multiple
991 assignments are done in parallel rather than sequentially.
992
993 @defspec psetq [symbol form]@dots{}
994 This special form (actually a macro) is used to assign to several
995 variables simultaneously.  Given only one @var{symbol} and @var{form},
996 it has the same effect as @code{setq}.  Given several @var{symbol}
997 and @var{form} pairs, it evaluates all the @var{form}s in advance
998 and then stores the corresponding variables afterwards.
999
1000 @example
1001 (setq x 2 y 3)
1002 (setq x (+ x y)  y (* x y))
1003 x
1004      @result{} 5
1005 y                     ; @r{@code{y} was computed after @code{x} was set.}
1006      @result{} 15
1007 (setq x 2 y 3)
1008 (psetq x (+ x y)  y (* x y))
1009 x
1010      @result{} 5
1011 y                     ; @r{@code{y} was computed before @code{x} was set.}
1012      @result{} 6
1013 @end example
1014
1015 The simplest use of @code{psetq} is @code{(psetq x y y x)}, which
1016 exchanges the values of two variables.  (The @code{rotatef} form
1017 provides an even more convenient way to swap two variables;
1018 @pxref{Modify Macros}.)
1019
1020 @code{psetq} always returns @code{nil}.
1021 @end defspec
1022
1023 @node Generalized Variables, Variable Bindings, Assignment, Control Structure
1024 @section Generalized Variables
1025
1026 @noindent
1027 A ``generalized variable'' or ``place form'' is one of the many places
1028 in Lisp memory where values can be stored.  The simplest place form is
1029 a regular Lisp variable.  But the cars and cdrs of lists, elements
1030 of arrays, properties of symbols, and many other locations are also
1031 places where Lisp values are stored.
1032
1033 The @code{setf} form is like @code{setq}, except that it accepts
1034 arbitrary place forms on the left side rather than just
1035 symbols.  For example, @code{(setf (car a) b)} sets the car of
1036 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
1037 but without having to remember two separate functions for setting
1038 and accessing every type of place.
1039
1040 Generalized variables are analogous to ``lvalues'' in the C
1041 language, where @samp{x = a[i]} gets an element from an array
1042 and @samp{a[i] = x} stores an element using the same notation.
1043 Just as certain forms like @code{a[i]} can be lvalues in C, there
1044 is a set of forms that can be generalized variables in Lisp.
1045
1046 @menu
1047 * Basic Setf::         `setf' and place forms
1048 * Modify Macros::      `incf', `push', `rotatef', `letf', `callf', etc.
1049 * Customizing Setf::   `define-modify-macro', `defsetf', `define-setf-method'
1050 @end menu
1051
1052 @node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables
1053 @subsection Basic Setf
1054
1055 @noindent
1056 The @code{setf} macro is the most basic way to operate on generalized
1057 variables.
1058
1059 @defspec setf [place form]@dots{}
1060 This macro evaluates @var{form} and stores it in @var{place}, which
1061 must be a valid generalized variable form.  If there are several
1062 @var{place} and @var{form} pairs, the assignments are done sequentially
1063 just as with @code{setq}.  @code{setf} returns the value of the last
1064 @var{form}.
1065
1066 The following Lisp forms will work as generalized variables, and
1067 so may legally appear in the @var{place} argument of @code{setf}:
1068
1069 @itemize @bullet
1070 @item
1071 A symbol naming a variable.  In other words, @code{(setf x y)} is
1072 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
1073 strictly speaking redundant now that @code{setf} exists.  Many
1074 programmers continue to prefer @code{setq} for setting simple
1075 variables, though, purely for stylistic or historical reasons.
1076 The form @code{(setf x y)} actually expands to @code{(setq x y)},
1077 so there is no performance penalty for using it in compiled code.
1078
1079 @item
1080 A call to any of the following Lisp functions:
1081
1082 @smallexample
1083 car                 cdr                 caar .. cddddr
1084 nth                 rest                first .. tenth
1085 aref                elt                 nthcdr
1086 symbol-function     symbol-value        symbol-plist
1087 get                 getf                gethash
1088 subseq
1089 @end smallexample
1090
1091 @noindent
1092 Note that for @code{nthcdr} and @code{getf}, the list argument
1093 of the function must itself be a valid @var{place} form.  For
1094 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
1095 to 7.  Note that @code{push} and @code{pop} on an @code{nthcdr}
1096 place can be used to insert or delete at any position in a list.
1097 The use of @code{nthcdr} as a @var{place} form is an extension
1098 to standard Common Lisp.
1099
1100 @item
1101 The following Emacs-specific functions are also @code{setf}-able.
1102 (Some of these are defined only in Emacs 19 or only in XEmacs.)
1103
1104 @smallexample
1105 buffer-file-name                  marker-position
1106 buffer-modified-p                 match-data
1107 buffer-name                       mouse-position
1108 buffer-string                     overlay-end
1109 buffer-substring                  overlay-get
1110 current-buffer                    overlay-start
1111 current-case-table                point
1112 current-column                    point-marker
1113 current-global-map                point-max
1114 current-input-mode                point-min
1115 current-local-map                 process-buffer
1116 current-window-configuration      process-filter
1117 default-file-modes                process-sentinel
1118 default-value                     read-mouse-position
1119 documentation-property            screen-height
1120 extent-data                       screen-menubar
1121 extent-end-position               screen-width
1122 extent-start-position             selected-window
1123 face-background                   selected-screen
1124 face-background-pixmap            selected-frame
1125 face-font                         standard-case-table
1126 face-foreground                   syntax-table
1127 face-underline-p                  window-buffer
1128 file-modes                        window-dedicated-p
1129 frame-height                      window-display-table
1130 frame-parameters                  window-height
1131 frame-visible-p                   window-hscroll
1132 frame-width                       window-point
1133 get-register                      window-start
1134 getenv                            window-width
1135 global-key-binding                x-get-cut-buffer
1136 keymap-parent                     x-get-cutbuffer
1137 local-key-binding                 x-get-secondary-selection
1138 mark                              x-get-selection
1139 mark-marker
1140 @end smallexample
1141
1142 Most of these have directly corresponding ``set'' functions, like
1143 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
1144 for @code{point}.  A few, like @code{point-min}, expand to longer
1145 sequences of code when they are @code{setf}'d (@code{(narrow-to-region
1146 x (point-max))} in this case).
1147
1148 @item
1149 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
1150 where @var{subplace} is itself a legal generalized variable whose
1151 current value is a string, and where the value stored is also a
1152 string.  The new string is spliced into the specified part of the
1153 destination string.  For example:
1154
1155 @example
1156 (setq a (list "hello" "world"))
1157      @result{} ("hello" "world")
1158 (cadr a)
1159      @result{} "world"
1160 (substring (cadr a) 2 4)
1161      @result{} "rl"
1162 (setf (substring (cadr a) 2 4) "o")
1163      @result{} "o"
1164 (cadr a)
1165      @result{} "wood"
1166 a
1167      @result{} ("hello" "wood")
1168 @end example
1169
1170 The generalized variable @code{buffer-substring}, listed above,
1171 also works in this way by replacing a portion of the current buffer.
1172
1173 @item
1174 A call of the form @code{(apply '@var{func} @dots{})} or
1175 @code{(apply (function @var{func}) @dots{})}, where @var{func}
1176 is a @code{setf}-able function whose store function is ``suitable''
1177 in the sense described in Steele's book; since none of the standard
1178 Emacs place functions are suitable in this sense, this feature is
1179 only interesting when used with places you define yourself with
1180 @code{define-setf-method} or the long form of @code{defsetf}.
1181
1182 @item
1183 A macro call, in which case the macro is expanded and @code{setf}
1184 is applied to the resulting form.
1185
1186 @item
1187 Any form for which a @code{defsetf} or @code{define-setf-method}
1188 has been made.
1189 @end itemize
1190
1191 Using any forms other than these in the @var{place} argument to
1192 @code{setf} will signal an error.
1193
1194 The @code{setf} macro takes care to evaluate all subforms in
1195 the proper left-to-right order; for example,
1196
1197 @example
1198 (setf (aref vec (incf i)) i)
1199 @end example
1200
1201 @noindent
1202 looks like it will evaluate @code{(incf i)} exactly once, before the
1203 following access to @code{i}; the @code{setf} expander will insert
1204 temporary variables as necessary to ensure that it does in fact work
1205 this way no matter what setf-method is defined for @code{aref}.
1206 (In this case, @code{aset} would be used and no such steps would
1207 be necessary since @code{aset} takes its arguments in a convenient
1208 order.)
1209
1210 However, if the @var{place} form is a macro which explicitly
1211 evaluates its arguments in an unusual order, this unusual order
1212 will be preserved.  Adapting an example from Steele, given
1213
1214 @example
1215 (defmacro wrong-order (x y) (list 'aref y x))
1216 @end example
1217
1218 @noindent
1219 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1220 evaluate @var{b} first, then @var{a}, just as in an actual call
1221 to @code{wrong-order}.
1222 @end defspec
1223
1224 @node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
1225 @subsection Modify Macros
1226
1227 @noindent
1228 This package defines a number of other macros besides @code{setf}
1229 that operate on generalized variables.  Many are interesting and
1230 useful even when the @var{place} is just a variable name.
1231
1232 @defspec psetf [place form]@dots{}
1233 This macro is to @code{setf} what @code{psetq} is to @code{setq}:
1234 When several @var{place}s and @var{form}s are involved, the
1235 assignments take place in parallel rather than sequentially.
1236 Specifically, all subforms are evaluated from left to right, then
1237 all the assignments are done (in an undefined order).
1238 @end defspec
1239
1240 @defspec incf place &optional x
1241 This macro increments the number stored in @var{place} by one, or
1242 by @var{x} if specified.  The incremented value is returned.  For
1243 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
1244 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1245
1246 Once again, care is taken to preserve the ``apparent'' order of
1247 evaluation.  For example,
1248
1249 @example
1250 (incf (aref vec (incf i)))
1251 @end example
1252
1253 @noindent
1254 appears to increment @code{i} once, then increment the element of
1255 @code{vec} addressed by @code{i}; this is indeed exactly what it
1256 does, which means the above form is @emph{not} equivalent to the
1257 ``obvious'' expansion,
1258
1259 @example
1260 (setf (aref vec (incf i)) (1+ (aref vec (incf i))))   ; Wrong!
1261 @end example
1262
1263 @noindent
1264 but rather to something more like
1265
1266 @example
1267 (let ((temp (incf i)))
1268   (setf (aref vec temp) (1+ (aref vec temp))))
1269 @end example
1270
1271 @noindent
1272 Again, all of this is taken care of automatically by @code{incf} and
1273 the other generalized-variable macros.
1274
1275 As a more Emacs-specific example of @code{incf}, the expression
1276 @code{(incf (point) @var{n})} is essentially equivalent to
1277 @code{(forward-char @var{n})}.
1278 @end defspec
1279
1280 @defspec decf place &optional x
1281 This macro decrements the number stored in @var{place} by one, or
1282 by @var{x} if specified.
1283 @end defspec
1284
1285 @defspec pop place
1286 This macro removes and returns the first element of the list stored
1287 in @var{place}.  It is analogous to @code{(prog1 (car @var{place})
1288 (setf @var{place} (cdr @var{place})))}, except that it takes care
1289 to evaluate all subforms only once.
1290 @end defspec
1291
1292 @defspec push x place
1293 This macro inserts @var{x} at the front of the list stored in
1294 @var{place}.  It is analogous to @code{(setf @var{place} (cons
1295 @var{x} @var{place}))}, except for evaluation of the subforms.
1296 @end defspec
1297
1298 @defspec pushnew x place @t{&key :test :test-not :key}
1299 This macro inserts @var{x} at the front of the list stored in
1300 @var{place}, but only if @var{x} was not @code{eql} to any
1301 existing element of the list.  The optional keyword arguments
1302 are interpreted in the same way as for @code{adjoin}.
1303 @xref{Lists as Sets}.
1304 @end defspec
1305
1306 @defspec shiftf place@dots{} newvalue
1307 This macro shifts the @var{place}s left by one, shifting in the
1308 value of @var{newvalue} (which may be any Lisp expression, not just
1309 a generalized variable), and returning the value shifted out of
1310 the first @var{place}.  Thus, @code{(shiftf @var{a} @var{b} @var{c}
1311 @var{d})} is equivalent to
1312
1313 @example
1314 (prog1
1315     @var{a}
1316   (psetf @var{a} @var{b}
1317          @var{b} @var{c}
1318          @var{c} @var{d}))
1319 @end example
1320
1321 @noindent
1322 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1323 evaluated only once each and in the apparent order.
1324 @end defspec
1325
1326 @defspec rotatef place@dots{}
1327 This macro rotates the @var{place}s left by one in circular fashion.
1328 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1329
1330 @example
1331 (psetf @var{a} @var{b}
1332        @var{b} @var{c}
1333        @var{c} @var{d}
1334        @var{d} @var{a})
1335 @end example
1336
1337 @noindent
1338 except for the evaluation of subforms.  @code{rotatef} always
1339 returns @code{nil}.  Note that @code{(rotatef @var{a} @var{b})}
1340 conveniently exchanges @var{a} and @var{b}.
1341 @end defspec
1342
1343 The following macros were invented for this package; they have no
1344 analogues in Common Lisp.
1345
1346 @defspec letf (bindings@dots{}) forms@dots{}
1347 This macro is analogous to @code{let}, but for generalized variables
1348 rather than just symbols.  Each @var{binding} should be of the form
1349 @code{(@var{place} @var{value})}; the original contents of the
1350 @var{place}s are saved, the @var{value}s are stored in them, and
1351 then the body @var{form}s are executed.  Afterwards, the @var{places}
1352 are set back to their original saved contents.  This cleanup happens
1353 even if the @var{form}s exit irregularly due to a @code{throw} or an
1354 error.
1355
1356 For example,
1357
1358 @example
1359 (letf (((point) (point-min))
1360        (a 17))
1361   ...)
1362 @end example
1363
1364 @noindent
1365 moves ``point'' in the current buffer to the beginning of the buffer,
1366 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1367 @code{a} is just a regular variable).  After the body exits, @code{a}
1368 is set back to its original value and point is moved back to its
1369 original position.
1370
1371 Note that @code{letf} on @code{(point)} is not quite like a
1372 @code{save-excursion}, as the latter effectively saves a marker
1373 which tracks insertions and deletions in the buffer.  Actually,
1374 a @code{letf} of @code{(point-marker)} is much closer to this
1375 behavior.  (@code{point} and @code{point-marker} are equivalent
1376 as @code{setf} places; each will accept either an integer or a
1377 marker as the stored value.)
1378
1379 Since generalized variables look like lists, @code{let}'s shorthand
1380 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1381 be ambiguous in @code{letf} and is not allowed.
1382
1383 However, a @var{binding} specifier may be a one-element list
1384 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1385 @var{place})}.  In other words, the @var{place} is not disturbed
1386 on entry to the body, and the only effect of the @code{letf} is
1387 to restore the original value of @var{place} afterwards.  (The
1388 redundant access-and-store suggested by the @code{(@var{place}
1389 @var{place})} example does not actually occur.)
1390
1391 In most cases, the @var{place} must have a well-defined value on
1392 entry to the @code{letf} form.  The only exceptions are plain
1393 variables and calls to @code{symbol-value} and @code{symbol-function}.
1394 If the symbol is not bound on entry, it is simply made unbound by
1395 @code{makunbound} or @code{fmakunbound} on exit.
1396 @end defspec
1397
1398 @defspec letf* (bindings@dots{}) forms@dots{}
1399 This macro is to @code{letf} what @code{let*} is to @code{let}:
1400 It does the bindings in sequential rather than parallel order.
1401 @end defspec
1402
1403 @defspec callf @var{function} @var{place} @var{args}@dots{}
1404 This is the ``generic'' modify macro.  It calls @var{function},
1405 which should be an unquoted function name, macro name, or lambda.
1406 It passes @var{place} and @var{args} as arguments, and assigns the
1407 result back to @var{place}.  For example, @code{(incf @var{place}
1408 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
1409 Some more examples:
1410
1411 @example
1412 (callf abs my-number)
1413 (callf concat (buffer-name) "<" (int-to-string n) ">")
1414 (callf union happy-people (list joe bob) :test 'same-person)
1415 @end example
1416
1417 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1418 to create even more concise notations for modify macros.  Note
1419 again that @code{callf} is an extension to standard Common Lisp.
1420 @end defspec
1421
1422 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1423 This macro is like @code{callf}, except that @var{place} is
1424 the @emph{second} argument of @var{function} rather than the
1425 first.  For example, @code{(push @var{x} @var{place})} is
1426 equivalent to @code{(callf2 cons @var{x} @var{place})}.
1427 @end defspec
1428
1429 The @code{callf} and @code{callf2} macros serve as building
1430 blocks for other macros like @code{incf}, @code{pushnew}, and
1431 @code{define-modify-macro}.  The @code{letf} and @code{letf*}
1432 macros are used in the processing of symbol macros;
1433 @pxref{Macro Bindings}.
1434
1435 @node Customizing Setf, , Modify Macros, Generalized Variables
1436 @subsection Customizing Setf
1437
1438 @noindent
1439 Common Lisp defines three macros, @code{define-modify-macro},
1440 @code{defsetf}, and @code{define-setf-method}, that allow the
1441 user to extend generalized variables in various ways.
1442
1443 @defspec define-modify-macro name arglist function [doc-string]
1444 This macro defines a ``read-modify-write'' macro similar to
1445 @code{incf} and @code{decf}.  The macro @var{name} is defined
1446 to take a @var{place} argument followed by additional arguments
1447 described by @var{arglist}.  The call
1448
1449 @example
1450 (@var{name} @var{place} @var{args}...)
1451 @end example
1452
1453 @noindent
1454 will be expanded to
1455
1456 @example
1457 (callf @var{func} @var{place} @var{args}...)
1458 @end example
1459
1460 @noindent
1461 which in turn is roughly equivalent to
1462
1463 @example
1464 (setf @var{place} (@var{func} @var{place} @var{args}...))
1465 @end example
1466
1467 For example:
1468
1469 @example
1470 (define-modify-macro incf (&optional (n 1)) +)
1471 (define-modify-macro concatf (&rest args) concat)
1472 @end example
1473
1474 Note that @code{&key} is not allowed in @var{arglist}, but
1475 @code{&rest} is sufficient to pass keywords on to the function.
1476
1477 Most of the modify macros defined by Common Lisp do not exactly
1478 follow the pattern of @code{define-modify-macro}.  For example,
1479 @code{push} takes its arguments in the wrong order, and @code{pop}
1480 is completely irregular.  You can define these macros ``by hand''
1481 using @code{get-setf-method}, or consult the source file
1482 @file{cl-macs.el} to see how to use the internal @code{setf}
1483 building blocks.
1484 @end defspec
1485
1486 @defspec defsetf access-fn update-fn
1487 This is the simpler of two @code{defsetf} forms.  Where
1488 @var{access-fn} is the name of a function which accesses a place,
1489 this declares @var{update-fn} to be the corresponding store
1490 function.  From now on,
1491
1492 @example
1493 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1494 @end example
1495
1496 @noindent
1497 will be expanded to
1498
1499 @example
1500 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1501 @end example
1502
1503 @noindent
1504 The @var{update-fn} is required to be either a true function, or
1505 a macro which evaluates its arguments in a function-like way.  Also,
1506 the @var{update-fn} is expected to return @var{value} as its result.
1507 Otherwise, the above expansion would not obey the rules for the way
1508 @code{setf} is supposed to behave.
1509
1510 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1511 to @code{defsetf} says that the @code{update-fn}'s return value is
1512 not suitable, so that the above @code{setf} should be expanded to
1513 something more like
1514
1515 @example
1516 (let ((temp @var{value}))
1517   (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1518   temp)
1519 @end example
1520
1521 Some examples of the use of @code{defsetf}, drawn from the standard
1522 suite of setf methods, are:
1523
1524 @example
1525 (defsetf car setcar)
1526 (defsetf symbol-value set)
1527 (defsetf buffer-name rename-buffer t)
1528 @end example
1529 @end defspec
1530
1531 @defspec defsetf access-fn arglist (store-var) forms@dots{}
1532 This is the second, more complex, form of @code{defsetf}.  It is
1533 rather like @code{defmacro} except for the additional @var{store-var}
1534 argument.  The @var{forms} should return a Lisp form which stores
1535 the value of @var{store-var} into the generalized variable formed
1536 by a call to @var{access-fn} with arguments described by @var{arglist}.
1537 The @var{forms} may begin with a string which documents the @code{setf}
1538 method (analogous to the doc string that appears at the front of a
1539 function).
1540
1541 For example, the simple form of @code{defsetf} is shorthand for
1542
1543 @example
1544 (defsetf @var{access-fn} (&rest args) (store)
1545   (append '(@var{update-fn}) args (list store)))
1546 @end example
1547
1548 The Lisp form that is returned can access the arguments from
1549 @var{arglist} and @var{store-var} in an unrestricted fashion;
1550 macros like @code{setf} and @code{incf} which invoke this
1551 setf-method will insert temporary variables as needed to make
1552 sure the apparent order of evaluation is preserved.
1553
1554 Another example drawn from the standard package:
1555
1556 @example
1557 (defsetf nth (n x) (store)
1558   (list 'setcar (list 'nthcdr n x) store))
1559 @end example
1560 @end defspec
1561
1562 @defspec define-setf-method access-fn arglist forms@dots{}
1563 This is the most general way to create new place forms.  When
1564 a @code{setf} to @var{access-fn} with arguments described by
1565 @var{arglist} is expanded, the @var{forms} are evaluated and
1566 must return a list of five items:
1567
1568 @enumerate
1569 @item
1570 A list of @dfn{temporary variables}.
1571
1572 @item
1573 A list of @dfn{value forms} corresponding to the temporary variables
1574 above.  The temporary variables will be bound to these value forms
1575 as the first step of any operation on the generalized variable.
1576
1577 @item
1578 A list of exactly one @dfn{store variable} (generally obtained
1579 from a call to @code{gensym}).
1580
1581 @item
1582 A Lisp form which stores the contents of the store variable into
1583 the generalized variable, assuming the temporaries have been
1584 bound as described above.
1585
1586 @item
1587 A Lisp form which accesses the contents of the generalized variable,
1588 assuming the temporaries have been bound.
1589 @end enumerate
1590
1591 This is exactly like the Common Lisp macro of the same name,
1592 except that the method returns a list of five values rather
1593 than the five values themselves, since Emacs Lisp does not
1594 support Common Lisp's notion of multiple return values.
1595
1596 Once again, the @var{forms} may begin with a documentation string.
1597
1598 A setf-method should be maximally conservative with regard to
1599 temporary variables.  In the setf-methods generated by
1600 @code{defsetf}, the second return value is simply the list of
1601 arguments in the place form, and the first return value is a
1602 list of a corresponding number of temporary variables generated
1603 by @code{gensym}.  Macros like @code{setf} and @code{incf} which
1604 use this setf-method will optimize away most temporaries that
1605 turn out to be unnecessary, so there is little reason for the
1606 setf-method itself to optimize.
1607 @end defspec
1608
1609 @defun get-setf-method place &optional env
1610 This function returns the setf-method for @var{place}, by
1611 invoking the definition previously recorded by @code{defsetf}
1612 or @code{define-setf-method}.  The result is a list of five
1613 values as described above.  You can use this function to build
1614 your own @code{incf}-like modify macros.  (Actually, it is
1615 better to use the internal functions @code{cl-setf-do-modify}
1616 and @code{cl-setf-do-store}, which are a bit easier to use and
1617 which also do a number of optimizations; consult the source
1618 code for the @code{incf} function for a simple example.)
1619
1620 The argument @var{env} specifies the ``environment'' to be
1621 passed on to @code{macroexpand} if @code{get-setf-method} should
1622 need to expand a macro in @var{place}.  It should come from
1623 an @code{&environment} argument to the macro or setf-method
1624 that called @code{get-setf-method}.
1625
1626 See also the source code for the setf-methods for @code{apply}
1627 and @code{substring}, each of which works by calling
1628 @code{get-setf-method} on a simpler case, then massaging
1629 the result in various ways.
1630 @end defun
1631
1632 Modern Common Lisp defines a second, independent way to specify
1633 the @code{setf} behavior of a function, namely ``@code{setf}
1634 functions'' whose names are lists @code{(setf @var{name})}
1635 rather than symbols.  For example, @code{(defun (setf foo) @dots{})}
1636 defines the function that is used when @code{setf} is applied to
1637 @code{foo}.  This package does not currently support @code{setf}
1638 functions.  In particular, it is a compile-time error to use
1639 @code{setf} on a form which has not already been @code{defsetf}'d
1640 or otherwise declared; in newer Common Lisps, this would not be
1641 an error since the function @code{(setf @var{func})} might be
1642 defined later.
1643
1644 @iftex
1645 @secno=4
1646 @end iftex
1647
1648 @node Variable Bindings, Conditionals, Generalized Variables, Control Structure
1649 @section Variable Bindings
1650
1651 @noindent
1652 These Lisp forms make bindings to variables and function names,
1653 analogous to Lisp's built-in @code{let} form.
1654
1655 @xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
1656 are also related to variable bindings.
1657
1658 @menu
1659 * Dynamic Bindings::     The `progv' form
1660 * Lexical Bindings::     `lexical-let' and lexical closures
1661 * Function Bindings::    `flet' and `labels'
1662 * Macro Bindings::       `macrolet' and `symbol-macrolet'
1663 @end menu
1664
1665 @node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings
1666 @subsection Dynamic Bindings
1667
1668 @noindent
1669 The standard @code{let} form binds variables whose names are known
1670 at compile-time.  The @code{progv} form provides an easy way to
1671 bind variables whose names are computed at run-time.
1672
1673 @defspec progv symbols values forms@dots{}
1674 This form establishes @code{let}-style variable bindings on a
1675 set of variables computed at run-time.  The expressions
1676 @var{symbols} and @var{values} are evaluated, and must return lists
1677 of symbols and values, respectively.  The symbols are bound to the
1678 corresponding values for the duration of the body @var{form}s.
1679 If @var{values} is shorter than @var{symbols}, the last few symbols
1680 are made unbound (as if by @code{makunbound}) inside the body.
1681 If @var{symbols} is shorter than @var{values}, the excess values
1682 are ignored.
1683 @end defspec
1684
1685 @node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
1686 @subsection Lexical Bindings
1687
1688 @noindent
1689 The @dfn{CL} package defines the following macro which
1690 more closely follows the Common Lisp @code{let} form:
1691
1692 @defspec lexical-let (bindings@dots{}) forms@dots{}
1693 This form is exactly like @code{let} except that the bindings it
1694 establishes are purely lexical.  Lexical bindings are similar to
1695 local variables in a language like C:  Only the code physically
1696 within the body of the @code{lexical-let} (after macro expansion)
1697 may refer to the bound variables.
1698
1699 @example
1700 (setq a 5)
1701 (defun foo (b) (+ a b))
1702 (let ((a 2)) (foo a))
1703      @result{} 4
1704 (lexical-let ((a 2)) (foo a))
1705      @result{} 7
1706 @end example
1707
1708 @noindent
1709 In this example, a regular @code{let} binding of @code{a} actually
1710 makes a temporary change to the global variable @code{a}, so @code{foo}
1711 is able to see the binding of @code{a} to 2.  But @code{lexical-let}
1712 actually creates a distinct local variable @code{a} for use within its
1713 body, without any effect on the global variable of the same name.
1714
1715 The most important use of lexical bindings is to create @dfn{closures}.
1716 A closure is a function object that refers to an outside lexical
1717 variable.  For example:
1718
1719 @example
1720 (defun make-adder (n)
1721   (lexical-let ((n n))
1722     (function (lambda (m) (+ n m)))))
1723 (setq add17 (make-adder 17))
1724 (funcall add17 4)
1725      @result{} 21
1726 @end example
1727
1728 @noindent
1729 The call @code{(make-adder 17)} returns a function object which adds
1730 17 to its argument.  If @code{let} had been used instead of
1731 @code{lexical-let}, the function object would have referred to the
1732 global @code{n}, which would have been bound to 17 only during the
1733 call to @code{make-adder} itself.
1734
1735 @example
1736 (defun make-counter ()
1737   (lexical-let ((n 0))
1738     (function* (lambda (&optional (m 1)) (incf n m)))))
1739 (setq count-1 (make-counter))
1740 (funcall count-1 3)
1741      @result{} 3
1742 (funcall count-1 14)
1743      @result{} 17
1744 (setq count-2 (make-counter))
1745 (funcall count-2 5)
1746      @result{} 5
1747 (funcall count-1 2)
1748      @result{} 19
1749 (funcall count-2)
1750      @result{} 6
1751 @end example
1752
1753 @noindent
1754 Here we see that each call to @code{make-counter} creates a distinct
1755 local variable @code{n}, which serves as a private counter for the
1756 function object that is returned.
1757
1758 Closed-over lexical variables persist until the last reference to
1759 them goes away, just like all other Lisp objects.  For example,
1760 @code{count-2} refers to a function object which refers to an
1761 instance of the variable @code{n}; this is the only reference
1762 to that variable, so after @code{(setq count-2 nil)} the garbage
1763 collector would be able to delete this instance of @code{n}.
1764 Of course, if a @code{lexical-let} does not actually create any
1765 closures, then the lexical variables are free as soon as the
1766 @code{lexical-let} returns.
1767
1768 Many closures are used only during the extent of the bindings they
1769 refer to; these are known as ``downward funargs'' in Lisp parlance.
1770 When a closure is used in this way, regular Emacs Lisp dynamic
1771 bindings suffice and will be more efficient than @code{lexical-let}
1772 closures:
1773
1774 @example
1775 (defun add-to-list (x list)
1776   (mapcar (function (lambda (y) (+ x y))) list))
1777 (add-to-list 7 '(1 2 5))
1778      @result{} (8 9 12)
1779 @end example
1780
1781 @noindent
1782 Since this lambda is only used while @code{x} is still bound,
1783 it is not necessary to make a true closure out of it.
1784
1785 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1786 to create a named closure.  If several closures are created in the
1787 body of a single @code{lexical-let}, they all close over the same
1788 instance of the lexical variable.
1789
1790 The @code{lexical-let} form is an extension to Common Lisp.  In
1791 true Common Lisp, all bindings are lexical unless declared otherwise.
1792 @end defspec
1793
1794 @defspec lexical-let* (bindings@dots{}) forms@dots{}
1795 This form is just like @code{lexical-let}, except that the bindings
1796 are made sequentially in the manner of @code{let*}.
1797 @end defspec
1798
1799 @node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
1800 @subsection Function Bindings
1801
1802 @noindent
1803 These forms make @code{let}-like bindings to functions instead
1804 of variables.
1805
1806 @defspec flet (bindings@dots{}) forms@dots{}
1807 This form establishes @code{let}-style bindings on the function
1808 cells of symbols rather than on the value cells.  Each @var{binding}
1809 must be a list of the form @samp{(@var{name} @var{arglist}
1810 @var{forms}@dots{})}, which defines a function exactly as if
1811 it were a @code{defun*} form.  The function @var{name} is defined
1812 accordingly for the duration of the body of the @code{flet}; then
1813 the old function definition, or lack thereof, is restored.
1814
1815 While @code{flet} in Common Lisp establishes a lexical binding of
1816 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding.  The
1817 result is that @code{flet} affects indirect calls to a function as
1818 well as calls directly inside the @code{flet} form itself.
1819
1820 You can use @code{flet} to disable or modify the behavior of a
1821 function in a temporary fashion.  This will even work on Emacs
1822 primitives, although note that some calls to primitive functions
1823 internal to Emacs are made without going through the symbol's
1824 function cell, and so will not be affected by @code{flet}.  For
1825 example,
1826
1827 @example
1828 (flet ((message (&rest args) (push args saved-msgs)))
1829   (do-something))
1830 @end example
1831
1832 This code attempts to replace the built-in function @code{message}
1833 with a function that simply saves the messages in a list rather
1834 than displaying them.  The original definition of @code{message}
1835 will be restored after @code{do-something} exits.  This code will
1836 work fine on messages generated by other Lisp code, but messages
1837 generated directly inside Emacs will not be caught since they make
1838 direct C-language calls to the message routines rather than going
1839 through the Lisp @code{message} function.
1840
1841 Functions defined by @code{flet} may use the full Common Lisp
1842 argument notation supported by @code{defun*}; also, the function
1843 body is enclosed in an implicit block as if by @code{defun*}.
1844 @xref{Program Structure}.
1845 @end defspec
1846
1847 @defspec labels (bindings@dots{}) forms@dots{}
1848 The @code{labels} form is a synonym for @code{flet}.  (In Common
1849 Lisp, @code{labels} and @code{flet} differ in ways that depend on
1850 their lexical scoping; these distinctions vanish in dynamically
1851 scoped Emacs Lisp.)
1852 @end defspec
1853
1854 @node Macro Bindings, , Function Bindings, Variable Bindings
1855 @subsection Macro Bindings
1856
1857 @noindent
1858 These forms create local macros and ``symbol macros.''
1859
1860 @defspec macrolet (bindings@dots{}) forms@dots{}
1861 This form is analogous to @code{flet}, but for macros instead of
1862 functions.  Each @var{binding} is a list of the same form as the
1863 arguments to @code{defmacro*} (i.e., a macro name, argument list,
1864 and macro-expander forms).  The macro is defined accordingly for
1865 use within the body of the @code{macrolet}.
1866
1867 Because of the nature of macros, @code{macrolet} is lexically
1868 scoped even in Emacs Lisp:  The @code{macrolet} binding will
1869 affect only calls that appear physically within the body
1870 @var{forms}, possibly after expansion of other macros in the
1871 body.
1872 @end defspec
1873
1874 @defspec symbol-macrolet (bindings@dots{}) forms@dots{}
1875 This form creates @dfn{symbol macros}, which are macros that look
1876 like variable references rather than function calls.  Each
1877 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1878 any reference to @var{var} within the body @var{forms} is
1879 replaced by @var{expansion}.
1880
1881 @example
1882 (setq bar '(5 . 9))
1883 (symbol-macrolet ((foo (car bar)))
1884   (incf foo))
1885 bar
1886      @result{} (6 . 9)
1887 @end example
1888
1889 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1890 I.e., @code{(setq foo 4)} in the above would be equivalent to
1891 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1892
1893 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1894 treated like a @code{letf} or @code{letf*}.  This differs from true
1895 Common Lisp, where the rules of lexical scoping cause a @code{let}
1896 binding to shadow a @code{symbol-macrolet} binding.  In this package,
1897 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1898 macro.
1899
1900 There is no analogue of @code{defmacro} for symbol macros; all symbol
1901 macros are local.  A typical use of @code{symbol-macrolet} is in the
1902 expansion of another macro:
1903
1904 @example
1905 (defmacro* my-dolist ((x list) &rest body)
1906   (let ((var (gensym)))
1907     (list 'loop 'for var 'on list 'do
1908           (list* 'symbol-macrolet (list (list x (list 'car var)))
1909                  body))))
1910
1911 (setq mylist '(1 2 3 4))
1912 (my-dolist (x mylist) (incf x))
1913 mylist
1914      @result{} (2 3 4 5)
1915 @end example
1916
1917 @noindent
1918 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1919 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1920 reference onto the elements of the list.  The @code{my-dolist} call
1921 shown here expands to
1922
1923 @example
1924 (loop for G1234 on mylist do
1925       (symbol-macrolet ((x (car G1234)))
1926         (incf x)))
1927 @end example
1928
1929 @noindent
1930 which in turn expands to
1931
1932 @example
1933 (loop for G1234 on mylist do (incf (car G1234)))
1934 @end example
1935
1936 @xref{Loop Facility}, for a description of the @code{loop} macro.
1937 This package defines a nonstandard @code{in-ref} loop clause that
1938 works much like @code{my-dolist}.
1939 @end defspec
1940
1941 @node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
1942 @section Conditionals
1943
1944 @noindent
1945 These conditional forms augment Emacs Lisp's simple @code{if},
1946 @code{and}, @code{or}, and @code{cond} forms.
1947
1948 @defspec when test forms@dots{}
1949 This is a variant of @code{if} where there are no ``else'' forms,
1950 and possibly several ``then'' forms.  In particular,
1951
1952 @example
1953 (when @var{test} @var{a} @var{b} @var{c})
1954 @end example
1955
1956 @noindent
1957 is entirely equivalent to
1958
1959 @example
1960 (if @var{test} (progn @var{a} @var{b} @var{c}) nil)
1961 @end example
1962 @end defspec
1963
1964 @defspec unless test forms@dots{}
1965 This is a variant of @code{if} where there are no ``then'' forms,
1966 and possibly several ``else'' forms:
1967
1968 @example
1969 (unless @var{test} @var{a} @var{b} @var{c})
1970 @end example
1971
1972 @noindent
1973 is entirely equivalent to
1974
1975 @example
1976 (when (not @var{test}) @var{a} @var{b} @var{c})
1977 @end example
1978 @end defspec
1979
1980 @defspec case keyform clause@dots{}
1981 This macro evaluates @var{keyform}, then compares it with the key
1982 values listed in the various @var{clause}s.  Whichever clause matches
1983 the key is executed; comparison is done by @code{eql}.  If no clause
1984 matches, the @code{case} form returns @code{nil}.  The clauses are
1985 of the form
1986
1987 @example
1988 (@var{keylist} @var{body-forms}@dots{})
1989 @end example
1990
1991 @noindent
1992 where @var{keylist} is a list of key values.  If there is exactly
1993 one value, and it is not a cons cell or the symbol @code{nil} or
1994 @code{t}, then it can be used by itself as a @var{keylist} without
1995 being enclosed in a list.  All key values in the @code{case} form
1996 must be distinct.  The final clauses may use @code{t} in place of
1997 a @var{keylist} to indicate a default clause that should be taken
1998 if none of the other clauses match.  (The symbol @code{otherwise}
1999 is also recognized in place of @code{t}.  To make a clause that
2000 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
2001 enclose the symbol in a list.)
2002
2003 For example, this expression reads a keystroke, then does one of
2004 four things depending on whether it is an @samp{a}, a @samp{b},
2005 a @key{RET} or @key{LFD}, or anything else.
2006
2007 @example
2008 (case (read-char)
2009   (?a (do-a-thing))
2010   (?b (do-b-thing))
2011   ((?\r ?\n) (do-ret-thing))
2012   (t (do-other-thing)))
2013 @end example
2014 @end defspec
2015
2016 @defspec ecase keyform clause@dots{}
2017 This macro is just like @code{case}, except that if the key does
2018 not match any of the clauses, an error is signalled rather than
2019 simply returning @code{nil}.
2020 @end defspec
2021
2022 @defspec typecase keyform clause@dots{}
2023 This macro is a version of @code{case} that checks for types
2024 rather than values.  Each @var{clause} is of the form
2025 @samp{(@var{type} @var{body}...)}.  @xref{Type Predicates},
2026 for a description of type specifiers.  For example,
2027
2028 @example
2029 (typecase x
2030   (integer (munch-integer x))
2031   (float (munch-float x))
2032   (string (munch-integer (string-to-int x)))
2033   (t (munch-anything x)))
2034 @end example
2035
2036 The type specifier @code{t} matches any type of object; the word
2037 @code{otherwise} is also allowed.  To make one clause match any of
2038 several types, use an @code{(or ...)} type specifier.
2039 @end defspec
2040
2041 @defspec etypecase keyform clause@dots{}
2042 This macro is just like @code{typecase}, except that if the key does
2043 not match any of the clauses, an error is signalled rather than
2044 simply returning @code{nil}.
2045 @end defspec
2046
2047 @node Blocks and Exits, Iteration, Conditionals, Control Structure
2048 @section Blocks and Exits
2049
2050 @noindent
2051 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
2052 similar to @code{catch} and @code{throw}, but lexically rather than
2053 dynamically scoped.  This package actually implements @code{block}
2054 in terms of @code{catch}; however, the lexical scoping allows the
2055 optimizing byte-compiler to omit the costly @code{catch} step if the
2056 body of the block does not actually @code{return-from} the block.
2057
2058 @defspec block name forms@dots{}
2059 The @var{forms} are evaluated as if by a @code{progn}.  However,
2060 if any of the @var{forms} execute @code{(return-from @var{name})},
2061 they will jump out and return directly from the @code{block} form.
2062 The @code{block} returns the result of the last @var{form} unless
2063 a @code{return-from} occurs.
2064
2065 The @code{block}/@code{return-from} mechanism is quite similar to
2066 the @code{catch}/@code{throw} mechanism.  The main differences are
2067 that block @var{name}s are unevaluated symbols, rather than forms
2068 (such as quoted symbols) which evaluate to a tag at run-time; and
2069 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
2070 are dynamically scoped.  This means that functions called from the
2071 body of a @code{catch} can also @code{throw} to the @code{catch},
2072 but the @code{return-from} referring to a block name must appear
2073 physically within the @var{forms} that make up the body of the block.
2074 They may not appear within other called functions, although they may
2075 appear within macro expansions or @code{lambda}s in the body.  Block
2076 names and @code{catch} names form independent name-spaces.
2077
2078 In true Common Lisp, @code{defun} and @code{defmacro} surround
2079 the function or expander bodies with implicit blocks with the
2080 same name as the function or macro.  This does not occur in Emacs
2081 Lisp, but this package provides @code{defun*} and @code{defmacro*}
2082 forms which do create the implicit block.
2083
2084 The Common Lisp looping constructs defined by this package,
2085 such as @code{loop} and @code{dolist}, also create implicit blocks
2086 just as in Common Lisp.
2087
2088 Because they are implemented in terms of Emacs Lisp @code{catch}
2089 and @code{throw}, blocks have the same overhead as actual
2090 @code{catch} constructs (roughly two function calls).  However,
2091 Zawinski and Furuseth's optimizing byte compiler (standard in
2092 Emacs 19) will optimize away the @code{catch} if the block does
2093 not in fact contain any @code{return} or @code{return-from} calls
2094 that jump to it.  This means that @code{do} loops and @code{defun*}
2095 functions which don't use @code{return} don't pay the overhead to
2096 support it.
2097 @end defspec
2098
2099 @defspec return-from name [result]
2100 This macro returns from the block named @var{name}, which must be
2101 an (unevaluated) symbol.  If a @var{result} form is specified, it
2102 is evaluated to produce the result returned from the @code{block}.
2103 Otherwise, @code{nil} is returned.
2104 @end defspec
2105
2106 @defspec return [result]
2107 This macro is exactly like @code{(return-from nil @var{result})}.
2108 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
2109 themselves in @code{nil} blocks.
2110 @end defspec
2111
2112 @node Iteration, Loop Facility, Blocks and Exits, Control Structure
2113 @section Iteration
2114
2115 @noindent
2116 The macros described here provide more sophisticated, high-level
2117 looping constructs to complement Emacs Lisp's basic @code{while}
2118 loop.
2119
2120 @defspec loop forms@dots{}
2121 The @dfn{CL} package supports both the simple, old-style meaning of
2122 @code{loop} and the extremely powerful and flexible feature known as
2123 the @dfn{Loop Facility} or @dfn{Loop Macro}.  This more advanced
2124 facility is discussed in the following section; @pxref{Loop Facility}.
2125 The simple form of @code{loop} is described here.
2126
2127 If @code{loop} is followed by zero or more Lisp expressions,
2128 then @code{(loop @var{exprs}@dots{})} simply creates an infinite
2129 loop executing the expressions over and over.  The loop is
2130 enclosed in an implicit @code{nil} block.  Thus,
2131
2132 @example
2133 (loop (foo)  (if (no-more) (return 72))  (bar))
2134 @end example
2135
2136 @noindent
2137 is exactly equivalent to
2138
2139 @example
2140 (block nil (while t (foo)  (if (no-more) (return 72))  (bar)))
2141 @end example
2142
2143 If any of the expressions are plain symbols, the loop is instead
2144 interpreted as a Loop Macro specification as described later.
2145 (This is not a restriction in practice, since a plain symbol
2146 in the above notation would simply access and throw away the
2147 value of a variable.)
2148 @end defspec
2149
2150 @defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2151 This macro creates a general iterative loop.  Each @var{spec} is
2152 of the form
2153
2154 @example
2155 (@var{var} [@var{init} [@var{step}]])
2156 @end example
2157
2158 The loop works as follows:  First, each @var{var} is bound to the
2159 associated @var{init} value as if by a @code{let} form.  Then, in
2160 each iteration of the loop, the @var{end-test} is evaluated; if
2161 true, the loop is finished.  Otherwise, the body @var{forms} are
2162 evaluated, then each @var{var} is set to the associated @var{step}
2163 expression (as if by a @code{psetq} form) and the next iteration
2164 begins.  Once the @var{end-test} becomes true, the @var{result}
2165 forms are evaluated (with the @var{var}s still bound to their
2166 values) to produce the result returned by @code{do}.
2167
2168 The entire @code{do} loop is enclosed in an implicit @code{nil}
2169 block, so that you can use @code{(return)} to break out of the
2170 loop at any time.
2171
2172 If there are no @var{result} forms, the loop returns @code{nil}.
2173 If a given @var{var} has no @var{step} form, it is bound to its
2174 @var{init} value but not otherwise modified during the @code{do}
2175 loop (unless the code explicitly modifies it); this case is just
2176 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
2177 around the loop.  If @var{init} is also omitted it defaults to
2178 @code{nil}, and in this case a plain @samp{@var{var}} can be used
2179 in place of @samp{(@var{var})}, again following the analogy with
2180 @code{let}.
2181
2182 This example (from Steele) illustrates a loop which applies the
2183 function @code{f} to successive pairs of values from the lists
2184 @code{foo} and @code{bar}; it is equivalent to the call
2185 @code{(mapcar* 'f foo bar)}.  Note that this loop has no body
2186 @var{forms} at all, performing all its work as side effects of
2187 the rest of the loop.
2188
2189 @example
2190 (do ((x foo (cdr x))
2191      (y bar (cdr y))
2192      (z nil (cons (f (car x) (car y)) z)))
2193   ((or (null x) (null y))
2194    (nreverse z)))
2195 @end example
2196 @end defspec
2197
2198 @defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2199 This is to @code{do} what @code{let*} is to @code{let}.  In
2200 particular, the initial values are bound as if by @code{let*}
2201 rather than @code{let}, and the steps are assigned as if by
2202 @code{setq} rather than @code{psetq}.
2203
2204 Here is another way to write the above loop:
2205
2206 @example
2207 (do* ((xp foo (cdr xp))
2208       (yp bar (cdr yp))
2209       (x (car xp) (car xp))
2210       (y (car yp) (car yp))
2211       z)
2212   ((or (null xp) (null yp))
2213    (nreverse z))
2214   (push (f x y) z))
2215 @end example
2216 @end defspec
2217
2218 @defspec dolist (var list [result]) forms@dots{}
2219 This is a more specialized loop which iterates across the elements
2220 of a list.  @var{list} should evaluate to a list; the body @var{forms}
2221 are executed with @var{var} bound to each element of the list in
2222 turn.  Finally, the @var{result} form (or @code{nil}) is evaluated
2223 with @var{var} bound to @code{nil} to produce the result returned by
2224 the loop.  The loop is surrounded by an implicit @code{nil} block.
2225 @end defspec
2226
2227 @defspec dotimes (var count [result]) forms@dots{}
2228 This is a more specialized loop which iterates a specified number
2229 of times.  The body is executed with @var{var} bound to the integers
2230 from zero (inclusive) to @var{count} (exclusive), in turn.  Then
2231 the @code{result} form is evaluated with @var{var} bound to the total
2232 number of iterations that were done (i.e., @code{(max 0 @var{count})})
2233 to get the return value for the loop form.  The loop is surrounded
2234 by an implicit @code{nil} block.
2235 @end defspec
2236
2237 @defspec do-symbols (var [obarray [result]]) forms@dots{}
2238 This loop iterates over all interned symbols.  If @var{obarray}
2239 is specified and is not @code{nil}, it loops over all symbols in
2240 that obarray.  For each symbol, the body @var{forms} are evaluated
2241 with @var{var} bound to that symbol.  The symbols are visited in
2242 an unspecified order.  Afterward the @var{result} form, if any,
2243 is evaluated (with @var{var} bound to @code{nil}) to get the return
2244 value.  The loop is surrounded by an implicit @code{nil} block.
2245 @end defspec
2246
2247 @defspec do-all-symbols (var [result]) forms@dots{}
2248 This is identical to @code{do-symbols} except that the @var{obarray}
2249 argument is omitted; it always iterates over the default obarray.
2250 @end defspec
2251
2252 @xref{Mapping over Sequences}, for some more functions for
2253 iterating over vectors or lists.
2254
2255 @node Loop Facility, Multiple Values, Iteration, Control Structure
2256 @section Loop Facility
2257
2258 @noindent
2259 A common complaint with Lisp's traditional looping constructs is
2260 that they are either too simple and limited, such as Common Lisp's
2261 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2262 obscure, like Common Lisp's @code{do} loop.
2263
2264 To remedy this, recent versions of Common Lisp have added a new
2265 construct called the ``Loop Facility'' or ``@code{loop} macro,''
2266 with an easy-to-use but very powerful and expressive syntax.
2267
2268 @menu
2269 * Loop Basics::           `loop' macro, basic clause structure
2270 * Loop Examples::         Working examples of `loop' macro
2271 * For Clauses::           Clauses introduced by `for' or `as'
2272 * Iteration Clauses::     `repeat', `while', `thereis', etc.
2273 * Accumulation Clauses::  `collect', `sum', `maximize', etc.
2274 * Other Clauses::         `with', `if', `initially', `finally'
2275 @end menu
2276
2277 @node Loop Basics, Loop Examples, Loop Facility, Loop Facility
2278 @subsection Loop Basics
2279
2280 @noindent
2281 The @code{loop} macro essentially creates a mini-language within
2282 Lisp that is specially tailored for describing loops.  While this
2283 language is a little strange-looking by the standards of regular Lisp,
2284 it turns out to be very easy to learn and well-suited to its purpose.
2285
2286 Since @code{loop} is a macro, all parsing of the loop language
2287 takes place at byte-compile time; compiled @code{loop}s are just
2288 as efficient as the equivalent @code{while} loops written longhand.
2289
2290 @defspec loop clauses@dots{}
2291 A loop construct consists of a series of @var{clause}s, each
2292 introduced by a symbol like @code{for} or @code{do}.  Clauses
2293 are simply strung together in the argument list of @code{loop},
2294 with minimal extra parentheses.  The various types of clauses
2295 specify initializations, such as the binding of temporary
2296 variables, actions to be taken in the loop, stepping actions,
2297 and final cleanup.
2298
2299 Common Lisp specifies a certain general order of clauses in a
2300 loop:
2301
2302 @example
2303 (loop @var{name-clause}
2304       @var{var-clauses}@dots{}
2305       @var{action-clauses}@dots{})
2306 @end example
2307
2308 The @var{name-clause} optionally gives a name to the implicit
2309 block that surrounds the loop.  By default, the implicit block
2310 is named @code{nil}.  The @var{var-clauses} specify what
2311 variables should be bound during the loop, and how they should
2312 be modified or iterated throughout the course of the loop.  The
2313 @var{action-clauses} are things to be done during the loop, such
2314 as computing, collecting, and returning values.
2315
2316 The Emacs version of the @code{loop} macro is less restrictive about
2317 the order of clauses, but things will behave most predictably if
2318 you put the variable-binding clauses @code{with}, @code{for}, and
2319 @code{repeat} before the action clauses.  As in Common Lisp,
2320 @code{initially} and @code{finally} clauses can go anywhere.
2321
2322 Loops generally return @code{nil} by default, but you can cause
2323 them to return a value by using an accumulation clause like
2324 @code{collect}, an end-test clause like @code{always}, or an
2325 explicit @code{return} clause to jump out of the implicit block.
2326 (Because the loop body is enclosed in an implicit block, you can
2327 also use regular Lisp @code{return} or @code{return-from} to
2328 break out of the loop.)
2329 @end defspec
2330
2331 The following sections give some examples of the Loop Macro in
2332 action, and describe the particular loop clauses in great detail.
2333 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2334 for additional discussion and examples of the @code{loop} macro.
2335
2336 @node Loop Examples, For Clauses, Loop Basics, Loop Facility
2337 @subsection Loop Examples
2338
2339 @noindent
2340 Before listing the full set of clauses that are allowed, let's
2341 look at a few example loops just to get a feel for the @code{loop}
2342 language.
2343
2344 @example
2345 (loop for buf in (buffer-list)
2346       collect (buffer-file-name buf))
2347 @end example
2348
2349 @noindent
2350 This loop iterates over all Emacs buffers, using the list
2351 returned by @code{buffer-list}.  For each buffer @code{buf},
2352 it calls @code{buffer-file-name} and collects the results into
2353 a list, which is then returned from the @code{loop} construct.
2354 The result is a list of the file names of all the buffers in
2355 Emacs' memory.  The words @code{for}, @code{in}, and @code{collect}
2356 are reserved words in the @code{loop} language.
2357
2358 @example
2359 (loop repeat 20 do (insert "Yowsa\n"))
2360 @end example
2361
2362 @noindent
2363 This loop inserts the phrase ``Yowsa'' twenty times in the
2364 current buffer.
2365
2366 @example
2367 (loop until (eobp) do (munch-line) (forward-line 1))
2368 @end example
2369
2370 @noindent
2371 This loop calls @code{munch-line} on every line until the end
2372 of the buffer.  If point is already at the end of the buffer,
2373 the loop exits immediately.
2374
2375 @example
2376 (loop do (munch-line) until (eobp) do (forward-line 1))
2377 @end example
2378
2379 @noindent
2380 This loop is similar to the above one, except that @code{munch-line}
2381 is always called at least once.
2382
2383 @example
2384 (loop for x from 1 to 100
2385       for y = (* x x)
2386       until (>= y 729)
2387       finally return (list x (= y 729)))
2388 @end example
2389
2390 @noindent
2391 This more complicated loop searches for a number @code{x} whose
2392 square is 729.  For safety's sake it only examines @code{x}
2393 values up to 100; dropping the phrase @samp{to 100} would
2394 cause the loop to count upwards with no limit.  The second
2395 @code{for} clause defines @code{y} to be the square of @code{x}
2396 within the loop; the expression after the @code{=} sign is
2397 reevaluated each time through the loop.  The @code{until}
2398 clause gives a condition for terminating the loop, and the
2399 @code{finally} clause says what to do when the loop finishes.
2400 (This particular example was written less concisely than it
2401 could have been, just for the sake of illustration.)
2402
2403 Note that even though this loop contains three clauses (two
2404 @code{for}s and an @code{until}) that would have been enough to
2405 define loops all by themselves, it still creates a single loop
2406 rather than some sort of triple-nested loop.  You must explicitly
2407 nest your @code{loop} constructs if you want nested loops.
2408
2409 @node For Clauses, Iteration Clauses, Loop Examples, Loop Facility
2410 @subsection For Clauses
2411
2412 @noindent
2413 Most loops are governed by one or more @code{for} clauses.
2414 A @code{for} clause simultaneously describes variables to be
2415 bound, how those variables are to be stepped during the loop,
2416 and usually an end condition based on those variables.
2417
2418 The word @code{as} is a synonym for the word @code{for}.  This
2419 word is followed by a variable name, then a word like @code{from}
2420 or @code{across} that describes the kind of iteration desired.
2421 In Common Lisp, the phrase @code{being the} sometimes precedes
2422 the type of iteration; in this package both @code{being} and
2423 @code{the} are optional.  The word @code{each} is a synonym
2424 for @code{the}, and the word that follows it may be singular
2425 or plural:  @samp{for x being the elements of y} or
2426 @samp{for x being each element of y}.  Which form you use
2427 is purely a matter of style.
2428
2429 The variable is bound around the loop as if by @code{let}:
2430
2431 @example
2432 (setq i 'happy)
2433 (loop for i from 1 to 10 do (do-something-with i))
2434 i
2435      @result{} happy
2436 @end example
2437
2438 @table @code
2439 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2440 This type of @code{for} clause creates a counting loop.  Each of
2441 the three sub-terms is optional, though there must be at least one
2442 term so that the clause is marked as a counting clause.
2443
2444 The three expressions are the starting value, the ending value, and
2445 the step value, respectively, of the variable.  The loop counts
2446 upwards by default (@var{expr3} must be positive), from @var{expr1}
2447 to @var{expr2} inclusively.  If you omit the @code{from} term, the
2448 loop counts from zero; if you omit the @code{to} term, the loop
2449 counts forever without stopping (unless stopped by some other
2450 loop clause, of course); if you omit the @code{by} term, the loop
2451 counts in steps of one.
2452
2453 You can replace the word @code{from} with @code{upfrom} or
2454 @code{downfrom} to indicate the direction of the loop.  Likewise,
2455 you can replace @code{to} with @code{upto} or @code{downto}.
2456 For example, @samp{for x from 5 downto 1} executes five times
2457 with @code{x} taking on the integers from 5 down to 1 in turn.
2458 Also, you can replace @code{to} with @code{below} or @code{above},
2459 which are like @code{upto} and @code{downto} respectively except
2460 that they are exclusive rather than inclusive limits:
2461
2462 @example
2463 (loop for x to 10 collect x)
2464      @result{} (0 1 2 3 4 5 6 7 8 9 10)
2465 (loop for x below 10 collect x)
2466      @result{} (0 1 2 3 4 5 6 7 8 9)
2467 @end example
2468
2469 The @code{by} value is always positive, even for downward-counting
2470 loops.  Some sort of @code{from} value is required for downward
2471 loops; @samp{for x downto 5} is not a legal loop clause all by
2472 itself.
2473
2474 @item for @var{var} in @var{list} by @var{function}
2475 This clause iterates @var{var} over all the elements of @var{list},
2476 in turn.  If you specify the @code{by} term, then @var{function}
2477 is used to traverse the list instead of @code{cdr}; it must be a
2478 function taking one argument.  For example:
2479
2480 @example
2481 (loop for x in '(1 2 3 4 5 6) collect (* x x))
2482      @result{} (1 4 9 16 25 36)
2483 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2484      @result{} (1 9 25)
2485 @end example
2486
2487 @item for @var{var} on @var{list} by @var{function}
2488 This clause iterates @var{var} over all the cons cells of @var{list}.
2489
2490 @example
2491 (loop for x on '(1 2 3 4) collect x)
2492      @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2493 @end example
2494
2495 With @code{by}, there is no real reason that the @code{on} expression
2496 must be a list.  For example:
2497
2498 @example
2499 (loop for x on first-animal by 'next-animal collect x)
2500 @end example
2501
2502 @noindent
2503 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2504 the next in the (assumed) sequence of animals, or @code{nil} if
2505 @var{x} was the last animal in the sequence.
2506
2507 @item for @var{var} in-ref @var{list} by @var{function}
2508 This is like a regular @code{in} clause, but @var{var} becomes
2509 a @code{setf}-able ``reference'' onto the elements of the list
2510 rather than just a temporary variable.  For example,
2511
2512 @example
2513 (loop for x in-ref my-list do (incf x))
2514 @end example
2515
2516 @noindent
2517 increments every element of @code{my-list} in place.  This clause
2518 is an extension to standard Common Lisp.
2519
2520 @item for @var{var} across @var{array}
2521 This clause iterates @var{var} over all the elements of @var{array},
2522 which may be a vector or a string.
2523
2524 @example
2525 (loop for x across "aeiou"
2526       do (use-vowel (char-to-string x)))
2527 @end example
2528
2529 @item for @var{var} across-ref @var{array}
2530 This clause iterates over an array, with @var{var} a @code{setf}-able
2531 reference onto the elements; see @code{in-ref} above.
2532
2533 @item for @var{var} being the elements of @var{sequence}
2534 This clause iterates over the elements of @var{sequence}, which may
2535 be a list, vector, or string.  Since the type must be determined
2536 at run-time, this is somewhat less efficient than @code{in} or
2537 @code{across}.  The clause may be followed by the additional term
2538 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2539 the successive indices (starting at 0) of the elements.
2540
2541 This clause type is taken from older versions of the @code{loop} macro,
2542 and is not present in modern Common Lisp.  The @samp{using (sequence ...)}
2543 term of the older macros is not supported.
2544
2545 @item for @var{var} being the elements of-ref @var{sequence}
2546 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2547 reference onto the elements; see @code{in-ref} above.
2548
2549 @item for @var{var} being the symbols [of @var{obarray}]
2550 This clause iterates over symbols, either over all interned symbols
2551 or over all symbols in @var{obarray}.  The loop is executed with
2552 @var{var} bound to each symbol in turn.  The symbols are visited in
2553 an unspecified order.
2554
2555 As an example,
2556
2557 @example
2558 (loop for sym being the symbols
2559       when (fboundp sym)
2560       when (string-match "^map" (symbol-name sym))
2561       collect sym)
2562 @end example
2563
2564 @noindent
2565 returns a list of all the functions whose names begin with @samp{map}.
2566
2567 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2568 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2569
2570 Due to a minor implementation restriction, it will not work to have
2571 more than one @code{for} clause iterating over symbols, hash tables,
2572 keymaps, overlays, or intervals in a given @code{loop}.  Fortunately,
2573 it would rarely if ever be useful to do so.  It @emph{is} legal to mix
2574 one of these types of clauses with other clauses like @code{for ... to}
2575 or @code{while}.
2576
2577 @item for @var{var} being the hash-keys of @var{hash-table}
2578 This clause iterates over the entries in @var{hash-table}.  For each
2579 hash table entry, @var{var} is bound to the entry's key.  If you write
2580 @samp{the hash-values} instead, @var{var} is bound to the values
2581 of the entries.  The clause may be followed by the additional
2582 term @samp{using (hash-values @var{var2})} (where @code{hash-values}
2583 is the opposite word of the word following @code{the}) to cause
2584 @var{var} and @var{var2} to be bound to the two parts of each
2585 hash table entry.
2586
2587 @item for @var{var} being the key-codes of @var{keymap}
2588 This clause iterates over the entries in @var{keymap}.  In GNU Emacs 18
2589 and 19, keymaps are either alists or vectors, and key-codes are integers
2590 or symbols.  In XEmacs, keymaps are a special new data type, and
2591 key-codes are symbols or lists of symbols.  The iteration does not enter
2592 nested keymaps or inherited (parent) keymaps.  You can use @samp{the
2593 key-bindings} to access the commands bound to the keys rather than the
2594 key codes, and you can add a @code{using} clause to access both the
2595 codes and the bindings together.
2596
2597 @item for @var{var} being the key-seqs of @var{keymap}
2598 This clause iterates over all key sequences defined by @var{keymap}
2599 and its nested keymaps, where @var{var} takes on values which are
2600 strings in Emacs 18 or vectors in Emacs 19.  The strings or vectors
2601 are reused for each iteration, so you must copy them if you wish to keep
2602 them permanently.  You can add a @samp{using (key-bindings ...)}
2603 clause to get the command bindings as well.
2604
2605 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2606 This clause iterates over the Emacs 19 ``overlays'' or XEmacs
2607 ``extents'' of a buffer (the clause @code{extents} is synonymous with
2608 @code{overlays}).  Under Emacs 18, this clause iterates zero times.  If
2609 the @code{of} term is omitted, the current buffer is used.  This clause
2610 also accepts optional @samp{from @var{pos}} and @samp{to @var{pos}}
2611 terms, limiting the clause to overlays which overlap the specified
2612 region.
2613
2614 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2615 This clause iterates over all intervals of a buffer with constant
2616 text properties.  The variable @var{var} will be bound to conses
2617 of start and end positions, where one start position is always equal
2618 to the previous end position.  The clause allows @code{of},
2619 @code{from}, @code{to}, and @code{property} terms, where the latter
2620 term restricts the search to just the specified property.  The
2621 @code{of} term may specify either a buffer or a string.  This
2622 clause is useful only in GNU Emacs 19; in other versions, all
2623 buffers and strings consist of a single interval.
2624
2625 @item for @var{var} being the frames
2626 This clause iterates over all frames, i.e., X window system windows
2627 open on Emacs files.  This clause works only under Emacs 19.  The
2628 clause @code{screens} is a synonym for @code{frames}.  The frames
2629 are visited in @code{next-frame} order starting from
2630 @code{selected-frame}.
2631
2632 @item for @var{var} being the windows [of @var{frame}]
2633 This clause iterates over the windows (in the Emacs sense) of
2634 the current frame, or of the specified @var{frame}.  (In Emacs 18
2635 there is only ever one frame, and the @code{of} term is not
2636 allowed there.)
2637
2638 @item for @var{var} being the buffers
2639 This clause iterates over all buffers in Emacs.  It is equivalent
2640 to @samp{for @var{var} in (buffer-list)}.
2641
2642 @item for @var{var} = @var{expr1} then @var{expr2}
2643 This clause does a general iteration.  The first time through
2644 the loop, @var{var} will be bound to @var{expr1}.  On the second
2645 and successive iterations it will be set by evaluating @var{expr2}
2646 (which may refer to the old value of @var{var}).  For example,
2647 these two loops are effectively the same:
2648
2649 @example
2650 (loop for x on my-list by 'cddr do ...)
2651 (loop for x = my-list then (cddr x) while x do ...)
2652 @end example
2653
2654 Note that this type of @code{for} clause does not imply any sort
2655 of terminating condition; the above example combines it with a
2656 @code{while} clause to tell when to end the loop.
2657
2658 If you omit the @code{then} term, @var{expr1} is used both for
2659 the initial setting and for successive settings:
2660
2661 @example
2662 (loop for x = (random) when (> x 0) return x)
2663 @end example
2664
2665 @noindent
2666 This loop keeps taking random numbers from the @code{(random)}
2667 function until it gets a positive one, which it then returns.
2668 @end table
2669
2670 If you include several @code{for} clauses in a row, they are
2671 treated sequentially (as if by @code{let*} and @code{setq}).
2672 You can instead use the word @code{and} to link the clauses,
2673 in which case they are processed in parallel (as if by @code{let}
2674 and @code{psetq}).
2675
2676 @example
2677 (loop for x below 5 for y = nil then x collect (list x y))
2678      @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2679 (loop for x below 5 and y = nil then x collect (list x y))
2680      @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2681 @end example
2682
2683 @noindent
2684 In the first loop, @code{y} is set based on the value of @code{x}
2685 that was just set by the previous clause; in the second loop,
2686 @code{x} and @code{y} are set simultaneously so @code{y} is set
2687 based on the value of @code{x} left over from the previous time
2688 through the loop.
2689
2690 Another feature of the @code{loop} macro is @dfn{destructuring},
2691 similar in concept to the destructuring provided by @code{defmacro}.
2692 The @var{var} part of any @code{for} clause can be given as a list
2693 of variables instead of a single variable.  The values produced
2694 during loop execution must be lists; the values in the lists are
2695 stored in the corresponding variables.
2696
2697 @example
2698 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2699      @result{} (5 9 13)
2700 @end example
2701
2702 In loop destructuring, if there are more values than variables
2703 the trailing values are ignored, and if there are more variables
2704 than values the trailing variables get the value @code{nil}.
2705 If @code{nil} is used as a variable name, the corresponding
2706 values are ignored.  Destructuring may be nested, and dotted
2707 lists of variables like @code{(x . y)} are allowed.
2708
2709 @node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility
2710 @subsection Iteration Clauses
2711
2712 @noindent
2713 Aside from @code{for} clauses, there are several other loop clauses
2714 that control the way the loop operates.  They might be used by
2715 themselves, or in conjunction with one or more @code{for} clauses.
2716
2717 @table @code
2718 @item repeat @var{integer}
2719 This clause simply counts up to the specified number using an
2720 internal temporary variable.  The loops
2721
2722 @example
2723 (loop repeat n do ...)
2724 (loop for temp to n do ...)
2725 @end example
2726
2727 @noindent
2728 are identical except that the second one forces you to choose
2729 a name for a variable you aren't actually going to use.
2730
2731 @item while @var{condition}
2732 This clause stops the loop when the specified condition (any Lisp
2733 expression) becomes @code{nil}.  For example, the following two
2734 loops are equivalent, except for the implicit @code{nil} block
2735 that surrounds the second one:
2736
2737 @example
2738 (while @var{cond} @var{forms}@dots{})
2739 (loop while @var{cond} do @var{forms}@dots{})
2740 @end example
2741
2742 @item until @var{condition}
2743 This clause stops the loop when the specified condition is true,
2744 i.e., non-@code{nil}.
2745
2746 @item always @var{condition}
2747 This clause stops the loop when the specified condition is @code{nil}.
2748 Unlike @code{while}, it stops the loop using @code{return nil} so that
2749 the @code{finally} clauses are not executed.  If all the conditions
2750 were non-@code{nil}, the loop returns @code{t}:
2751
2752 @example
2753 (if (loop for size in size-list always (> size 10))
2754     (some-big-sizes)
2755   (no-big-sizes))
2756 @end example
2757
2758 @item never @var{condition}
2759 This clause is like @code{always}, except that the loop returns
2760 @code{t} if any conditions were false, or @code{nil} otherwise.
2761
2762 @item thereis @var{condition}
2763 This clause stops the loop when the specified form is non-@code{nil};
2764 in this case, it returns that non-@code{nil} value.  If all the
2765 values were @code{nil}, the loop returns @code{nil}.
2766 @end table
2767
2768 @node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility
2769 @subsection Accumulation Clauses
2770
2771 @noindent
2772 These clauses cause the loop to accumulate information about the
2773 specified Lisp @var{form}.  The accumulated result is returned
2774 from the loop unless overridden, say, by a @code{return} clause.
2775
2776 @table @code
2777 @item collect @var{form}
2778 This clause collects the values of @var{form} into a list.  Several
2779 examples of @code{collect} appear elsewhere in this manual.
2780
2781 The word @code{collecting} is a synonym for @code{collect}, and
2782 likewise for the other accumulation clauses.
2783
2784 @item append @var{form}
2785 This clause collects lists of values into a result list using
2786 @code{append}.
2787
2788 @item nconc @var{form}
2789 This clause collects lists of values into a result list by
2790 destructively modifying the lists rather than copying them.
2791
2792 @item concat @var{form}
2793 This clause concatenates the values of the specified @var{form}
2794 into a string.  (It and the following clause are extensions to
2795 standard Common Lisp.)
2796
2797 @item vconcat @var{form}
2798 This clause concatenates the values of the specified @var{form}
2799 into a vector.
2800
2801 @item count @var{form}
2802 This clause counts the number of times the specified @var{form}
2803 evaluates to a non-@code{nil} value.
2804
2805 @item sum @var{form}
2806 This clause accumulates the sum of the values of the specified
2807 @var{form}, which must evaluate to a number.
2808
2809 @item maximize @var{form}
2810 This clause accumulates the maximum value of the specified @var{form},
2811 which must evaluate to a number.  The return value is undefined if
2812 @code{maximize} is executed zero times.
2813
2814 @item minimize @var{form}
2815 This clause accumulates the minimum value of the specified @var{form}.
2816 @end table
2817
2818 Accumulation clauses can be followed by @samp{into @var{var}} to
2819 cause the data to be collected into variable @var{var} (which is
2820 automatically @code{let}-bound during the loop) rather than an
2821 unnamed temporary variable.  Also, @code{into} accumulations do
2822 not automatically imply a return value.  The loop must use some
2823 explicit mechanism, such as @code{finally return}, to return
2824 the accumulated result.
2825
2826 It is legal for several accumulation clauses of the same type to
2827 accumulate into the same place.  From Steele:
2828
2829 @example
2830 (loop for name in '(fred sue alice joe june)
2831       for kids in '((bob ken) () () (kris sunshine) ())
2832       collect name
2833       append kids)
2834      @result{} (fred bob ken sue alice joe kris sunshine june)
2835 @end example
2836
2837 @node Other Clauses, , Accumulation Clauses, Loop Facility
2838 @subsection Other Clauses
2839
2840 @noindent
2841 This section describes the remaining loop clauses.
2842
2843 @table @code
2844 @item with @var{var} = @var{value}
2845 This clause binds a variable to a value around the loop, but
2846 otherwise leaves the variable alone during the loop.  The following
2847 loops are basically equivalent:
2848
2849 @example
2850 (loop with x = 17 do ...)
2851 (let ((x 17)) (loop do ...))
2852 (loop for x = 17 then x do ...)
2853 @end example
2854
2855 Naturally, the variable @var{var} might be used for some purpose
2856 in the rest of the loop.  For example:
2857
2858 @example
2859 (loop for x in my-list  with res = nil  do (push x res)
2860       finally return res)
2861 @end example
2862
2863 This loop inserts the elements of @code{my-list} at the front of
2864 a new list being accumulated in @code{res}, then returns the
2865 list @code{res} at the end of the loop.  The effect is similar
2866 to that of a @code{collect} clause, but the list gets reversed
2867 by virtue of the fact that elements are being pushed onto the
2868 front of @code{res} rather than the end.
2869
2870 If you omit the @code{=} term, the variable is initialized to
2871 @code{nil}.  (Thus the @samp{= nil} in the above example is
2872 unnecessary.)
2873
2874 Bindings made by @code{with} are sequential by default, as if
2875 by @code{let*}.  Just like @code{for} clauses, @code{with} clauses
2876 can be linked with @code{and} to cause the bindings to be made by
2877 @code{let} instead.
2878
2879 @item if @var{condition} @var{clause}
2880 This clause executes the following loop clause only if the specified
2881 condition is true.  The following @var{clause} should be an accumulation,
2882 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2883 Several clauses may be linked by separating them with @code{and}.
2884 These clauses may be followed by @code{else} and a clause or clauses
2885 to execute if the condition was false.  The whole construct may
2886 optionally be followed by the word @code{end} (which may be used to
2887 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2888
2889 The actual non-@code{nil} value of the condition form is available
2890 by the name @code{it} in the ``then'' part.  For example:
2891
2892 @example
2893 (setq funny-numbers '(6 13 -1))
2894      @result{} (6 13 -1)
2895 (loop for x below 10
2896       if (oddp x)
2897         collect x into odds
2898         and if (memq x funny-numbers) return (cdr it) end
2899       else
2900         collect x into evens
2901       finally return (vector odds evens))
2902      @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2903 (setq funny-numbers '(6 7 13 -1))
2904      @result{} (6 7 13 -1)
2905 (loop <@r{same thing again}>)
2906      @result{} (13 -1)
2907 @end example
2908
2909 Note the use of @code{and} to put two clauses into the ``then''
2910 part, one of which is itself an @code{if} clause.  Note also that
2911 @code{end}, while normally optional, was necessary here to make
2912 it clear that the @code{else} refers to the outermost @code{if}
2913 clause.  In the first case, the loop returns a vector of lists
2914 of the odd and even values of @var{x}.  In the second case, the
2915 odd number 7 is one of the @code{funny-numbers} so the loop
2916 returns early; the actual returned value is based on the result
2917 of the @code{memq} call.
2918
2919 @item when @var{condition} @var{clause}
2920 This clause is just a synonym for @code{if}.
2921
2922 @item unless @var{condition} @var{clause}
2923 The @code{unless} clause is just like @code{if} except that the
2924 sense of the condition is reversed.
2925
2926 @item named @var{name}
2927 This clause gives a name other than @code{nil} to the implicit
2928 block surrounding the loop.  The @var{name} is the symbol to be
2929 used as the block name.
2930
2931 @item initially [do] @var{forms}...
2932 This keyword introduces one or more Lisp forms which will be
2933 executed before the loop itself begins (but after any variables
2934 requested by @code{for} or @code{with} have been bound to their
2935 initial values).  @code{initially} clauses can appear anywhere;
2936 if there are several, they are executed in the order they appear
2937 in the loop.  The keyword @code{do} is optional.
2938
2939 @item finally [do] @var{forms}...
2940 This introduces Lisp forms which will be executed after the loop
2941 finishes (say, on request of a @code{for} or @code{while}).
2942 @code{initially} and @code{finally} clauses may appear anywhere
2943 in the loop construct, but they are executed (in the specified
2944 order) at the beginning or end, respectively, of the loop.
2945
2946 @item finally return @var{form}
2947 This says that @var{form} should be executed after the loop
2948 is done to obtain a return value.  (Without this, or some other
2949 clause like @code{collect} or @code{return}, the loop will simply
2950 return @code{nil}.)  Variables bound by @code{for}, @code{with},
2951 or @code{into} will still contain their final values when @var{form}
2952 is executed.
2953
2954 @item do @var{forms}...
2955 The word @code{do} may be followed by any number of Lisp expressions
2956 which are executed as an implicit @code{progn} in the body of the
2957 loop.  Many of the examples in this section illustrate the use of
2958 @code{do}.
2959
2960 @item return @var{form}
2961 This clause causes the loop to return immediately.  The following
2962 Lisp form is evaluated to give the return value of the @code{loop}
2963 form.  The @code{finally} clauses, if any, are not executed.
2964 Of course, @code{return} is generally used inside an @code{if} or
2965 @code{unless}, as its use in a top-level loop clause would mean
2966 the loop would never get to ``loop'' more than once.
2967
2968 The clause @samp{return @var{form}} is equivalent to
2969 @samp{do (return @var{form})} (or @code{return-from} if the loop
2970 was named).  The @code{return} clause is implemented a bit more
2971 efficiently, though.
2972 @end table
2973
2974 While there is no high-level way to add user extensions to @code{loop}
2975 (comparable to @code{defsetf} for @code{setf}, say), this package
2976 does offer two properties called @code{cl-loop-handler} and
2977 @code{cl-loop-for-handler} which are functions to be called when
2978 a given symbol is encountered as a top-level loop clause or
2979 @code{for} clause, respectively.  Consult the source code in
2980 file @file{cl-macs.el} for details.
2981
2982 This package's @code{loop} macro is compatible with that of Common
2983 Lisp, except that a few features are not implemented:  @code{loop-finish}
2984 and data-type specifiers.  Naturally, the @code{for} clauses which
2985 iterate over keymaps, overlays, intervals, frames, windows, and
2986 buffers are Emacs-specific extensions.
2987
2988 @node Multiple Values, , Loop Facility, Control Structure
2989 @section Multiple Values
2990
2991 @noindent
2992 Common Lisp functions can return zero or more results.  Emacs Lisp
2993 functions, by contrast, always return exactly one result.  This
2994 package makes no attempt to emulate Common Lisp multiple return
2995 values; Emacs versions of Common Lisp functions that return more
2996 than one value either return just the first value (as in
2997 @code{compiler-macroexpand}) or return a list of values (as in
2998 @code{get-setf-method}).  This package @emph{does} define placeholders
2999 for the Common Lisp functions that work with multiple values, but
3000 in Emacs Lisp these functions simply operate on lists instead.
3001 The @code{values} form, for example, is a synonym for @code{list}
3002 in Emacs.
3003
3004 @defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
3005 This form evaluates @var{values-form}, which must return a list of
3006 values.  It then binds the @var{var}s to these respective values,
3007 as if by @code{let}, and then executes the body @var{forms}.
3008 If there are more @var{var}s than values, the extra @var{var}s
3009 are bound to @code{nil}.  If there are fewer @var{var}s than
3010 values, the excess values are ignored.
3011 @end defspec
3012
3013 @defspec multiple-value-setq (var@dots{}) form
3014 This form evaluates @var{form}, which must return a list of values.
3015 It then sets the @var{var}s to these respective values, as if by
3016 @code{setq}.  Extra @var{var}s or values are treated the same as
3017 in @code{multiple-value-bind}.
3018 @end defspec
3019
3020 The older Quiroz package attempted a more faithful (but still
3021 imperfect) emulation of Common Lisp multiple values.  The old
3022 method ``usually'' simulated true multiple values quite well,
3023 but under certain circumstances would leave spurious return
3024 values in memory where a later, unrelated @code{multiple-value-bind}
3025 form would see them.
3026
3027 Since a perfect emulation is not feasible in Emacs Lisp, this
3028 package opts to keep it as simple and predictable as possible.
3029
3030 @node Macros, Declarations, Control Structure, Top
3031 @chapter Macros
3032
3033 @noindent
3034 This package implements the various Common Lisp features of
3035 @code{defmacro}, such as destructuring, @code{&environment},
3036 and @code{&body}.  Top-level @code{&whole} is not implemented
3037 for @code{defmacro} due to technical difficulties.
3038 @xref{Argument Lists}.
3039
3040 Destructuring is made available to the user by way of the
3041 following macro:
3042
3043 @defspec destructuring-bind arglist expr forms@dots{}
3044 This macro expands to code which executes @var{forms}, with
3045 the variables in @var{arglist} bound to the list of values
3046 returned by @var{expr}.  The @var{arglist} can include all
3047 the features allowed for @code{defmacro} argument lists,
3048 including destructuring.  (The @code{&environment} keyword
3049 is not allowed.)  The macro expansion will signal an error
3050 if @var{expr} returns a list of the wrong number of arguments
3051 or with incorrect keyword arguments.
3052 @end defspec
3053
3054 This package also includes the Common Lisp @code{define-compiler-macro}
3055 facility, which allows you to define compile-time expansions and
3056 optimizations for your functions.
3057
3058 @defspec define-compiler-macro name arglist forms@dots{}
3059 This form is similar to @code{defmacro}, except that it only expands
3060 calls to @var{name} at compile-time; calls processed by the Lisp
3061 interpreter are not expanded, nor are they expanded by the
3062 @code{macroexpand} function.
3063
3064 The argument list may begin with a @code{&whole} keyword and a
3065 variable.  This variable is bound to the macro-call form itself,
3066 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
3067 If the macro expander returns this form unchanged, then the
3068 compiler treats it as a normal function call.  This allows
3069 compiler macros to work as optimizers for special cases of a
3070 function, leaving complicated cases alone.
3071
3072 For example, here is a simplified version of a definition that
3073 appears as a standard part of this package:
3074
3075 @example
3076 (define-compiler-macro member* (&whole form a list &rest keys)
3077   (if (and (null keys)
3078            (eq (car-safe a) 'quote)
3079            (not (floatp-safe (cadr a))))
3080       (list 'memq a list)
3081     form))
3082 @end example
3083
3084 @noindent
3085 This definition causes @code{(member* @var{a} @var{list})} to change
3086 to a call to the faster @code{memq} in the common case where @var{a}
3087 is a non-floating-point constant; if @var{a} is anything else, or
3088 if there are any keyword arguments in the call, then the original
3089 @code{member*} call is left intact.  (The actual compiler macro
3090 for @code{member*} optimizes a number of other cases, including
3091 common @code{:test} predicates.)
3092 @end defspec
3093
3094 @defun compiler-macroexpand form
3095 This function is analogous to @code{macroexpand}, except that it
3096 expands compiler macros rather than regular macros.  It returns
3097 @var{form} unchanged if it is not a call to a function for which
3098 a compiler macro has been defined, or if that compiler macro
3099 decided to punt by returning its @code{&whole} argument.  Like
3100 @code{macroexpand}, it expands repeatedly until it reaches a form
3101 for which no further expansion is possible.
3102 @end defun
3103
3104 @xref{Macro Bindings}, for descriptions of the @code{macrolet}
3105 and @code{symbol-macrolet} forms for making ``local'' macro
3106 definitions.
3107
3108 @node Declarations, Symbols, Macros, Top
3109 @chapter Declarations
3110
3111 @noindent
3112 Common Lisp includes a complex and powerful ``declaration''
3113 mechanism that allows you to give the compiler special hints
3114 about the types of data that will be stored in particular variables,
3115 and about the ways those variables and functions will be used.  This
3116 package defines versions of all the Common Lisp declaration forms:
3117 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
3118 and @code{the}.
3119
3120 Most of the Common Lisp declarations are not currently useful in
3121 Emacs Lisp, as the byte-code system provides little opportunity
3122 to benefit from type information, and @code{special} declarations
3123 are redundant in a fully dynamically-scoped Lisp.  A few
3124 declarations are meaningful when the optimizing Emacs 19 byte
3125 compiler is being used, however.  Under the earlier non-optimizing
3126 compiler, these declarations will effectively be ignored.
3127
3128 @defun proclaim decl-spec
3129 This function records a ``global'' declaration specified by
3130 @var{decl-spec}.  Since @code{proclaim} is a function, @var{decl-spec}
3131 is evaluated and thus should normally be quoted.
3132 @end defun
3133
3134 @defspec declaim decl-specs@dots{}
3135 This macro is like @code{proclaim}, except that it takes any number
3136 of @var{decl-spec} arguments, and the arguments are unevaluated and
3137 unquoted.  The @code{declaim} macro also puts an @code{(eval-when
3138 (compile load eval) ...)} around the declarations so that they will
3139 be registered at compile-time as well as at run-time.  (This is vital,
3140 since normally the declarations are meant to influence the way the
3141 compiler treats the rest of the file that contains the @code{declaim}
3142 form.)
3143 @end defspec
3144
3145 @defspec declare decl-specs@dots{}
3146 This macro is used to make declarations within functions and other
3147 code.  Common Lisp allows declarations in various locations, generally
3148 at the beginning of any of the many ``implicit @code{progn}s''
3149 throughout Lisp syntax, such as function bodies, @code{let} bodies,
3150 etc.  Currently the only declaration understood by @code{declare}
3151 is @code{special}.
3152 @end defspec
3153
3154 @defspec locally declarations@dots{} forms@dots{}
3155 In this package, @code{locally} is no different from @code{progn}.
3156 @end defspec
3157
3158 @defspec the type form
3159 Type information provided by @code{the} is ignored in this package;
3160 in other words, @code{(the @var{type} @var{form})} is equivalent
3161 to @var{form}.  Future versions of the optimizing byte-compiler may
3162 make use of this information.
3163
3164 For example, @code{mapcar} can map over both lists and arrays.  It is
3165 hard for the compiler to expand @code{mapcar} into an in-line loop
3166 unless it knows whether the sequence will be a list or an array ahead
3167 of time.  With @code{(mapcar 'car (the vector foo))}, a future
3168 compiler would have enough information to expand the loop in-line.
3169 For now, Emacs Lisp will treat the above code as exactly equivalent
3170 to @code{(mapcar 'car foo)}.
3171 @end defspec
3172
3173 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
3174 @code{declare} should be a list beginning with a symbol that says
3175 what kind of declaration it is.  This package currently understands
3176 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
3177 and @code{warn} declarations.  (The @code{warn} declaration is an
3178 extension of standard Common Lisp.)  Other Common Lisp declarations,
3179 such as @code{type} and @code{ftype}, are silently ignored.
3180
3181 @table @code
3182 @item special
3183 Since all variables in Emacs Lisp are ``special'' (in the Common
3184 Lisp sense), @code{special} declarations are only advisory.  They
3185 simply tell the optimizing byte compiler that the specified
3186 variables are intentionally being referred to without being
3187 bound in the body of the function.  The compiler normally emits
3188 warnings for such references, since they could be typographical
3189 errors for references to local variables.
3190
3191 The declaration @code{(declare (special @var{var1} @var{var2}))} is
3192 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
3193 optimizing compiler, or to nothing at all in older compilers (which
3194 do not warn for non-local references).
3195
3196 In top-level contexts, it is generally better to write
3197 @code{(defvar @var{var})} than @code{(declaim (special @var{var}))},
3198 since @code{defvar} makes your intentions clearer.  But the older
3199 byte compilers can not handle @code{defvar}s appearing inside of
3200 functions, while @code{(declare (special @var{var}))} takes care
3201 to work correctly with all compilers.
3202
3203 @item inline
3204 The @code{inline} @var{decl-spec} lists one or more functions
3205 whose bodies should be expanded ``in-line'' into calling functions
3206 whenever the compiler is able to arrange for it.  For example,
3207 the Common Lisp function @code{cadr} is declared @code{inline}
3208 by this package so that the form @code{(cadr @var{x})} will
3209 expand directly into @code{(car (cdr @var{x}))} when it is called
3210 in user functions, for a savings of one (relatively expensive)
3211 function call.
3212
3213 The following declarations are all equivalent.  Note that the
3214 @code{defsubst} form is a convenient way to define a function
3215 and declare it inline all at once, but it is available only in
3216 Emacs 19.
3217
3218 @example
3219 (declaim (inline foo bar))
3220 (eval-when (compile load eval) (proclaim '(inline foo bar)))
3221 (proclaim-inline foo bar)   ; XEmacs only
3222 (defsubst foo (...) ...)    ; instead of defun; Emacs 19 only
3223 @end example
3224
3225 @strong{Please note:}  This declaration remains in effect after the
3226 containing source file is done.  It is correct to use it to
3227 request that a function you have defined should be inlined,
3228 but it is impolite to use it to request inlining of an external
3229 function.
3230
3231 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
3232 before a particular call to a function to cause just that call to
3233 be inlined; the current byte compilers provide no way to implement
3234 this, so @code{(declare (inline @dots{}))} is currently ignored by
3235 this package.
3236
3237 @item notinline
3238 The @code{notinline} declaration lists functions which should
3239 not be inlined after all; it cancels a previous @code{inline}
3240 declaration.
3241
3242 @item optimize
3243 This declaration controls how much optimization is performed by
3244 the compiler.  Naturally, it is ignored by the earlier non-optimizing
3245 compilers.
3246
3247 The word @code{optimize} is followed by any number of lists like
3248 @code{(speed 3)} or @code{(safety 2)}.  Common Lisp defines several
3249 optimization ``qualities''; this package ignores all but @code{speed}
3250 and @code{safety}.  The value of a quality should be an integer from
3251 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
3252 The default level for both qualities is 1.
3253
3254 In this package, with the Emacs 19 optimizing compiler, the
3255 @code{speed} quality is tied to the @code{byte-compile-optimize}
3256 flag, which is set to @code{nil} for @code{(speed 0)} and to
3257 @code{t} for higher settings; and the @code{safety} quality is
3258 tied to the @code{byte-compile-delete-errors} flag, which is
3259 set to @code{t} for @code{(safety 3)} and to @code{nil} for all
3260 lower settings.  (The latter flag controls whether the compiler
3261 is allowed to optimize out code whose only side-effect could
3262 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3263 @code{bar} when it is not known whether @code{foo} will be bound
3264 at run-time.)
3265
3266 Note that even compiling with @code{(safety 0)}, the Emacs
3267 byte-code system provides sufficient checking to prevent real
3268 harm from being done.  For example, barring serious bugs in
3269 Emacs itself, Emacs will not crash with a segmentation fault
3270 just because of an error in a fully-optimized Lisp program.
3271
3272 The @code{optimize} declaration is normally used in a top-level
3273 @code{proclaim} or @code{declaim} in a file; Common Lisp allows
3274 it to be used with @code{declare} to set the level of optimization
3275 locally for a given form, but this will not work correctly with the
3276 current version of the optimizing compiler.  (The @code{declare}
3277 will set the new optimization level, but that level will not
3278 automatically be unset after the enclosing form is done.)
3279
3280 @item warn
3281 This declaration controls what sorts of warnings are generated
3282 by the byte compiler.  Again, only the optimizing compiler
3283 generates warnings.  The word @code{warn} is followed by any
3284 number of ``warning qualities,'' similar in form to optimization
3285 qualities.  The currently supported warning types are
3286 @code{redefine}, @code{callargs}, @code{unresolved}, and
3287 @code{free-vars}; in the current system, a value of 0 will
3288 disable these warnings and any higher value will enable them.
3289 See the documentation for the optimizing byte compiler for details.
3290 @end table
3291
3292 @node Symbols, Numbers, Declarations, Top
3293 @chapter Symbols
3294
3295 @noindent
3296 This package defines several symbol-related features that were
3297 missing from Emacs Lisp.
3298
3299 @menu
3300 * Property Lists::       `getf', `remf'
3301 * Creating Symbols::     `gensym', `gentemp'
3302 @end menu
3303
3304 @node Property Lists, Creating Symbols, Symbols, Symbols
3305 @section Property Lists
3306
3307 @noindent
3308 These functions augment the standard Emacs Lisp functions @code{get}
3309 and @code{put} for operating on properties attached to objects.
3310 There are also functions for working with property lists as
3311 first-class data structures not attached to particular objects.
3312
3313 @defun getf place property &optional default
3314 This function scans the list @var{place} as if it were a property
3315 list, i.e., a list of alternating property names and values.  If
3316 an even-numbered element of @var{place} is found which is @code{eq}
3317 to @var{property}, the following odd-numbered element is returned.
3318 Otherwise, @var{default} is returned (or @code{nil} if no default
3319 is given).
3320
3321 In particular,
3322
3323 @example
3324 (get sym prop)  @equiv{}  (getf (symbol-plist sym) prop)
3325 @end example
3326
3327 It is legal to use @code{getf} as a @code{setf} place, in which case
3328 its @var{place} argument must itself be a legal @code{setf} place.
3329 The @var{default} argument, if any, is ignored in this context.
3330 The effect is to change (via @code{setcar}) the value cell in the
3331 list that corresponds to @var{property}, or to cons a new property-value
3332 pair onto the list if the property is not yet present.
3333
3334 @example
3335 (put sym prop val)  @equiv{}  (setf (getf (symbol-plist sym) prop) val)
3336 @end example
3337
3338 The @code{get} function is also @code{setf}-able.  The fact that
3339 @code{default} is ignored can sometimes be useful:
3340
3341 @example
3342 (incf (get 'foo 'usage-count 0))
3343 @end example
3344
3345 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3346 if it exists, or set to 1 (an incremented 0) otherwise.
3347
3348 When not used as a @code{setf} form, @code{getf} is just a regular
3349 function and its @var{place} argument can actually be any Lisp
3350 expression.
3351 @end defun
3352
3353 @defspec remf place property
3354 This macro removes the property-value pair for @var{property} from
3355 the property list stored at @var{place}, which is any @code{setf}-able
3356 place expression.  It returns true if the property was found.  Note
3357 that if @var{property} happens to be first on the list, this will
3358 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3359 whereas if it occurs later, this simply uses @code{setcdr} to splice
3360 out the property and value cells.
3361 @end defspec
3362
3363 @iftex
3364 @secno=2
3365 @end iftex
3366
3367 @node Creating Symbols, , Property Lists, Symbols
3368 @section Creating Symbols
3369
3370 @noindent
3371 These functions create unique symbols, typically for use as
3372 temporary variables.
3373
3374 @defun gensym &optional x
3375 This function creates a new, uninterned symbol (using @code{make-symbol})
3376 with a unique name.  (The name of an uninterned symbol is relevant
3377 only if the symbol is printed.)  By default, the name is generated
3378 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3379 @samp{G1002}, etc.  If the optional argument @var{x} is a string, that
3380 string is used as a prefix instead of @samp{G}.  Uninterned symbols
3381 are used in macro expansions for temporary variables, to ensure that
3382 their names will not conflict with ``real'' variables in the user's
3383 code.
3384 @end defun
3385
3386 @defvar *gensym-counter*
3387 This variable holds the counter used to generate @code{gensym} names.
3388 It is incremented after each use by @code{gensym}.  In Common Lisp
3389 this is initialized with 0, but this package initializes it with a
3390 random (time-dependent) value to avoid trouble when two files that
3391 each used @code{gensym} in their compilation are loaded together.
3392
3393 @strong{XEmacs note:} As of XEmacs 21.0, an uninterned symbol remains
3394 uninterned even after being dumped to bytecode.  Older versions of Emacs
3395 didn't distinguish the printed representation of interned and uninterned
3396 symbols, so their names had to be treated more carefully.
3397 @end defvar
3398
3399 @defun gentemp &optional x
3400 This function is like @code{gensym}, except that it produces a new
3401 @emph{interned} symbol.  If the symbol that is generated already
3402 exists, the function keeps incrementing the counter and trying
3403 again until a new symbol is generated.
3404 @end defun
3405
3406 The Quiroz @file{cl.el} package also defined a @code{defkeyword}
3407 form for creating self-quoting keyword symbols.  This package
3408 automatically creates all keywords that are called for by
3409 @code{&key} argument specifiers, and discourages the use of
3410 keywords as data unrelated to keyword arguments, so the
3411 @code{defkeyword} form has been discontinued.
3412
3413 @iftex
3414 @chapno=11
3415 @end iftex
3416
3417 @node Numbers, Sequences, Symbols, Top
3418 @chapter Numbers
3419
3420 @noindent
3421 This section defines a few simple Common Lisp operations on numbers
3422 which were left out of Emacs Lisp.
3423
3424 @menu
3425 * Predicates on Numbers::       `plusp', `oddp', `floatp-safe', etc.
3426 * Numerical Functions::         `abs', `expt', `floor*', etc.
3427 * Random Numbers::              `random*', `make-random-state'
3428 * Implementation Parameters::   `most-positive-fixnum', `most-positive-float'
3429 @end menu
3430
3431 @iftex
3432 @secno=1
3433 @end iftex
3434
3435 @node Predicates on Numbers, Numerical Functions, Numbers, Numbers
3436 @section Predicates on Numbers
3437
3438 @noindent
3439 These functions return @code{t} if the specified condition is
3440 true of the numerical argument, or @code{nil} otherwise.
3441
3442 @defun plusp number
3443 This predicate tests whether @var{number} is positive.  It is an
3444 error if the argument is not a number.
3445 @end defun
3446
3447 @defun minusp number
3448 This predicate tests whether @var{number} is negative.  It is an
3449 error if the argument is not a number.
3450 @end defun
3451
3452 @defun oddp integer
3453 This predicate tests whether @var{integer} is odd.  It is an
3454 error if the argument is not an integer.
3455 @end defun
3456
3457 @defun evenp integer
3458 This predicate tests whether @var{integer} is even.  It is an
3459 error if the argument is not an integer.
3460 @end defun
3461
3462 @defun floatp-safe object
3463 This predicate tests whether @var{object} is a floating-point
3464 number.  On systems that support floating-point, this is equivalent
3465 to @code{floatp}.  On other systems, this always returns @code{nil}.
3466 @end defun
3467
3468 @iftex
3469 @secno=3
3470 @end iftex
3471
3472 @node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers
3473 @section Numerical Functions
3474
3475 @noindent
3476 These functions perform various arithmetic operations on numbers.
3477
3478 @defun abs number
3479 This function returns the absolute value of @var{number}.  (Newer
3480 versions of Emacs provide this as a built-in function; this package
3481 defines @code{abs} only for Emacs 18 versions which don't provide
3482 it as a primitive.)
3483 @end defun
3484
3485 @defun expt base power
3486 This function returns @var{base} raised to the power of @var{number}.
3487 (Newer versions of Emacs provide this as a built-in function; this
3488 package defines @code{expt} only for Emacs 18 versions which don't
3489 provide it as a primitive.)
3490 @end defun
3491
3492 @defun gcd &rest integers
3493 This function returns the Greatest Common Divisor of the arguments.
3494 For one argument, it returns the absolute value of that argument.
3495 For zero arguments, it returns zero.
3496 @end defun
3497
3498 @defun lcm &rest integers
3499 This function returns the Least Common Multiple of the arguments.
3500 For one argument, it returns the absolute value of that argument.
3501 For zero arguments, it returns one.
3502 @end defun
3503
3504 @defun isqrt integer
3505 This function computes the ``integer square root'' of its integer
3506 argument, i.e., the greatest integer less than or equal to the true
3507 square root of the argument.
3508 @end defun
3509
3510 @defun floor* number &optional divisor
3511 This function implements the Common Lisp @code{floor} function.
3512 It is called @code{floor*} to avoid name conflicts with the
3513 simpler @code{floor} function built-in to Emacs 19.
3514
3515 With one argument, @code{floor*} returns a list of two numbers:
3516 The argument rounded down (toward minus infinity) to an integer,
3517 and the ``remainder'' which would have to be added back to the
3518 first return value to yield the argument again.  If the argument
3519 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3520 If the argument is an Emacs 19 floating-point number, the first
3521 result is a Lisp integer and the second is a Lisp float between
3522 0 (inclusive) and 1 (exclusive).
3523
3524 With two arguments, @code{floor*} divides @var{number} by
3525 @var{divisor}, and returns the floor of the quotient and the
3526 corresponding remainder as a list of two numbers.  If
3527 @code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3528 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3529 between 0 (inclusive) and @var{r} (exclusive).  Also, note
3530 that @code{(floor* @var{x})} is exactly equivalent to
3531 @code{(floor* @var{x} 1)}.
3532
3533 This function is entirely compatible with Common Lisp's @code{floor}
3534 function, except that it returns the two results in a list since
3535 Emacs Lisp does not support multiple-valued functions.
3536 @end defun
3537
3538 @defun ceiling* number &optional divisor
3539 This function implements the Common Lisp @code{ceiling} function,
3540 which is analogous to @code{floor} except that it rounds the
3541 argument or quotient of the arguments up toward plus infinity.
3542 The remainder will be between 0 and minus @var{r}.
3543 @end defun
3544
3545 @defun truncate* number &optional divisor
3546 This function implements the Common Lisp @code{truncate} function,
3547 which is analogous to @code{floor} except that it rounds the
3548 argument or quotient of the arguments toward zero.  Thus it is
3549 equivalent to @code{floor*} if the argument or quotient is
3550 positive, or to @code{ceiling*} otherwise.  The remainder has
3551 the same sign as @var{number}.
3552 @end defun
3553
3554 @defun round* number &optional divisor
3555 This function implements the Common Lisp @code{round} function,
3556 which is analogous to @code{floor} except that it rounds the
3557 argument or quotient of the arguments to the nearest integer.
3558 In the case of a tie (the argument or quotient is exactly
3559 halfway between two integers), it rounds to the even integer.
3560 @end defun
3561
3562 @defun mod* number divisor
3563 This function returns the same value as the second return value
3564 of @code{floor}.
3565 @end defun
3566
3567 @defun rem* number divisor
3568 This function returns the same value as the second return value
3569 of @code{truncate}.
3570 @end defun
3571
3572 These definitions are compatible with those in the Quiroz
3573 @file{cl.el} package, except that this package appends @samp{*}
3574 to certain function names to avoid conflicts with existing
3575 Emacs 19 functions, and that the mechanism for returning
3576 multiple values is different.
3577
3578 @iftex
3579 @secno=8
3580 @end iftex
3581
3582 @node Random Numbers, Implementation Parameters, Numerical Functions, Numbers
3583 @section Random Numbers
3584
3585 @noindent
3586 This package also provides an implementation of the Common Lisp
3587 random number generator.  It uses its own additive-congruential
3588 algorithm, which is much more likely to give statistically clean
3589 random numbers than the simple generators supplied by many
3590 operating systems.
3591
3592 @defun random* number &optional state
3593 This function returns a random nonnegative number less than
3594 @var{number}, and of the same type (either integer or floating-point).
3595 The @var{state} argument should be a @code{random-state} object
3596 which holds the state of the random number generator.  The
3597 function modifies this state object as a side effect.  If
3598 @var{state} is omitted, it defaults to the variable
3599 @code{*random-state*}, which contains a pre-initialized
3600 @code{random-state} object.
3601 @end defun
3602
3603 @defvar *random-state*
3604 This variable contains the system ``default'' @code{random-state}
3605 object, used for calls to @code{random*} that do not specify an
3606 alternative state object.  Since any number of programs in the
3607 Emacs process may be accessing @code{*random-state*} in interleaved
3608 fashion, the sequence generated from this variable will be
3609 irreproducible for all intents and purposes.
3610 @end defvar
3611
3612 @defun make-random-state &optional state
3613 This function creates or copies a @code{random-state} object.
3614 If @var{state} is omitted or @code{nil}, it returns a new copy of
3615 @code{*random-state*}.  This is a copy in the sense that future
3616 sequences of calls to @code{(random* @var{n})} and
3617 @code{(random* @var{n} @var{s})} (where @var{s} is the new
3618 random-state object) will return identical sequences of random
3619 numbers.
3620
3621 If @var{state} is a @code{random-state} object, this function
3622 returns a copy of that object.  If @var{state} is @code{t}, this
3623 function returns a new @code{random-state} object seeded from the
3624 date and time.  As an extension to Common Lisp, @var{state} may also
3625 be an integer in which case the new object is seeded from that
3626 integer; each different integer seed will result in a completely
3627 different sequence of random numbers.
3628
3629 It is legal to print a @code{random-state} object to a buffer or
3630 file and later read it back with @code{read}.  If a program wishes
3631 to use a sequence of pseudo-random numbers which can be reproduced
3632 later for debugging, it can call @code{(make-random-state t)} to
3633 get a new sequence, then print this sequence to a file.  When the
3634 program is later rerun, it can read the original run's random-state
3635 from the file.
3636 @end defun
3637
3638 @defun random-state-p object
3639 This predicate returns @code{t} if @var{object} is a
3640 @code{random-state} object, or @code{nil} otherwise.
3641 @end defun
3642
3643 @node Implementation Parameters, , Random Numbers, Numbers
3644 @section Implementation Parameters
3645
3646 @noindent
3647 This package defines several useful constants having to with numbers.
3648
3649 @defvar most-positive-fixnum
3650 This constant equals the largest value a Lisp integer can hold.
3651 It is typically @code{2^23-1} or @code{2^25-1}.
3652 @end defvar
3653
3654 @defvar most-negative-fixnum
3655 This constant equals the smallest (most negative) value a Lisp
3656 integer can hold.
3657 @end defvar
3658
3659 The following parameters have to do with floating-point numbers.
3660 This package determines their values by exercising the computer's
3661 floating-point arithmetic in various ways.  Because this operation
3662 might be slow, the code for initializing them is kept in a separate
3663 function that must be called before the parameters can be used.
3664
3665 @defun cl-float-limits
3666 This function makes sure that the Common Lisp floating-point
3667 parameters like @code{most-positive-float} have been initialized.
3668 Until it is called, these parameters will be @code{nil}.  If this
3669 version of Emacs does not support floats (e.g., most versions of
3670 Emacs 18), the parameters will remain @code{nil}.  If the parameters
3671 have already been initialized, the function returns immediately.
3672
3673 The algorithm makes assumptions that will be valid for most modern
3674 machines, but will fail if the machine's arithmetic is extremely
3675 unusual, e.g., decimal.
3676 @end defun
3677
3678 Since true Common Lisp supports up to four different floating-point
3679 precisions, it has families of constants like
3680 @code{most-positive-single-float}, @code{most-positive-double-float},
3681 @code{most-positive-long-float}, and so on.  Emacs has only one
3682 floating-point precision, so this package omits the precision word
3683 from the constants' names.
3684
3685 @defvar most-positive-float
3686 This constant equals the largest value a Lisp float can hold.
3687 For those systems whose arithmetic supports infinities, this is
3688 the largest @emph{finite} value.  For IEEE machines, the value
3689 is approximately @code{1.79e+308}.
3690 @end defvar
3691
3692 @defvar most-negative-float
3693 This constant equals the most-negative value a Lisp float can hold.
3694 (It is assumed to be equal to @code{(- most-positive-float)}.)
3695 @end defvar
3696
3697 @defvar least-positive-float
3698 This constant equals the smallest Lisp float value greater than zero.
3699 For IEEE machines, it is about @code{4.94e-324} if denormals are
3700 supported or @code{2.22e-308} if not.
3701 @end defvar
3702
3703 @defvar least-positive-normalized-float
3704 This constant equals the smallest @emph{normalized} Lisp float greater
3705 than zero, i.e., the smallest value for which IEEE denormalization
3706 will not result in a loss of precision.  For IEEE machines, this
3707 value is about @code{2.22e-308}.  For machines that do not support
3708 the concept of denormalization and gradual underflow, this constant
3709 will always equal @code{least-positive-float}.
3710 @end defvar
3711
3712 @defvar least-negative-float
3713 This constant is the negative counterpart of @code{least-positive-float}.
3714 @end defvar
3715
3716 @defvar least-negative-normalized-float
3717 This constant is the negative counterpart of
3718 @code{least-positive-normalized-float}.
3719 @end defvar
3720
3721 @defvar float-epsilon
3722 This constant is the smallest positive Lisp float that can be added
3723 to 1.0 to produce a distinct value.  Adding a smaller number to 1.0
3724 will yield 1.0 again due to roundoff.  For IEEE machines, epsilon
3725 is about @code{2.22e-16}.
3726 @end defvar
3727
3728 @defvar float-negative-epsilon
3729 This is the smallest positive value that can be subtracted from
3730 1.0 to produce a distinct value.  For IEEE machines, it is about
3731 @code{1.11e-16}.
3732 @end defvar
3733
3734 @iftex
3735 @chapno=13
3736 @end iftex
3737
3738 @node Sequences, Lists, Numbers, Top
3739 @chapter Sequences
3740
3741 @noindent
3742 Common Lisp defines a number of functions that operate on
3743 @dfn{sequences}, which are either lists, strings, or vectors.
3744 Emacs Lisp includes a few of these, notably @code{elt} and
3745 @code{length}; this package defines most of the rest.
3746
3747 @menu
3748 * Sequence Basics::          Arguments shared by all sequence functions
3749 * Mapping over Sequences::   `mapcar*', `mapcan', `map', `every', etc.
3750 * Sequence Functions::       `subseq', `remove*', `substitute', etc.
3751 * Searching Sequences::      `find', `position', `count', `search', etc.
3752 * Sorting Sequences::        `sort*', `stable-sort', `merge'
3753 @end menu
3754
3755 @node Sequence Basics, Mapping over Sequences, Sequences, Sequences
3756 @section Sequence Basics
3757
3758 @noindent
3759 Many of the sequence functions take keyword arguments; @pxref{Argument
3760 Lists}.  All keyword arguments are optional and, if specified,
3761 may appear in any order.
3762
3763 The @code{:key} argument should be passed either @code{nil}, or a
3764 function of one argument.  This key function is used as a filter
3765 through which the elements of the sequence are seen; for example,
3766 @code{(find x y :key 'car)} is similar to @code{(assoc* x y)}:
3767 It searches for an element of the list whose @code{car} equals
3768 @code{x}, rather than for an element which equals @code{x} itself.
3769 If @code{:key} is omitted or @code{nil}, the filter is effectively
3770 the identity function.
3771
3772 The @code{:test} and @code{:test-not} arguments should be either
3773 @code{nil}, or functions of two arguments.  The test function is
3774 used to compare two sequence elements, or to compare a search value
3775 with sequence elements.  (The two values are passed to the test
3776 function in the same order as the original sequence function
3777 arguments from which they are derived, or, if they both come from
3778 the same sequence, in the same order as they appear in that sequence.)
3779 The @code{:test} argument specifies a function which must return
3780 true (non-@code{nil}) to indicate a match; instead, you may use
3781 @code{:test-not} to give a function which returns @emph{false} to
3782 indicate a match.  The default test function is @code{:test 'eql}.
3783
3784 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3785 arguments also come in @code{-if} and @code{-if-not} varieties,
3786 where a @var{predicate} function is passed instead of @var{item},
3787 and sequence elements match if the predicate returns true on them
3788 (or false in the case of @code{-if-not}).  For example:
3789
3790 @example
3791 (remove* 0 seq :test '=)  @equiv{}  (remove-if 'zerop seq)
3792 @end example
3793
3794 @noindent
3795 to remove all zeros from sequence @code{seq}.
3796
3797 Some operations can work on a subsequence of the argument sequence;
3798 these function take @code{:start} and @code{:end} arguments which
3799 default to zero and the length of the sequence, respectively.
3800 Only elements between @var{start} (inclusive) and @var{end}
3801 (exclusive) are affected by the operation.  The @var{end} argument
3802 may be passed @code{nil} to signify the length of the sequence;
3803 otherwise, both @var{start} and @var{end} must be integers, with
3804 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3805 If the function takes two sequence arguments, the limits are
3806 defined by keywords @code{:start1} and @code{:end1} for the first,
3807 and @code{:start2} and @code{:end2} for the second.
3808
3809 A few functions accept a @code{:from-end} argument, which, if
3810 non-@code{nil}, causes the operation to go from right-to-left
3811 through the sequence instead of left-to-right, and a @code{:count}
3812 argument, which specifies an integer maximum number of elements
3813 to be removed or otherwise processed.
3814
3815 The sequence functions make no guarantees about the order in
3816 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3817 are called on various elements.  Therefore, it is a bad idea to depend
3818 on side effects of these functions.  For example, @code{:from-end}
3819 may cause the sequence to be scanned actually in reverse, or it may
3820 be scanned forwards but computing a result ``as if'' it were scanned
3821 backwards.  (Some functions, like @code{mapcar*} and @code{every},
3822 @emph{do} specify exactly the order in which the function is called
3823 so side effects are perfectly acceptable in those cases.)
3824
3825 Strings in GNU Emacs 19 may contain ``text properties'' as well
3826 as character data.  Except as noted, it is undefined whether or
3827 not text properties are preserved by sequence functions.  For
3828 example, @code{(remove* ?A @var{str})} may or may not preserve
3829 the properties of the characters copied from @var{str} into the
3830 result.
3831
3832 @node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences
3833 @section Mapping over Sequences
3834
3835 @noindent
3836 These functions ``map'' the function you specify over the elements
3837 of lists or arrays.  They are all variations on the theme of the
3838 built-in function @code{mapcar}.
3839
3840 @defun mapcar* function seq &rest more-seqs
3841 This function calls @var{function} on successive parallel sets of
3842 elements from its argument sequences.  Given a single @var{seq}
3843 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3844 it calls the function with the first elements of each of the sequences
3845 as the @var{n} arguments to yield the first element of the result
3846 list, then with the second elements, and so on.  The mapping stops as
3847 soon as the shortest sequence runs out.  The argument sequences may
3848 be any mixture of lists, strings, and vectors; the return sequence
3849 is always a list.
3850
3851 Common Lisp's @code{mapcar} accepts multiple arguments but works
3852 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3853 argument.  This package's @code{mapcar*} works as a compatible
3854 superset of both.
3855 @end defun
3856
3857 @defun map result-type function seq &rest more-seqs
3858 This function maps @var{function} over the argument sequences,
3859 just like @code{mapcar*}, but it returns a sequence of type
3860 @var{result-type} rather than a list.  @var{result-type} must
3861 be one of the following symbols: @code{vector}, @code{string},
3862 @code{list} (in which case the effect is the same as for
3863 @code{mapcar*}), or @code{nil} (in which case the results are
3864 thrown away and @code{map} returns @code{nil}).
3865 @end defun
3866
3867 @defun maplist function list &rest more-lists
3868 This function calls @var{function} on each of its argument lists,
3869 then on the @code{cdr}s of those lists, and so on, until the
3870 shortest list runs out.  The results are returned in the form
3871 of a list.  Thus, @code{maplist} is like @code{mapcar*} except
3872 that it passes in the list pointers themselves rather than the
3873 @code{car}s of the advancing pointers.
3874 @end defun
3875
3876 @defun mapc function seq &rest more-seqs
3877 This function is like @code{mapcar*}, except that the values
3878 returned by @var{function} are ignored and thrown away rather
3879 than being collected into a list.  The return value of @code{mapc}
3880 is @var{seq}, the first sequence.
3881 @end defun
3882
3883 @defun mapl function list &rest more-lists
3884 This function is like @code{maplist}, except that it throws away
3885 the values returned by @var{function}.
3886 @end defun
3887
3888 @defun mapcan function seq &rest more-seqs
3889 This function is like @code{mapcar*}, except that it concatenates
3890 the return values (which must be lists) using @code{nconc},
3891 rather than simply collecting them into a list.
3892 @end defun
3893
3894 @defun mapcon function list &rest more-lists
3895 This function is like @code{maplist}, except that it concatenates
3896 the return values using @code{nconc}.
3897 @end defun
3898
3899 @defun some predicate seq &rest more-seqs
3900 This function calls @var{predicate} on each element of @var{seq}
3901 in turn; if @var{predicate} returns a non-@code{nil} value,
3902 @code{some} returns that value, otherwise it returns @code{nil}.
3903 Given several sequence arguments, it steps through the sequences
3904 in parallel until the shortest one runs out, just as in
3905 @code{mapcar*}.  You can rely on the left-to-right order in which
3906 the elements are visited, and on the fact that mapping stops
3907 immediately as soon as @var{predicate} returns non-@code{nil}.
3908 @end defun
3909
3910 @defun every predicate seq &rest more-seqs
3911 This function calls @var{predicate} on each element of the sequence(s)
3912 in turn; it returns @code{nil} as soon as @var{predicate} returns
3913 @code{nil} for any element, or @code{t} if the predicate was true
3914 for all elements.
3915 @end defun
3916
3917 @defun notany predicate seq &rest more-seqs
3918 This function calls @var{predicate} on each element of the sequence(s)
3919 in turn; it returns @code{nil} as soon as @var{predicate} returns
3920 a non-@code{nil} value for any element, or @code{t} if the predicate
3921 was @code{nil} for all elements.
3922 @end defun
3923
3924 @defun notevery predicate seq &rest more-seqs
3925 This function calls @var{predicate} on each element of the sequence(s)
3926 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3927 returns @code{nil} for any element, or @code{t} if the predicate was
3928 true for all elements.
3929 @end defun
3930
3931 @defun reduce function seq @t{&key :from-end :start :end :initial-value :key}
3932 This function combines the elements of @var{seq} using an associative
3933 binary operation.  Suppose @var{function} is @code{*} and @var{seq} is
3934 the list @code{(2 3 4 5)}.  The first two elements of the list are
3935 combined with @code{(* 2 3) = 6}; this is combined with the next
3936 element, @code{(* 6 4) = 24}, and that is combined with the final
3937 element: @code{(* 24 5) = 120}.  Note that the @code{*} function happens
3938 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3939 an explicit call to @code{reduce}.
3940
3941 If @code{:from-end} is true, the reduction is right-associative instead
3942 of left-associative:
3943
3944 @example
3945 (reduce '- '(1 2 3 4))
3946      @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3947 (reduce '- '(1 2 3 4) :from-end t)
3948      @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3949 @end example
3950
3951 If @code{:key} is specified, it is a function of one argument which
3952 is called on each of the sequence elements in turn.
3953
3954 If @code{:initial-value} is specified, it is effectively added to the
3955 front (or rear in the case of @code{:from-end}) of the sequence.
3956 The @code{:key} function is @emph{not} applied to the initial value.
3957
3958 If the sequence, including the initial value, has exactly one element
3959 then that element is returned without ever calling @var{function}.
3960 If the sequence is empty (and there is no initial value), then
3961 @var{function} is called with no arguments to obtain the return value.
3962 @end defun
3963
3964 All of these mapping operations can be expressed conveniently in
3965 terms of the @code{loop} macro.  In compiled code, @code{loop} will
3966 be faster since it generates the loop as in-line code with no
3967 function calls.
3968
3969 @node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences
3970 @section Sequence Functions
3971
3972 @noindent
3973 This section describes a number of Common Lisp functions for
3974 operating on sequences.
3975
3976 @defun subseq sequence start &optional end
3977 This function returns a given subsequence of the argument
3978 @var{sequence}, which may be a list, string, or vector.
3979 The indices @var{start} and @var{end} must be in range, and
3980 @var{start} must be no greater than @var{end}.  If @var{end}
3981 is omitted, it defaults to the length of the sequence.  The
3982 return value is always a copy; it does not share structure
3983 with @var{sequence}.
3984
3985 As an extension to Common Lisp, @var{start} and/or @var{end}
3986 may be negative, in which case they represent a distance back
3987 from the end of the sequence.  This is for compatibility with
3988 Emacs' @code{substring} function.  Note that @code{subseq} is
3989 the @emph{only} sequence function that allows negative
3990 @var{start} and @var{end}.
3991
3992 You can use @code{setf} on a @code{subseq} form to replace a
3993 specified range of elements with elements from another sequence.
3994 The replacement is done as if by @code{replace}, described below.
3995 @end defun
3996
3997 @defun concatenate result-type &rest seqs
3998 This function concatenates the argument sequences together to
3999 form a result sequence of type @var{result-type}, one of the
4000 symbols @code{vector}, @code{string}, or @code{list}.  The
4001 arguments are always copied, even in cases such as
4002 @code{(concatenate 'list '(1 2 3))} where the result is
4003 identical to an argument.
4004 @end defun
4005
4006 @defun fill seq item @t{&key :start :end}
4007 This function fills the elements of the sequence (or the specified
4008 part of the sequence) with the value @var{item}.
4009 @end defun
4010
4011 @defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
4012 This function copies part of @var{seq2} into part of @var{seq1}.
4013 The sequence @var{seq1} is not stretched or resized; the amount
4014 of data copied is simply the shorter of the source and destination
4015 (sub)sequences.  The function returns @var{seq1}.
4016
4017 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
4018 will work correctly even if the regions indicated by the start
4019 and end arguments overlap.  However, if @var{seq1} and @var{seq2}
4020 are lists which share storage but are not @code{eq}, and the
4021 start and end arguments specify overlapping regions, the effect
4022 is undefined.
4023 @end defun
4024
4025 @defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end}
4026 This returns a copy of @var{seq} with all elements matching
4027 @var{item} removed.  The result may share storage with or be
4028 @code{eq} to @var{seq} in some circumstances, but the original
4029 @var{seq} will not be modified.  The @code{:test}, @code{:test-not},
4030 and @code{:key} arguments define the matching test that is used;
4031 by default, elements @code{eql} to @var{item} are removed.  The
4032 @code{:count} argument specifies the maximum number of matching
4033 elements that can be removed (only the leftmost @var{count} matches
4034 are removed).  The @code{:start} and @code{:end} arguments specify
4035 a region in @var{seq} in which elements will be removed; elements
4036 outside that region are not matched or removed.  The @code{:from-end}
4037 argument, if true, says that elements should be deleted from the
4038 end of the sequence rather than the beginning (this matters only
4039 if @var{count} was also specified).
4040 @end defun
4041
4042 @defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end}
4043 This deletes all elements of @var{seq} which match @var{item}.
4044 It is a destructive operation.  Since Emacs Lisp does not support
4045 stretchable strings or vectors, this is the same as @code{remove*}
4046 for those sequence types.  On lists, @code{remove*} will copy the
4047 list if necessary to preserve the original list, whereas
4048 @code{delete*} will splice out parts of the argument list.
4049 Compare @code{append} and @code{nconc}, which are analogous
4050 non-destructive and destructive list operations in Emacs Lisp.
4051 @end defun
4052
4053 @findex remove-if
4054 @findex remove-if-not
4055 @findex delete-if
4056 @findex delete-if-not
4057 The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
4058 @code{delete-if}, and @code{delete-if-not} are defined similarly.
4059
4060 @defun delete item list
4061 This MacLisp-compatible function deletes from @var{list} all elements
4062 which are @code{equal} to @var{item}.  The @code{delete} function is
4063 built-in to Emacs 19; this package defines it equivalently in Emacs 18.
4064 @end defun
4065
4066 @defun remove item list
4067 This function removes from @var{list} all elements which are
4068 @code{equal} to @var{item}.  This package defines it for symmetry
4069 with @code{delete}, even though @code{remove} is not built-in to
4070 Emacs 19.
4071 @end defun
4072
4073 @defun remq item list
4074 This function removes from @var{list} all elements which are
4075 @code{eq} to @var{item}.  This package defines it for symmetry
4076 with @code{delq}, even though @code{remq} is not built-in to
4077 Emacs 19.
4078 @end defun
4079
4080 @defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
4081 This function returns a copy of @var{seq} with duplicate elements
4082 removed.  Specifically, if two elements from the sequence match
4083 according to the @code{:test}, @code{:test-not}, and @code{:key}
4084 arguments, only the rightmost one is retained.  If @code{:from-end}
4085 is true, the leftmost one is retained instead.  If @code{:start} or
4086 @code{:end} is specified, only elements within that subsequence are
4087 examined or removed.
4088 @end defun
4089
4090 @defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
4091 This function deletes duplicate elements from @var{seq}.  It is
4092 a destructive version of @code{remove-duplicates}.
4093 @end defun
4094
4095 @defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
4096 This function returns a copy of @var{seq}, with all elements
4097 matching @var{old} replaced with @var{new}.  The @code{:count},
4098 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
4099 used to limit the number of substitutions made.
4100 @end defun
4101
4102 @defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
4103 This is a destructive version of @code{substitute}; it performs
4104 the substitution using @code{setcar} or @code{aset} rather than
4105 by returning a changed copy of the sequence.
4106 @end defun
4107
4108 @findex substitute-if
4109 @findex substitute-if-not
4110 @findex nsubstitute-if
4111 @findex nsubstitute-if-not
4112 The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if},
4113 and @code{nsubstitute-if-not} functions are defined similarly.  For
4114 these, a @var{predicate} is given in place of the @var{old} argument.
4115
4116 @node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences
4117 @section Searching Sequences
4118
4119 @noindent
4120 These functions search for elements or subsequences in a sequence.
4121 (See also @code{member*} and @code{assoc*}; @pxref{Lists}.)
4122
4123 @defun find item seq @t{&key :test :test-not :key :start :end :from-end}
4124 This function searches @var{seq} for an element matching @var{item}.
4125 If it finds a match, it returns the matching element.  Otherwise,
4126 it returns @code{nil}.  It returns the leftmost match, unless
4127 @code{:from-end} is true, in which case it returns the rightmost
4128 match.  The @code{:start} and @code{:end} arguments may be used to
4129 limit the range of elements that are searched.
4130 @end defun
4131
4132 @defun position item seq @t{&key :test :test-not :key :start :end :from-end}
4133 This function is like @code{find}, except that it returns the
4134 integer position in the sequence of the matching item rather than
4135 the item itself.  The position is relative to the start of the
4136 sequence as a whole, even if @code{:start} is non-zero.  The function
4137 returns @code{nil} if no matching element was found.
4138 @end defun
4139
4140 @defun count item seq @t{&key :test :test-not :key :start :end}
4141 This function returns the number of elements of @var{seq} which
4142 match @var{item}.  The result is always a nonnegative integer.
4143 @end defun
4144
4145 @findex find-if
4146 @findex find-if-not
4147 @findex position-if
4148 @findex position-if-not
4149 @findex count-if
4150 @findex count-if-not
4151 The @code{find-if}, @code{find-if-not}, @code{position-if},
4152 @code{position-if-not}, @code{count-if}, and @code{count-if-not}
4153 functions are defined similarly.
4154
4155 @defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
4156 This function compares the specified parts of @var{seq1} and
4157 @var{seq2}.  If they are the same length and the corresponding
4158 elements match (according to @code{:test}, @code{:test-not},
4159 and @code{:key}), the function returns @code{nil}.  If there is
4160 a mismatch, the function returns the index (relative to @var{seq1})
4161 of the first mismatching element.  This will be the leftmost pair of
4162 elements which do not match, or the position at which the shorter of
4163 the two otherwise-matching sequences runs out.
4164
4165 If @code{:from-end} is true, then the elements are compared from right
4166 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
4167 If the sequences differ, then one plus the index of the rightmost
4168 difference (relative to @var{seq1}) is returned.
4169
4170 An interesting example is @code{(mismatch str1 str2 :key 'upcase)},
4171 which compares two strings case-insensitively.
4172 @end defun
4173
4174 @defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
4175 This function searches @var{seq2} for a subsequence that matches
4176 @var{seq1} (or part of it specified by @code{:start1} and
4177 @code{:end1}.)  Only matches which fall entirely within the region
4178 defined by @code{:start2} and @code{:end2} will be considered.
4179 The return value is the index of the leftmost element of the
4180 leftmost match, relative to the start of @var{seq2}, or @code{nil}
4181 if no matches were found.  If @code{:from-end} is true, the
4182 function finds the @emph{rightmost} matching subsequence.
4183 @end defun
4184
4185 @node Sorting Sequences, , Searching Sequences, Sequences
4186 @section Sorting Sequences
4187
4188 @defun sort* seq predicate @t{&key :key}
4189 This function sorts @var{seq} into increasing order as determined
4190 by using @var{predicate} to compare pairs of elements.  @var{predicate}
4191 should return true (non-@code{nil}) if and only if its first argument
4192 is less than (not equal to) its second argument.  For example,
4193 @code{<} and @code{string-lessp} are suitable predicate functions
4194 for sorting numbers and strings, respectively; @code{>} would sort
4195 numbers into decreasing rather than increasing order.
4196
4197 This function differs from Emacs' built-in @code{sort} in that it
4198 can operate on any type of sequence, not just lists.  Also, it
4199 accepts a @code{:key} argument which is used to preprocess data
4200 fed to the @var{predicate} function.  For example,
4201
4202 @example
4203 (setq data (sort data 'string-lessp :key 'downcase))
4204 @end example
4205
4206 @noindent
4207 sorts @var{data}, a sequence of strings, into increasing alphabetical
4208 order without regard to case.  A @code{:key} function of @code{car}
4209 would be useful for sorting association lists.
4210
4211 The @code{sort*} function is destructive; it sorts lists by actually
4212 rearranging the @code{cdr} pointers in suitable fashion.
4213 @end defun
4214
4215 @defun stable-sort seq predicate @t{&key :key}
4216 This function sorts @var{seq} @dfn{stably}, meaning two elements
4217 which are equal in terms of @var{predicate} are guaranteed not to
4218 be rearranged out of their original order by the sort.
4219
4220 In practice, @code{sort*} and @code{stable-sort} are equivalent
4221 in Emacs Lisp because the underlying @code{sort} function is
4222 stable by default.  However, this package reserves the right to
4223 use non-stable methods for @code{sort*} in the future.
4224 @end defun
4225
4226 @defun merge type seq1 seq2 predicate @t{&key :key}
4227 This function merges two sequences @var{seq1} and @var{seq2} by
4228 interleaving their elements.  The result sequence, of type @var{type}
4229 (in the sense of @code{concatenate}), has length equal to the sum
4230 of the lengths of the two input sequences.  The sequences may be
4231 modified destructively.  Order of elements within @var{seq1} and
4232 @var{seq2} is preserved in the interleaving; elements of the two
4233 sequences are compared by @var{predicate} (in the sense of
4234 @code{sort}) and the lesser element goes first in the result.
4235 When elements are equal, those from @var{seq1} precede those from
4236 @var{seq2} in the result.  Thus, if @var{seq1} and @var{seq2} are
4237 both sorted according to @var{predicate}, then the result will be
4238 a merged sequence which is (stably) sorted according to
4239 @var{predicate}.
4240 @end defun
4241
4242 @node Lists, Hash Tables, Sequences, Top
4243 @chapter Lists
4244
4245 @noindent
4246 The functions described here operate on lists.
4247
4248 @menu
4249 * List Functions::                `caddr', `first', `last', `list*', etc.
4250 * Substitution of Expressions::   `subst', `sublis', etc.
4251 * Lists as Sets::                 `member*', `adjoin', `union', etc.
4252 * Association Lists::             `assoc*', `rassoc*', `acons', `pairlis'
4253 @end menu
4254
4255 @node List Functions, Substitution of Expressions, Lists, Lists
4256 @section List Functions
4257
4258 @noindent
4259 This section describes a number of simple operations on lists,
4260 i.e., chains of cons cells.
4261
4262 @defun caddr x
4263 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
4264 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
4265 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
4266 All of these functions are @code{setf}-able, and calls to them
4267 are expanded inline by the byte-compiler for maximum efficiency.
4268 @end defun
4269
4270 @defun first x
4271 This function is a synonym for @code{(car @var{x})}.  Likewise,
4272 the functions @code{second}, @code{third}, @dots{}, through
4273 @code{tenth} return the given element of the list @var{x}.
4274 @end defun
4275
4276 @defun rest x
4277 This function is a synonym for @code{(cdr @var{x})}.
4278 @end defun
4279
4280 @defun endp x
4281 Common Lisp defines this function to act like @code{null}, but
4282 signalling an error if @code{x} is neither a @code{nil} nor a
4283 cons cell.  This package simply defines @code{endp} as a synonym
4284 for @code{null}.
4285 @end defun
4286
4287 @defun list-length x
4288 This function returns the length of list @var{x}, exactly like
4289 @code{(length @var{x})}, except that if @var{x} is a circular
4290 list (where the cdr-chain forms a loop rather than terminating
4291 with @code{nil}), this function returns @code{nil}.  (The regular
4292 @code{length} function would get stuck if given a circular list.)
4293 @end defun
4294
4295 @defun last x &optional n
4296 This function returns the last cons, or the @var{n}th-to-last cons,
4297 of the list @var{x}.  If @var{n} is omitted it defaults to 1.
4298 The ``last cons'' means the first cons cell of the list whose
4299 @code{cdr} is not another cons cell.  (For normal lists, the
4300 @code{cdr} of the last cons will be @code{nil}.)  This function
4301 returns @code{nil} if @var{x} is @code{nil} or shorter than
4302 @var{n}.  Note that the last @emph{element} of the list is
4303 @code{(car (last @var{x}))}.
4304 @end defun
4305
4306 @defun butlast x &optional n
4307 This function returns the list @var{x} with the last element,
4308 or the last @var{n} elements, removed.  If @var{n} is greater
4309 than zero it makes a copy of the list so as not to damage the
4310 original list.  In general, @code{(append (butlast @var{x} @var{n})
4311 (last @var{x} @var{n}))} will return a list equal to @var{x}.
4312 @end defun
4313
4314 @defun nbutlast x &optional n
4315 This is a version of @code{butlast} that works by destructively
4316 modifying the @code{cdr} of the appropriate element, rather than
4317 making a copy of the list.
4318 @end defun
4319
4320 @defun list* arg &rest others
4321 This function constructs a list of its arguments.  The final
4322 argument becomes the @code{cdr} of the last cell constructed.
4323 Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to
4324 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4325 @code{(list* @var{a} @var{b} nil)} is equivalent to
4326 @code{(list @var{a} @var{b})}.
4327
4328 (Note that this function really is called @code{list*} in Common
4329 Lisp; it is not a name invented for this package like @code{member*}
4330 or @code{defun*}.)
4331 @end defun
4332
4333 @defun ldiff list sublist
4334 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4335 one of the cons cells of @var{list}, then this function returns
4336 a copy of the part of @var{list} up to but not including
4337 @var{sublist}.  For example, @code{(ldiff x (cddr x))} returns
4338 the first two elements of the list @code{x}.  The result is a
4339 copy; the original @var{list} is not modified.  If @var{sublist}
4340 is not a sublist of @var{list}, a copy of the entire @var{list}
4341 is returned.
4342 @end defun
4343
4344 @defun copy-list list
4345 This function returns a copy of the list @var{list}.  It copies
4346 dotted lists like @code{(1 2 . 3)} correctly.
4347 @end defun
4348
4349 @defun copy-tree x &optional vecp
4350 This function returns a copy of the tree of cons cells @var{x}.
4351 Unlike @code{copy-sequence} (and its alias @code{copy-list}),
4352 which copies only along the @code{cdr} direction, this function
4353 copies (recursively) along both the @code{car} and the @code{cdr}
4354 directions.  If @var{x} is not a cons cell, the function simply
4355 returns @var{x} unchanged.  If the optional @var{vecp} argument
4356 is true, this function copies vectors (recursively) as well as
4357 cons cells.
4358 @end defun
4359
4360 @defun tree-equal x y @t{&key :test :test-not :key}
4361 This function compares two trees of cons cells.  If @var{x} and
4362 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4363 compared recursively.  If neither @var{x} nor @var{y} is a cons
4364 cell, they are compared by @code{eql}, or according to the
4365 specified test.  The @code{:key} function, if specified, is
4366 applied to the elements of both trees.  @xref{Sequences}.
4367 @end defun
4368
4369 @iftex
4370 @secno=3
4371 @end iftex
4372
4373 @node Substitution of Expressions, Lists as Sets, List Functions, Lists
4374 @section Substitution of Expressions
4375
4376 @noindent
4377 These functions substitute elements throughout a tree of cons
4378 cells.  (@xref{Sequence Functions}, for the @code{substitute}
4379 function, which works on just the top-level elements of a list.)
4380
4381 @defun subst new old tree @t{&key :test :test-not :key}
4382 This function substitutes occurrences of @var{old} with @var{new}
4383 in @var{tree}, a tree of cons cells.  It returns a substituted
4384 tree, which will be a copy except that it may share storage with
4385 the argument @var{tree} in parts where no substitutions occurred.
4386 The original @var{tree} is not modified.  This function recurses
4387 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4388 of the component cons cells.  If @var{old} is itself a cons cell,
4389 then matching cells in the tree are substituted as usual without
4390 recursively substituting in that cell.  Comparisons with @var{old}
4391 are done according to the specified test (@code{eql} by default).
4392 The @code{:key} function is applied to the elements of the tree
4393 but not to @var{old}.
4394 @end defun
4395
4396 @defun nsubst new old tree @t{&key :test :test-not :key}
4397 This function is like @code{subst}, except that it works by
4398 destructive modification (by @code{setcar} or @code{setcdr})
4399 rather than copying.
4400 @end defun
4401
4402 @findex subst-if
4403 @findex subst-if-not
4404 @findex nsubst-if
4405 @findex nsubst-if-not
4406 The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and
4407 @code{nsubst-if-not} functions are defined similarly.
4408
4409 @defun sublis alist tree @t{&key :test :test-not :key}
4410 This function is like @code{subst}, except that it takes an
4411 association list @var{alist} of @var{old}-@var{new} pairs.
4412 Each element of the tree (after applying the @code{:key}
4413 function, if any), is compared with the @code{car}s of
4414 @var{alist}; if it matches, it is replaced by the corresponding
4415 @code{cdr}.
4416 @end defun
4417
4418 @defun nsublis alist tree @t{&key :test :test-not :key}
4419 This is a destructive version of @code{sublis}.
4420 @end defun
4421
4422 @node Lists as Sets, Association Lists, Substitution of Expressions, Lists
4423 @section Lists as Sets
4424
4425 @noindent
4426 These functions perform operations on lists which represent sets
4427 of elements.
4428
4429 @defun member item list
4430 This MacLisp-compatible function searches @var{list} for an element
4431 which is @code{equal} to @var{item}.  The @code{member} function is
4432 built-in to Emacs 19; this package defines it equivalently in Emacs 18.
4433 See the following function for a Common-Lisp compatible version.
4434 @end defun
4435
4436 @defun member* item list @t{&key :test :test-not :key}
4437 This function searches @var{list} for an element matching @var{item}.
4438 If a match is found, it returns the cons cell whose @code{car} was
4439 the matching element.  Otherwise, it returns @code{nil}.  Elements
4440 are compared by @code{eql} by default; you can use the @code{:test},
4441 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4442 @xref{Sequences}.
4443
4444 Note that this function's name is suffixed by @samp{*} to avoid
4445 the incompatible @code{member} function defined in Emacs 19.
4446 (That function uses @code{equal} for comparisons; it is equivalent
4447 to @code{(member* @var{item} @var{list} :test 'equal)}.)
4448 @end defun
4449
4450 @findex member-if
4451 @findex member-if-not
4452 The @code{member-if} and @code{member-if-not} functions
4453 analogously search for elements which satisfy a given predicate.
4454
4455 @defun tailp sublist list
4456 This function returns @code{t} if @var{sublist} is a sublist of
4457 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4458 any of its @code{cdr}s.
4459 @end defun
4460
4461 @defun adjoin item list @t{&key :test :test-not :key}
4462 This function conses @var{item} onto the front of @var{list},
4463 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4464 is not already present on the list (as determined by @code{member*}).
4465 If a @code{:key} argument is specified, it is applied to
4466 @var{item} as well as to the elements of @var{list} during
4467 the search, on the reasoning that @var{item} is ``about'' to
4468 become part of the list.
4469 @end defun
4470
4471 @defun union list1 list2 @t{&key :test :test-not :key}
4472 This function combines two lists which represent sets of items,
4473 returning a list that represents the union of those two sets.
4474 The result list will contain all items which appear in @var{list1}
4475 or @var{list2}, and no others.  If an item appears in both
4476 @var{list1} and @var{list2} it will be copied only once.  If
4477 an item is duplicated in @var{list1} or @var{list2}, it is
4478 undefined whether or not that duplication will survive in the
4479 result list.  The order of elements in the result list is also
4480 undefined.
4481 @end defun
4482
4483 @defun nunion list1 list2 @t{&key :test :test-not :key}
4484 This is a destructive version of @code{union}; rather than copying,
4485 it tries to reuse the storage of the argument lists if possible.
4486 @end defun
4487
4488 @defun intersection list1 list2 @t{&key :test :test-not :key}
4489 This function computes the intersection of the sets represented
4490 by @var{list1} and @var{list2}.  It returns the list of items
4491 which appear in both @var{list1} and @var{list2}.
4492 @end defun
4493
4494 @defun nintersection list1 list2 @t{&key :test :test-not :key}
4495 This is a destructive version of @code{intersection}.  It
4496 tries to reuse storage of @var{list1} rather than copying.
4497 It does @emph{not} reuse the storage of @var{list2}.
4498 @end defun
4499
4500 @defun set-difference list1 list2 @t{&key :test :test-not :key}
4501 This function computes the ``set difference'' of @var{list1}
4502 and @var{list2}, i.e., the set of elements that appear in
4503 @var{list1} but @emph{not} in @var{list2}.
4504 @end defun
4505
4506 @defun nset-difference list1 list2 @t{&key :test :test-not :key}
4507 This is a destructive @code{set-difference}, which will try
4508 to reuse @var{list1} if possible.
4509 @end defun
4510
4511 @defun set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4512 This function computes the ``set exclusive or'' of @var{list1}
4513 and @var{list2}, i.e., the set of elements that appear in
4514 exactly one of @var{list1} and @var{list2}.
4515 @end defun
4516
4517 @defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4518 This is a destructive @code{set-exclusive-or}, which will try
4519 to reuse @var{list1} and @var{list2} if possible.
4520 @end defun
4521
4522 @defun subsetp list1 list2 @t{&key :test :test-not :key}
4523 This function checks whether @var{list1} represents a subset
4524 of @var{list2}, i.e., whether every element of @var{list1}
4525 also appears in @var{list2}.
4526 @end defun
4527
4528 @node Association Lists, , Lists as Sets, Lists
4529 @section Association Lists
4530
4531 @noindent
4532 An @dfn{association list} is a list representing a mapping from
4533 one set of values to another; any list whose elements are cons
4534 cells is an association list.
4535
4536 @defun assoc* item a-list @t{&key :test :test-not :key}
4537 This function searches the association list @var{a-list} for an
4538 element whose @code{car} matches (in the sense of @code{:test},
4539 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4540 a given @var{item}.  It returns the matching element, if any,
4541 otherwise @code{nil}.  It ignores elements of @var{a-list} which
4542 are not cons cells.  (This corresponds to the behavior of
4543 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4544 @code{assoc} ignores @code{nil}s but considers any other non-cons
4545 elements of @var{a-list} to be an error.)
4546 @end defun
4547
4548 @defun rassoc* item a-list @t{&key :test :test-not :key}
4549 This function searches for an element whose @code{cdr} matches
4550 @var{item}.  If @var{a-list} represents a mapping, this applies
4551 the inverse of the mapping to @var{item}.
4552 @end defun
4553
4554 @defun rassoc item a-list
4555 This function searches like @code{rassoc*} with a @code{:test}
4556 argument of @code{equal}.  It is analogous to Emacs Lisp's
4557 standard @code{assoc} function, which derives from the MacLisp
4558 rather than the Common Lisp tradition.
4559 @end defun
4560
4561 @findex assoc-if
4562 @findex assoc-if-not
4563 @findex rassoc-if
4564 @findex rassoc-if-not
4565 The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if},
4566 and @code{rassoc-if-not} functions are defined similarly.
4567
4568 Two simple functions for constructing association lists are:
4569
4570 @defun acons key value alist
4571 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4572 @end defun
4573
4574 @defun pairlis keys values &optional alist
4575 This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values})
4576 @var{alist})}.
4577 @end defun
4578
4579 @node Hash Tables, Structures, Lists, Top
4580 @chapter Hash Tables
4581
4582 @noindent
4583 Hash tables are now implemented directly in the C code and documented in
4584 @ref{Hash Tables,,, lispref, XEmacs Lisp Reference Manual}.
4585
4586 @ignore
4587 A @dfn{hash table} is a data structure that maps ``keys'' onto
4588 ``values.''  Keys and values can be arbitrary Lisp data objects.
4589 Hash tables have the property that the time to search for a given
4590 key is roughly constant; simpler data structures like association
4591 lists take time proportional to the number of entries in the list.
4592
4593 @defun make-hash-table @t{&key :test :size}
4594 This function creates and returns a hash-table object whose
4595 function for comparing elements is @code{:test} (@code{eql}
4596 by default), and which is allocated to fit about @code{:size}
4597 elements.  The @code{:size} argument is purely advisory; the
4598 table will stretch automatically if you store more elements in
4599 it.  If @code{:size} is omitted, a reasonable default is used.
4600
4601 Common Lisp allows only @code{eq}, @code{eql}, @code{equal},
4602 and @code{equalp} as legal values for the @code{:test} argument.
4603 In this package, any reasonable predicate function will work,
4604 though if you use something else you should check the details of
4605 the hashing function described below to make sure it is suitable
4606 for your predicate.
4607
4608 Some versions of Emacs (like XEmacs) include a built-in hash
4609 table type; in these versions, @code{make-hash-table} with a test of
4610 @code{eq}, @code{eql}, or @code{equal} will use these built-in hash
4611 tables.  In all other cases, it will return a hash-table object which
4612 takes the form of a list with an identifying ``tag'' symbol at the
4613 front.  All of the hash table functions in this package can operate on
4614 both types of hash table; normally you will never know which type is
4615 being used.
4616
4617 This function accepts the additional Common Lisp keywords
4618 @code{:rehash-size} and @code{:rehash-threshold}, but it ignores
4619 their values.
4620 @end defun
4621
4622 @defun gethash key table &optional default
4623 This function looks up @var{key} in @var{table}.  If @var{key}
4624 exists in the table, in the sense that it matches any of the existing
4625 keys according to the table's test function, then the associated value
4626 is returned.  Otherwise, @var{default} (or @code{nil}) is returned.
4627
4628 To store new data in the hash table, use @code{setf} on a call to
4629 @code{gethash}.  If @var{key} already exists in the table, the
4630 corresponding value is changed to the stored value.  If @var{key}
4631 does not already exist, a new entry is added to the table and the
4632 table is reallocated to a larger size if necessary.  The @var{default}
4633 argument is allowed but ignored in this case.  The situation is
4634 exactly analogous to that of @code{get}; @pxref{Property Lists}.
4635 @end defun
4636
4637 @defun remhash key table
4638 This function removes the entry for @var{key} from @var{table}.
4639 If an entry was removed, it returns @code{t}.  If @var{key} does
4640 not appear in the table, it does nothing and returns @code{nil}.
4641 @end defun
4642
4643 @defun clrhash table
4644 This function removes all the entries from @var{table}, leaving
4645 an empty hash table.
4646 @end defun
4647
4648 @defun maphash function table
4649 This function calls @var{function} for each entry in @var{table}.
4650 It passes two arguments to @var{function}, the key and the value
4651 of the given entry.  The return value of @var{function} is ignored;
4652 @var{maphash} itself returns @code{nil}.  @xref{Loop Facility}, for
4653 an alternate way of iterating over hash tables.
4654 @end defun
4655
4656 @defun hash-table-count table This function returns the number of
4657 entries in @var{table}.  @strong{Warning:} The current implementation of
4658 XEmacs hash-tables does not decrement the stored @code{count}
4659 when @code{remhash} removes an entry.  Therefore, the return value of
4660 this function is not dependable if you have used @code{remhash} on the
4661 table and the table's test is @code{eq}, @code{eql}, or @code{equal}.
4662 A slower, but reliable, way to count the entries is
4663 @code{(loop for x being the hash-keys of @var{table} count t)}.
4664 @end defun
4665
4666 @defun hash-table-p object This function returns @code{t} if
4667 @var{object} is a hash table, @code{nil} otherwise.  It recognizes both
4668 types of hash tables (both XEmacs built-in tables and tables implemented
4669 with special lists.)
4670 @end defun
4671
4672 Sometimes when dealing with hash tables it is useful to know the
4673 exact ``hash function'' that is used.  This package implements
4674 hash tables using Emacs Lisp ``obarrays,'' which are the same
4675 data structure that Emacs Lisp uses to keep track of symbols.
4676 Each hash table includes an embedded obarray.  Key values given
4677 to @code{gethash} are converted by various means into strings,
4678 which are then looked up in the obarray using @code{intern} and
4679 @code{intern-soft}.  The symbol, or ``bucket,'' corresponding to
4680 a given key string includes as its @code{symbol-value} an association
4681 list of all key-value pairs which hash to that string.  Depending
4682 on the test function, it is possible for many entries to hash to
4683 the same bucket.  For example, if the test is @code{eql}, then the
4684 symbol @code{foo} and two separately built strings @code{"foo"} will
4685 create three entries in the same bucket.  Search time is linear
4686 within buckets, so hash tables will be most effective if you arrange
4687 not to store too many things that hash the same.
4688
4689 The following algorithm is used to convert Lisp objects to hash
4690 strings:
4691
4692 @itemize @bullet
4693 @item
4694 Strings are used directly as hash strings.  (However, if the test
4695 function is @code{equalp}, strings are @code{downcase}d first.)
4696
4697 @item
4698 Symbols are hashed according to their @code{symbol-name}.
4699
4700 @item
4701 Integers are hashed into one of 16 buckets depending on their value
4702 modulo 16.  Floating-point numbers are truncated to integers and
4703 hashed modulo 16.
4704
4705 @item
4706 Cons cells are hashed according to their @code{car}s; nonempty vectors
4707 are hashed according to their first element.
4708
4709 @item
4710 All other types of objects hash into a single bucket named @code{"*"}.
4711 @end itemize
4712
4713 @noindent
4714 Thus, for example, searching among many buffer objects in a hash table
4715 will devolve to a (still fairly fast) linear-time search through a
4716 single bucket, whereas searching for different symbols will be very
4717 fast since each symbol will, in general, hash into its own bucket.
4718
4719 The size of the obarray in a hash table is automatically adjusted
4720 as the number of elements increases.
4721
4722 As a special case, @code{make-hash-table} with a @code{:size} argument
4723 of 0 or 1 will create a hash-table object that uses a single association
4724 list rather than an obarray of many lists.  For very small tables this
4725 structure will be more efficient since lookup does not require
4726 converting the key to a string or looking it up in an obarray.
4727 However, such tables are guaranteed to take time proportional to
4728 their size to do a search.
4729 @end ignore
4730
4731 @iftex
4732 @chapno=18
4733 @end iftex
4734
4735 @node Structures, Assertions, Hash Tables, Top
4736 @chapter Structures
4737
4738 @noindent
4739 The Common Lisp @dfn{structure} mechanism provides a general way
4740 to define data types similar to C's @code{struct} types.  A
4741 structure is a Lisp object containing some number of @dfn{slots},
4742 each of which can hold any Lisp data object.  Functions are
4743 provided for accessing and setting the slots, creating or copying
4744 structure objects, and recognizing objects of a particular structure
4745 type.
4746
4747 In true Common Lisp, each structure type is a new type distinct
4748 from all existing Lisp types.  Since the underlying Emacs Lisp
4749 system provides no way to create new distinct types, this package
4750 implements structures as vectors (or lists upon request) with a
4751 special ``tag'' symbol to identify them.
4752
4753 @defspec defstruct name slots@dots{}
4754 The @code{defstruct} form defines a new structure type called
4755 @var{name}, with the specified @var{slots}.  (The @var{slots}
4756 may begin with a string which documents the structure type.)
4757 In the simplest case, @var{name} and each of the @var{slots}
4758 are symbols.  For example,
4759
4760 @example
4761 (defstruct person name age sex)
4762 @end example
4763
4764 @noindent
4765 defines a struct type called @code{person} which contains three
4766 slots.  Given a @code{person} object @var{p}, you can access those
4767 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4768 and @code{(person-sex @var{p})}.  You can also change these slots by
4769 using @code{setf} on any of these place forms:
4770
4771 @example
4772 (incf (person-age birthday-boy))
4773 @end example
4774
4775 You can create a new @code{person} by calling @code{make-person},
4776 which takes keyword arguments @code{:name}, @code{:age}, and
4777 @code{:sex} to specify the initial values of these slots in the
4778 new object.  (Omitting any of these arguments leaves the corresponding
4779 slot ``undefined,'' according to the Common Lisp standard; in Emacs
4780 Lisp, such uninitialized slots are filled with @code{nil}.)
4781
4782 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4783 object of the same type whose slots are @code{eq} to those of @var{p}.
4784
4785 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4786 true if @var{x} looks like a @code{person}, false otherwise.  (Again,
4787 in Common Lisp this predicate would be exact; in Emacs Lisp the
4788 best it can do is verify that @var{x} is a vector of the correct
4789 length which starts with the correct tag symbol.)
4790
4791 Accessors like @code{person-name} normally check their arguments
4792 (effectively using @code{person-p}) and signal an error if the
4793 argument is the wrong type.  This check is affected by
4794 @code{(optimize (safety @dots{}))} declarations.  Safety level 1,
4795 the default, uses a somewhat optimized check that will detect all
4796 incorrect arguments, but may use an uninformative error message
4797 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4798 Safety level 0 omits all checks except as provided by the underlying
4799 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4800 always print a descriptive error message for incorrect inputs.
4801 @xref{Declarations}.
4802
4803 @example
4804 (setq dave (make-person :name "Dave" :sex 'male))
4805      @result{} [cl-struct-person "Dave" nil male]
4806 (setq other (copy-person dave))
4807      @result{} [cl-struct-person "Dave" nil male]
4808 (eq dave other)
4809      @result{} nil
4810 (eq (person-name dave) (person-name other))
4811      @result{} t
4812 (person-p dave)
4813      @result{} t
4814 (person-p [1 2 3 4])
4815      @result{} nil
4816 (person-p "Bogus")
4817      @result{} nil
4818 (person-p '[cl-struct-person counterfeit person object])
4819      @result{} t
4820 @end example
4821
4822 In general, @var{name} is either a name symbol or a list of a name
4823 symbol followed by any number of @dfn{struct options}; each @var{slot}
4824 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4825 @var{default-value} @var{slot-options}@dots{})}.  The @var{default-value}
4826 is a Lisp form which is evaluated any time an instance of the
4827 structure type is created without specifying that slot's value.
4828
4829 Common Lisp defines several slot options, but the only one
4830 implemented in this package is @code{:read-only}.  A non-@code{nil}
4831 value for this option means the slot should not be @code{setf}-able;
4832 the slot's value is determined when the object is created and does
4833 not change afterward.
4834
4835 @example
4836 (defstruct person
4837   (name nil :read-only t)
4838   age
4839   (sex 'unknown))
4840 @end example
4841
4842 Any slot options other than @code{:read-only} are ignored.
4843
4844 For obscure historical reasons, structure options take a different
4845 form than slot options.  A structure option is either a keyword
4846 symbol, or a list beginning with a keyword symbol possibly followed
4847 by arguments.  (By contrast, slot options are key-value pairs not
4848 enclosed in lists.)
4849
4850 @example
4851 (defstruct (person (:constructor create-person)
4852                    (:type list)
4853                    :named)
4854   name age sex)
4855 @end example
4856
4857 The following structure options are recognized.
4858
4859 @table @code
4860 @iftex
4861 @itemmax=0 in
4862 @advance@leftskip-.5@tableindent
4863 @end iftex
4864 @item :conc-name
4865 The argument is a symbol whose print name is used as the prefix for
4866 the names of slot accessor functions.  The default is the name of
4867 the struct type followed by a hyphen.  The option @code{(:conc-name p-)}
4868 would change this prefix to @code{p-}.  Specifying @code{nil} as an
4869 argument means no prefix, so that the slot names themselves are used
4870 to name the accessor functions.
4871
4872 @item :constructor
4873 In the simple case, this option takes one argument which is an
4874 alternate name to use for the constructor function.  The default
4875 is @code{make-@var{name}}, e.g., @code{make-person}.  The above
4876 example changes this to @code{create-person}.  Specifying @code{nil}
4877 as an argument means that no standard constructor should be
4878 generated at all.
4879
4880 In the full form of this option, the constructor name is followed
4881 by an arbitrary argument list.  @xref{Program Structure}, for a
4882 description of the format of Common Lisp argument lists.  All
4883 options, such as @code{&rest} and @code{&key}, are supported.
4884 The argument names should match the slot names; each slot is
4885 initialized from the corresponding argument.  Slots whose names
4886 do not appear in the argument list are initialized based on the
4887 @var{default-value} in their slot descriptor.  Also, @code{&optional}
4888 and @code{&key} arguments which don't specify defaults take their
4889 defaults from the slot descriptor.  It is legal to include arguments
4890 which don't correspond to slot names; these are useful if they are
4891 referred to in the defaults for optional, keyword, or @code{&aux}
4892 arguments which @emph{do} correspond to slots.
4893
4894 You can specify any number of full-format @code{:constructor}
4895 options on a structure.  The default constructor is still generated
4896 as well unless you disable it with a simple-format @code{:constructor}
4897 option.
4898
4899 @example
4900 (defstruct
4901  (person
4902   (:constructor nil)   ; no default constructor
4903   (:constructor new-person (name sex &optional (age 0)))
4904   (:constructor new-hound (&key (name "Rover")
4905                                 (dog-years 0)
4906                            &aux (age (* 7 dog-years))
4907                                 (sex 'canine))))
4908  name age sex)
4909 @end example
4910
4911 The first constructor here takes its arguments positionally rather
4912 than by keyword.  (In official Common Lisp terminology, constructors
4913 that work By Order of Arguments instead of by keyword are called
4914 ``BOA constructors.''  No, I'm not making this up.)  For example,
4915 @code{(new-person "Jane" 'female)} generates a person whose slots
4916 are @code{"Jane"}, 0, and @code{female}, respectively.
4917
4918 The second constructor takes two keyword arguments, @code{:name},
4919 which initializes the @code{name} slot and defaults to @code{"Rover"},
4920 and @code{:dog-years}, which does not itself correspond to a slot
4921 but which is used to initialize the @code{age} slot.  The @code{sex}
4922 slot is forced to the symbol @code{canine} with no syntax for
4923 overriding it.
4924
4925 @item :copier
4926 The argument is an alternate name for the copier function for
4927 this type.  The default is @code{copy-@var{name}}.  @code{nil}
4928 means not to generate a copier function.  (In this implementation,
4929 all copier functions are simply synonyms for @code{copy-sequence}.)
4930
4931 @item :predicate
4932 The argument is an alternate name for the predicate which recognizes
4933 objects of this type.  The default is @code{@var{name}-p}.  @code{nil}
4934 means not to generate a predicate function.  (If the @code{:type}
4935 option is used without the @code{:named} option, no predicate is
4936 ever generated.)
4937
4938 In true Common Lisp, @code{typep} is always able to recognize a
4939 structure object even if @code{:predicate} was used.  In this
4940 package, @code{typep} simply looks for a function called
4941 @code{@var{typename}-p}, so it will work for structure types
4942 only if they used the default predicate name.
4943
4944 @item :include
4945 This option implements a very limited form of C++-style inheritance.
4946 The argument is the name of another structure type previously
4947 created with @code{defstruct}.  The effect is to cause the new
4948 structure type to inherit all of the included structure's slots
4949 (plus, of course, any new slots described by this struct's slot
4950 descriptors).  The new structure is considered a ``specialization''
4951 of the included one.  In fact, the predicate and slot accessors
4952 for the included type will also accept objects of the new type.
4953
4954 If there are extra arguments to the @code{:include} option after
4955 the included-structure name, these options are treated as replacement
4956 slot descriptors for slots in the included structure, possibly with
4957 modified default values.  Borrowing an example from Steele:
4958
4959 @example
4960 (defstruct person name (age 0) sex)
4961      @result{} person
4962 (defstruct (astronaut (:include person (age 45)))
4963   helmet-size
4964   (favorite-beverage 'tang))
4965      @result{} astronaut
4966
4967 (setq joe (make-person :name "Joe"))
4968      @result{} [cl-struct-person "Joe" 0 nil]
4969 (setq buzz (make-astronaut :name "Buzz"))
4970      @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4971
4972 (list (person-p joe) (person-p buzz))
4973      @result{} (t t)
4974 (list (astronaut-p joe) (astronaut-p buzz))
4975      @result{} (nil t)
4976
4977 (person-name buzz)
4978      @result{} "Buzz"
4979 (astronaut-name joe)
4980      @result{} error: "astronaut-name accessing a non-astronaut"
4981 @end example
4982
4983 Thus, if @code{astronaut} is a specialization of @code{person},
4984 then every @code{astronaut} is also a @code{person} (but not the
4985 other way around).  Every @code{astronaut} includes all the slots
4986 of a @code{person}, plus extra slots that are specific to
4987 astronauts.  Operations that work on people (like @code{person-name})
4988 work on astronauts just like other people.
4989
4990 @item :print-function
4991 In full Common Lisp, this option allows you to specify a function
4992 which is called to print an instance of the structure type.  The
4993 Emacs Lisp system offers no hooks into the Lisp printer which would
4994 allow for such a feature, so this package simply ignores
4995 @code{:print-function}.
4996
4997 @item :type
4998 The argument should be one of the symbols @code{vector} or @code{list}.
4999 This tells which underlying Lisp data type should be used to implement
5000 the new structure type.  Vectors are used by default, but
5001 @code{(:type list)} will cause structure objects to be stored as
5002 lists instead.
5003
5004 The vector representation for structure objects has the advantage
5005 that all structure slots can be accessed quickly, although creating
5006 vectors is a bit slower in Emacs Lisp.  Lists are easier to create,
5007 but take a relatively long time accessing the later slots.
5008
5009 @item :named
5010 This option, which takes no arguments, causes a characteristic ``tag''
5011 symbol to be stored at the front of the structure object.  Using
5012 @code{:type} without also using @code{:named} will result in a
5013 structure type stored as plain vectors or lists with no identifying
5014 features.
5015
5016 The default, if you don't specify @code{:type} explicitly, is to
5017 use named vectors.  Therefore, @code{:named} is only useful in
5018 conjunction with @code{:type}.
5019
5020 @example
5021 (defstruct (person1) name age sex)
5022 (defstruct (person2 (:type list) :named) name age sex)
5023 (defstruct (person3 (:type list)) name age sex)
5024
5025 (setq p1 (make-person1))
5026      @result{} [cl-struct-person1 nil nil nil]
5027 (setq p2 (make-person2))
5028      @result{} (person2 nil nil nil)
5029 (setq p3 (make-person3))
5030      @result{} (nil nil nil)
5031
5032 (person1-p p1)
5033      @result{} t
5034 (person2-p p2)
5035      @result{} t
5036 (person3-p p3)
5037      @result{} error: function person3-p undefined
5038 @end example
5039
5040 Since unnamed structures don't have tags, @code{defstruct} is not
5041 able to make a useful predicate for recognizing them.  Also,
5042 accessors like @code{person3-name} will be generated but they
5043 will not be able to do any type checking.  The @code{person3-name}
5044 function, for example, will simply be a synonym for @code{car} in
5045 this case.  By contrast, @code{person2-name} is able to verify
5046 that its argument is indeed a @code{person2} object before
5047 proceeding.
5048
5049 @item :initial-offset
5050 The argument must be a nonnegative integer.  It specifies a
5051 number of slots to be left ``empty'' at the front of the
5052 structure.  If the structure is named, the tag appears at the
5053 specified position in the list or vector; otherwise, the first
5054 slot appears at that position.  Earlier positions are filled
5055 with @code{nil} by the constructors and ignored otherwise.  If
5056 the type @code{:include}s another type, then @code{:initial-offset}
5057 specifies a number of slots to be skipped between the last slot
5058 of the included type and the first new slot.
5059 @end table
5060 @end defspec
5061
5062 Except as noted, the @code{defstruct} facility of this package is
5063 entirely compatible with that of Common Lisp.
5064
5065 @iftex
5066 @chapno=23
5067 @end iftex
5068
5069 @node Assertions, Efficiency Concerns, Structures, Top
5070 @chapter Assertions and Errors
5071
5072 @noindent
5073 This section describes two macros that test @dfn{assertions}, i.e.,
5074 conditions which must be true if the program is operating correctly.
5075 Assertions never add to the behavior of a Lisp program; they simply
5076 make ``sanity checks'' to make sure everything is as it should be.
5077
5078 If the optimization property @code{speed} has been set to 3, and
5079 @code{safety} is less than 3, then the byte-compiler will optimize
5080 away the following assertions.  Because assertions might be optimized
5081 away, it is a bad idea for them to include side-effects.
5082
5083 @defspec assert test-form [show-args string args@dots{}]
5084 This form verifies that @var{test-form} is true (i.e., evaluates to
5085 a non-@code{nil} value).  If so, it returns @code{nil}.  If the test
5086 is not satisfied, @code{assert} signals an error.
5087
5088 A default error message will be supplied which includes @var{test-form}.
5089 You can specify a different error message by including a @var{string}
5090 argument plus optional extra arguments.  Those arguments are simply
5091 passed to @code{error} to signal the error.
5092
5093 If the optional second argument @var{show-args} is @code{t} instead
5094 of @code{nil}, then the error message (with or without @var{string})
5095 will also include all non-constant arguments of the top-level
5096 @var{form}.  For example:
5097
5098 @example
5099 (assert (> x 10) t "x is too small: %d")
5100 @end example
5101
5102 This usage of @var{show-args} is a change to Common Lisp.  In
5103 true Common Lisp, the second argument gives a list of @var{places}
5104 which can be @code{setf}'d by the user before continuing from the
5105 error.
5106 @end defspec
5107
5108 @defspec check-type place type &optional string
5109 This form verifies that @var{place} evaluates to a value of type
5110 @var{type}.  If so, it returns @code{nil}.  If not, @code{check-type}
5111 signals a continuable @code{wrong-type-argument} error.  The default
5112 error message lists the erroneous value along with @var{type} and
5113 @var{place} themselves.  If @var{string} is specified, it is included in
5114 the error message in place of @var{type}.  For example:
5115
5116 @example
5117 (check-type x (integer 1 *) "a positive integer")
5118 @end example
5119
5120 @xref{Type Predicates}, for a description of the type specifiers
5121 that may be used for @var{type}.
5122
5123 Note that as in Common Lisp, the first argument to @code{check-type}
5124 should be a @var{place} suitable for use by @code{setf}, because
5125 @code{check-type} signals a continuable error that allows the user to
5126 modify @var{place}, most simply by returning a value from the debugger.
5127 @end defspec
5128
5129 The following error-related macro is also defined:
5130
5131 @defspec ignore-errors forms@dots{}
5132 This executes @var{forms} exactly like a @code{progn}, except that
5133 errors are ignored during the @var{forms}.  More precisely, if
5134 an error is signalled then @code{ignore-errors} immediately
5135 aborts execution of the @var{forms} and returns @code{nil}.
5136 If the @var{forms} complete successfully, @code{ignore-errors}
5137 returns the result of the last @var{form}.
5138 @end defspec
5139
5140 @node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
5141 @appendix Efficiency Concerns
5142
5143 @appendixsec Macros
5144
5145 @noindent
5146 Many of the advanced features of this package, such as @code{defun*},
5147 @code{loop}, and @code{setf}, are implemented as Lisp macros.  In
5148 byte-compiled code, these complex notations will be expanded into
5149 equivalent Lisp code which is simple and efficient.  For example,
5150 the forms
5151
5152 @example
5153 (incf i n)
5154 (push x (car p))
5155 @end example
5156
5157 @noindent
5158 are expanded at compile-time to the Lisp forms
5159
5160 @example
5161 (setq i (+ i n))
5162 (setcar p (cons x (car p)))
5163 @end example
5164
5165 @noindent
5166 which are the most efficient ways of doing these respective operations
5167 in Lisp.  Thus, there is no performance penalty for using the more
5168 readable @code{incf} and @code{push} forms in your compiled code.
5169
5170 @emph{Interpreted} code, on the other hand, must expand these macros
5171 every time they are executed.  For this reason it is strongly
5172 recommended that code making heavy use of macros be compiled.
5173 (The features labelled ``Special Form'' instead of ``Function'' in
5174 this manual are macros.)  A loop using @code{incf} a hundred times
5175 will execute considerably faster if compiled, and will also
5176 garbage-collect less because the macro expansion will not have
5177 to be generated, used, and thrown away a hundred times.
5178
5179 You can find out how a macro expands by using the
5180 @code{cl-prettyexpand} function.
5181
5182 @defun cl-prettyexpand form &optional full
5183 This function takes a single Lisp form as an argument and inserts
5184 a nicely formatted copy of it in the current buffer (which must be
5185 in Lisp mode so that indentation works properly).  It also expands
5186 all Lisp macros which appear in the form.  The easiest way to use
5187 this function is to go to the @code{*scratch*} buffer and type, say,
5188
5189 @example
5190 (cl-prettyexpand '(loop for x below 10 collect x))
5191 @end example
5192
5193 @noindent
5194 and type @kbd{C-x C-e} immediately after the closing parenthesis;
5195 the expansion
5196
5197 @example
5198 (block nil
5199   (let* ((x 0)
5200          (G1004 nil))
5201     (while (< x 10)
5202       (setq G1004 (cons x G1004))
5203       (setq x (+ x 1)))
5204     (nreverse G1004)))
5205 @end example
5206
5207 @noindent
5208 will be inserted into the buffer.  (The @code{block} macro is
5209 expanded differently in the interpreter and compiler, so
5210 @code{cl-prettyexpand} just leaves it alone.  The temporary
5211 variable @code{G1004} was created by @code{gensym}.)
5212
5213 If the optional argument @var{full} is true, then @emph{all}
5214 macros are expanded, including @code{block}, @code{eval-when},
5215 and compiler macros.  Expansion is done as if @var{form} were
5216 a top-level form in a file being compiled.  For example,
5217
5218 @example
5219 (cl-prettyexpand '(pushnew 'x list))
5220      @print{} (setq list (adjoin 'x list))
5221 (cl-prettyexpand '(pushnew 'x list) t)
5222      @print{} (setq list (if (memq 'x list) list (cons 'x list)))
5223 (cl-prettyexpand '(caddr (member* 'a list)) t)
5224      @print{} (car (cdr (cdr (memq 'a list))))
5225 @end example
5226
5227 Note that @code{adjoin}, @code{caddr}, and @code{member*} all
5228 have built-in compiler macros to optimize them in common cases.
5229 @end defun
5230
5231 @ifinfo
5232 @example
5233
5234 @end example
5235 @end ifinfo
5236 @appendixsec Error Checking
5237
5238 @noindent
5239 Common Lisp compliance has in general not been sacrificed for the
5240 sake of efficiency.  A few exceptions have been made for cases
5241 where substantial gains were possible at the expense of marginal
5242 incompatibility.  One example is the use of @code{memq} (which is
5243 treated very efficiently by the byte-compiler) to scan for keyword
5244 arguments; this can become confused in rare cases when keyword
5245 symbols are used as both keywords and data values at once.  This
5246 is extremely unlikely to occur in practical code, and the use of
5247 @code{memq} allows functions with keyword arguments to be nearly
5248 as fast as functions that use @code{&optional} arguments.
5249
5250 The Common Lisp standard (as embodied in Steele's book) uses the
5251 phrase ``it is an error if'' to indicate a situation which is not
5252 supposed to arise in complying programs; implementations are strongly
5253 encouraged but not required to signal an error in these situations.
5254 This package sometimes omits such error checking in the interest of
5255 compactness and efficiency.  For example, @code{do} variable
5256 specifiers are supposed to be lists of one, two, or three forms;
5257 extra forms are ignored by this package rather than signalling a
5258 syntax error.  The @code{endp} function is simply a synonym for
5259 @code{null} in this package.  Functions taking keyword arguments
5260 will accept an odd number of arguments, treating the trailing
5261 keyword as if it were followed by the value @code{nil}.
5262
5263 Argument lists (as processed by @code{defun*} and friends)
5264 @emph{are} checked rigorously except for the minor point just
5265 mentioned; in particular, keyword arguments are checked for
5266 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
5267 are fully implemented.  Keyword validity checking is slightly
5268 time consuming (though not too bad in byte-compiled code);
5269 you can use @code{&allow-other-keys} to omit this check.  Functions
5270 defined in this package such as @code{find} and @code{member*}
5271 do check their keyword arguments for validity.
5272
5273 @ifinfo
5274 @example
5275
5276 @end example
5277 @end ifinfo
5278 @appendixsec Optimizing Compiler
5279
5280 @noindent
5281 The byte-compiler that comes with Emacs 18 normally fails to expand
5282 macros that appear in top-level positions in the file (i.e., outside
5283 of @code{defun}s or other enclosing forms).  This would have
5284 disastrous consequences to programs that used such top-level macros
5285 as @code{defun*}, @code{eval-when}, and @code{defstruct}.  To
5286 work around this problem, the @dfn{CL} package patches the Emacs
5287 18 compiler to expand top-level macros.  This patch will apply to
5288 your own macros, too, if they are used in a top-level context.
5289 The patch will not harm versions of the Emacs 18 compiler which
5290 have already had a similar patch applied, nor will it affect the
5291 optimizing Emacs 19 byte-compiler written by Jamie Zawinski and
5292 Hallvard Furuseth.  The patch is applied to the byte compiler's
5293 code in Emacs' memory, @emph{not} to the @file{bytecomp.elc} file
5294 stored on disk.
5295
5296 The Emacs 19 compiler (for Emacs 18) is available from various
5297 Emacs Lisp archive sites such as @code{archive.cis.ohio-state.edu}.
5298 Its use is highly recommended; many of the Common Lisp macros emit
5299 code which can be improved by optimization.  In particular,
5300 @code{block}s (whether explicit or implicit in constructs like
5301 @code{defun*} and @code{loop}) carry a fair run-time penalty; the
5302 optimizing compiler removes @code{block}s which are not actually
5303 referenced by @code{return} or @code{return-from} inside the block.
5304
5305 @node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top
5306 @appendix Common Lisp Compatibility
5307
5308 @noindent
5309 Following is a list of all known incompatibilities between this
5310 package and Common Lisp as documented in Steele (2nd edition).
5311
5312 Certain function names, such as @code{member}, @code{assoc}, and
5313 @code{floor}, were already taken by (incompatible) Emacs Lisp
5314 functions; this package appends @samp{*} to the names of its
5315 Common Lisp versions of these functions.
5316
5317 The word @code{defun*} is required instead of @code{defun} in order
5318 to use extended Common Lisp argument lists in a function.  Likewise,
5319 @code{defmacro*} and @code{function*} are versions of those forms
5320 which understand full-featured argument lists.  The @code{&whole}
5321 keyword does not work in @code{defmacro} argument lists (except
5322 inside recursive argument lists).
5323
5324 In order to allow an efficient implementation, keyword arguments use
5325 a slightly cheesy parser which may be confused if a keyword symbol
5326 is passed as the @emph{value} of another keyword argument.
5327 (Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})}
5328 is used to scan for @code{:@var{keyword}} among the supplied
5329 keyword arguments.)
5330
5331 The @code{eql} and @code{equal} predicates do not distinguish
5332 between IEEE floating-point plus and minus zero.  The @code{equalp}
5333 predicate has several differences with Common Lisp; @pxref{Predicates}.
5334
5335 The @code{setf} mechanism is entirely compatible, except that
5336 setf-methods return a list of five values rather than five
5337 values directly.  Also, the new ``@code{setf} function'' concept
5338 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
5339
5340 The @code{do-all-symbols} form is the same as @code{do-symbols}
5341 with no @var{obarray} argument.  In Common Lisp, this form would
5342 iterate over all symbols in all packages.  Since Emacs obarrays
5343 are not a first-class package mechanism, there is no way for
5344 @code{do-all-symbols} to locate any but the default obarray.
5345
5346 The @code{loop} macro is complete except that @code{loop-finish}
5347 and type specifiers are unimplemented.
5348
5349 The multiple-value return facility treats lists as multiple
5350 values, since Emacs Lisp cannot support multiple return values
5351 directly.  The macros will be compatible with Common Lisp if
5352 @code{values} or @code{values-list} is always used to return to
5353 a @code{multiple-value-bind} or other multiple-value receiver;
5354 if @code{values} is used without @code{multiple-value-@dots{}}
5355 or vice-versa the effect will be different from Common Lisp.
5356
5357 Many Common Lisp declarations are ignored, and others match
5358 the Common Lisp standard in concept but not in detail.  For
5359 example, local @code{special} declarations, which are purely
5360 advisory in Emacs Lisp, do not rigorously obey the scoping rules
5361 set down in Steele's book.
5362
5363 The variable @code{*gensym-counter*} starts out with a pseudo-random
5364 value rather than with zero.  This is to cope with the fact that
5365 generated symbols become interned when they are written to and
5366 loaded back from a file.
5367
5368 The @code{defstruct} facility is compatible, except that structures
5369 are of type @code{:type vector :named} by default rather than some
5370 special, distinct type.  Also, the @code{:type} slot option is ignored.
5371
5372 The second argument of @code{check-type} is treated differently.
5373
5374 @node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top
5375 @appendix Old CL Compatibility
5376
5377 @noindent
5378 Following is a list of all known incompatibilities between this package
5379 and the older Quiroz @file{cl.el} package.
5380
5381 This package's emulation of multiple return values in functions is
5382 incompatible with that of the older package.  That package attempted
5383 to come as close as possible to true Common Lisp multiple return
5384 values; unfortunately, it could not be 100% reliable and so was prone
5385 to occasional surprises if used freely.  This package uses a simpler
5386 method, namely replacing multiple values with lists of values, which
5387 is more predictable though more noticeably different from Common Lisp.
5388
5389 The @code{defkeyword} form and @code{keywordp} function are not
5390 implemented in this package.
5391
5392 The @code{member}, @code{floor}, @code{ceiling}, @code{truncate},
5393 @code{round}, @code{mod}, and @code{rem} functions are suffixed
5394 by @samp{*} in this package to avoid collision with existing
5395 functions in Emacs 18 or Emacs 19.  The older package simply
5396 redefined these functions, overwriting the built-in meanings and
5397 causing serious portability problems with Emacs 19.  (Some more
5398 recent versions of the Quiroz package changed the names to
5399 @code{cl-member}, etc.; this package defines the latter names as
5400 aliases for @code{member*}, etc.)
5401
5402 Certain functions in the old package which were buggy or inconsistent
5403 with the Common Lisp standard are incompatible with the conforming
5404 versions in this package.  For example, @code{eql} and @code{member}
5405 were synonyms for @code{eq} and @code{memq} in that package, @code{setf}
5406 failed to preserve correct order of evaluation of its arguments, etc.
5407
5408 Finally, unlike the older package, this package is careful to
5409 prefix all of its internal names with @code{cl-}.  Except for a
5410 few functions which are explicitly defined as additional features
5411 (such as @code{floatp-safe} and @code{letf}), this package does not
5412 export any non-@samp{cl-} symbols which are not also part of Common
5413 Lisp.
5414
5415 @ifinfo
5416 @example
5417
5418 @end example
5419 @end ifinfo
5420 @appendixsec The @code{cl-compat} package
5421
5422 @noindent
5423 The @dfn{CL} package includes emulations of some features of the
5424 old @file{cl.el}, in the form of a compatibility package
5425 @code{cl-compat}.  To use it, put @code{(require 'cl-compat)} in
5426 your program.
5427
5428 The old package defined a number of internal routines without
5429 @code{cl-} prefixes or other annotations.  Call to these routines
5430 may have crept into existing Lisp code.  @code{cl-compat}
5431 provides emulations of the following internal routines:
5432 @code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists},
5433 @code{reassemble-arglists}, @code{duplicate-symbols-p},
5434 @code{safe-idiv}.
5435
5436 Some @code{setf} forms translated into calls to internal
5437 functions that user code might call directly.  The functions
5438 @code{setnth}, @code{setnthcdr}, and @code{setelt} fall in
5439 this category; they are defined by @code{cl-compat}, but the
5440 best fix is to change to use @code{setf} properly.
5441
5442 The @code{cl-compat} file defines the keyword functions
5443 @code{keywordp}, @code{keyword-of}, and @code{defkeyword},
5444 which are not defined by the new @dfn{CL} package because the
5445 use of keywords as data is discouraged.
5446
5447 The @code{build-klist} mechanism for parsing keyword arguments
5448 is emulated by @code{cl-compat}; the @code{with-keyword-args}
5449 macro is not, however, and in any case it's best to change to
5450 use the more natural keyword argument processing offered by
5451 @code{defun*}.
5452
5453 Multiple return values are treated differently by the two
5454 Common Lisp packages.  The old package's method was more
5455 compatible with true Common Lisp, though it used heuristics
5456 that caused it to report spurious multiple return values in
5457 certain cases.  The @code{cl-compat} package defines a set
5458 of multiple-value macros that are compatible with the old
5459 CL package; again, they are heuristic in nature, but they
5460 are guaranteed to work in any case where the old package's
5461 macros worked.  To avoid name collision with the ``official''
5462 multiple-value facilities, the ones in @code{cl-compat} have
5463 capitalized names:  @code{Values}, @code{Values-list},
5464 @code{Multiple-value-bind}, etc.
5465
5466 The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate},
5467 and @code{cl-round} are defined by @code{cl-compat} to use the
5468 old-style multiple-value mechanism, just as they did in the old
5469 package.  The newer @code{floor*} and friends return their two
5470 results in a list rather than as multiple values.  Note that
5471 older versions of the old package used the unadorned names
5472 @code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
5473 these names because they conflict with Emacs 19 built-ins.
5474
5475 @node Porting Common Lisp, Function Index, Old CL Compatibility, Top
5476 @appendix Porting Common Lisp
5477
5478 @noindent
5479 This package is meant to be used as an extension to Emacs Lisp,
5480 not as an Emacs implementation of true Common Lisp.  Some of the
5481 remaining differences between Emacs Lisp and Common Lisp make it
5482 difficult to port large Common Lisp applications to Emacs.  For
5483 one, some of the features in this package are not fully compliant
5484 with ANSI or Steele; @pxref{Common Lisp Compatibility}.  But there
5485 are also quite a few features that this package does not provide
5486 at all.  Here are some major omissions that you will want watch out
5487 for when bringing Common Lisp code into Emacs.
5488
5489 @itemize @bullet
5490 @item
5491 Case-insensitivity.  Symbols in Common Lisp are case-insensitive
5492 by default.  Some programs refer to a function or variable as
5493 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
5494 Emacs Lisp will treat these as three distinct symbols.
5495
5496 Some Common Lisp code is written in all upper-case.  While Emacs
5497 is happy to let the program's own functions and variables use
5498 this convention, calls to Lisp builtins like @code{if} and
5499 @code{defun} will have to be changed to lower-case.
5500
5501 @item
5502 Lexical scoping.  In Common Lisp, function arguments and @code{let}
5503 bindings apply only to references physically within their bodies
5504 (or within macro expansions in their bodies).  Emacs Lisp, by
5505 contrast, uses @dfn{dynamic scoping} wherein a binding to a
5506 variable is visible even inside functions called from the body.
5507
5508 Variables in Common Lisp can be made dynamically scoped by
5509 declaring them @code{special} or using @code{defvar}.  In Emacs
5510 Lisp it is as if all variables were declared @code{special}.
5511
5512 Often you can use code that was written for lexical scoping
5513 even in a dynamically scoped Lisp, but not always.  Here is
5514 an example of a Common Lisp code fragment that would fail in
5515 Emacs Lisp:
5516
5517 @example
5518 (defun map-odd-elements (func list)
5519   (loop for x in list
5520         for flag = t then (not flag)
5521         collect (if flag x (funcall func x))))
5522
5523 (defun add-odd-elements (list x)
5524   (map-odd-elements (function (lambda (a) (+ a x))) list))
5525 @end example
5526
5527 @noindent
5528 In Common Lisp, the two functions' usages of @code{x} are completely
5529 independent.  In Emacs Lisp, the binding to @code{x} made by
5530 @code{add-odd-elements} will have been hidden by the binding
5531 in @code{map-odd-elements} by the time the @code{(+ a x)} function
5532 is called.
5533
5534 (This package avoids such problems in its own mapping functions
5535 by using names like @code{cl-x} instead of @code{x} internally;
5536 as long as you don't use the @code{cl-} prefix for your own
5537 variables no collision can occur.)
5538
5539 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
5540 form which establishes a Common Lisp-style lexical binding, and some
5541 examples of how it differs from Emacs' regular @code{let}.
5542
5543 @item
5544 Common Lisp allows the shorthand @code{#'x} to stand for
5545 @code{(function x)}, just as @code{'x} stands for @code{(quote x)}.
5546 In Common Lisp, one traditionally uses @code{#'} notation when
5547 referring to the name of a function.  In Emacs Lisp, it works
5548 just as well to use a regular quote:
5549
5550 @example
5551 (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp
5552 (loop for x in y by 'cddr collect (mapcar 'plusp x))   ; Emacs Lisp
5553 @end example
5554
5555 When @code{#'} introduces a @code{lambda} form, it is best to
5556 write out @code{(function ...)} longhand in Emacs Lisp.  You can
5557 use a regular quote, but then the byte-compiler won't know that
5558 the @code{lambda} expression is code that can be compiled.
5559
5560 @example
5561 (mapcar #'(lambda (x) (* x 2)) list)            ; Common Lisp
5562 (mapcar (function (lambda (x) (* x 2))) list)   ; Emacs Lisp
5563 @end example
5564
5565 XEmacs supports @code{#'} notation starting with version 19.8.
5566
5567 @item
5568 Reader macros.  Common Lisp includes a second type of macro that
5569 works at the level of individual characters.  For example, Common
5570 Lisp implements the quote notation by a reader macro called @code{'},
5571 whereas Emacs Lisp's parser just treats quote as a special case.
5572 Some Lisp packages use reader macros to create special syntaxes
5573 for themselves, which the Emacs parser is incapable of reading.
5574
5575 @item
5576 Other syntactic features.  Common Lisp provides a number of
5577 notations beginning with @code{#} that the Emacs Lisp parser
5578 won't understand.  For example, @samp{#| ... |#} is an
5579 alternate comment notation, and @samp{#+lucid (foo)} tells
5580 the parser to ignore the @code{(foo)} except in Lucid Common
5581 Lisp.
5582
5583 The number prefixes `#b', `#o', and `#x', however, are supported
5584 by the Emacs Lisp parser to represent numbers in binary, octal,
5585 and hexadecimal notation (or radix), just like in Common Lisp.
5586
5587 @item
5588 Packages.  In Common Lisp, symbols are divided into @dfn{packages}.
5589 Symbols that are Lisp built-ins are typically stored in one package;
5590 symbols that are vendor extensions are put in another, and each
5591 application program would have a package for its own symbols.
5592 Certain symbols are ``exported'' by a package and others are
5593 internal; certain packages ``use'' or import the exported symbols
5594 of other packages.  To access symbols that would not normally be
5595 visible due to this importing and exporting, Common Lisp provides
5596 a syntax like @code{package:symbol} or @code{package::symbol}.
5597
5598 Emacs Lisp has a single namespace for all interned symbols, and
5599 then uses a naming convention of putting a prefix like @code{cl-}
5600 in front of the name.  Some Emacs packages adopt the Common Lisp-like
5601 convention of using @code{cl:} or @code{cl::} as the prefix.
5602 However, the Emacs parser does not understand colons and just
5603 treats them as part of the symbol name.  Thus, while @code{mapcar}
5604 and @code{lisp:mapcar} may refer to the same symbol in Common
5605 Lisp, they are totally distinct in Emacs Lisp.  Common Lisp
5606 programs which refer to a symbol by the full name sometimes
5607 and the short name other times will not port cleanly to Emacs.
5608
5609 Emacs Lisp does have a concept of ``obarrays,'' which are
5610 package-like collections of symbols, but this feature is not
5611 strong enough to be used as a true package mechanism.
5612
5613 @item
5614 Keywords.  The notation @code{:test-not} in Common Lisp really
5615 is a shorthand for @code{keyword:test-not}; keywords are just
5616 symbols in a built-in @code{keyword} package with the special
5617 property that all its symbols are automatically self-evaluating.
5618 Common Lisp programs often use keywords liberally to avoid
5619 having to use quotes.
5620
5621 In Emacs Lisp a keyword is just a symbol whose name begins with
5622 a colon; since the Emacs parser does not treat them specially,
5623 they have to be explicitly made self-evaluating by a statement
5624 like @code{(setq :test-not ':test-not)}.  This package arranges
5625 to execute such a statement whenever @code{defun*} or some
5626 other form sees a keyword being used as an argument.  Common
5627 Lisp code that assumes that a symbol @code{:mumble} will be
5628 self-evaluating even though it was never introduced by a
5629 @code{defun*} will have to be fixed.
5630
5631 @item
5632 The @code{format} function is quite different between Common
5633 Lisp and Emacs Lisp.  It takes an additional ``destination''
5634 argument before the format string.  A destination of @code{nil}
5635 means to format to a string as in Emacs Lisp; a destination
5636 of @code{t} means to write to the terminal (similar to
5637 @code{message} in Emacs).  Also, format control strings are
5638 utterly different; @code{~} is used instead of @code{%} to
5639 introduce format codes, and the set of available codes is
5640 much richer.  There are no notations like @code{\n} for
5641 string literals; instead, @code{format} is used with the
5642 ``newline'' format code, @code{~%}.  More advanced formatting
5643 codes provide such features as paragraph filling, case
5644 conversion, and even loops and conditionals.
5645
5646 While it would have been possible to implement most of Common
5647 Lisp @code{format} in this package (under the name @code{format*},
5648 of course), it was not deemed worthwhile.  It would have required
5649 a huge amount of code to implement even a decent subset of
5650 @code{format*}, yet the functionality it would provide over
5651 Emacs Lisp's @code{format} would rarely be useful.
5652
5653 @item
5654 Vector constants use square brackets in Emacs Lisp, but
5655 @code{#(a b c)} notation in Common Lisp.  To further complicate
5656 matters, Emacs 19 introduces its own @code{#(} notation for
5657 something entirely different---strings with properties.
5658
5659 @item
5660 Characters are distinct from integers in Common Lisp.  The
5661 notation for character constants is also different:  @code{#\A}
5662 instead of @code{?A}.  Also, @code{string=} and @code{string-equal}
5663 are synonyms in Emacs Lisp whereas the latter is case-insensitive
5664 in Common Lisp.
5665
5666 @item
5667 Data types.  Some Common Lisp data types do not exist in Emacs
5668 Lisp.  Rational numbers and complex numbers are not present,
5669 nor are large integers (all integers are ``fixnums'').  All
5670 arrays are one-dimensional.  There are no readtables or pathnames;
5671 streams are a set of existing data types rather than a new data
5672 type of their own.  Hash tables, random-states, structures, and
5673 packages (obarrays) are built from Lisp vectors or lists rather
5674 than being distinct types.
5675
5676 @item
5677 The Common Lisp Object System (CLOS) is not implemented,
5678 nor is the Common Lisp Condition System.
5679
5680 @item
5681 Common Lisp features that are completely redundant with Emacs
5682 Lisp features of a different name generally have not been
5683 implemented.  For example, Common Lisp writes @code{defconstant}
5684 where Emacs Lisp uses @code{defconst}.  Similarly, @code{make-list}
5685 takes its arguments in different ways in the two Lisps but does
5686 exactly the same thing, so this package has not bothered to
5687 implement a Common Lisp-style @code{make-list}.
5688
5689 @item
5690 A few more notable Common Lisp features not included in this
5691 package:  @code{compiler-let}, @code{tagbody}, @code{prog},
5692 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5693
5694 @item
5695 Recursion.  While recursion works in Emacs Lisp just like it
5696 does in Common Lisp, various details of the Emacs Lisp system
5697 and compiler make recursion much less efficient than it is in
5698 most Lisps.  Some schools of thought prefer to use recursion
5699 in Lisp over other techniques; they would sum a list of
5700 numbers using something like
5701
5702 @example
5703 (defun sum-list (list)
5704   (if list
5705       (+ (car list) (sum-list (cdr list)))
5706     0))
5707 @end example
5708
5709 @noindent
5710 where a more iteratively-minded programmer might write one of
5711 these forms:
5712
5713 @example
5714 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
5715 (loop for x in my-list sum x)
5716 @end example
5717
5718 While this would be mainly a stylistic choice in most Common Lisps,
5719 in Emacs Lisp you should be aware that the iterative forms are
5720 much faster than recursion.  Also, Lisp programmers will want to
5721 note that the current Emacs Lisp compiler does not optimize tail
5722 recursion.
5723 @end itemize
5724
5725 @node Function Index, Variable Index, Porting Common Lisp, Top
5726 @unnumbered Function Index
5727
5728 @printindex fn
5729
5730 @node Variable Index, , Function Index, Top
5731 @unnumbered Variable Index
5732
5733 @printindex vr
5734
5735 @contents
5736 @bye