@setfilename ../info/cl
@settitle Common Lisp Extensions
+@copying
+This file documents the GNU Emacs Common Lisp emulation package.
+
+Copyright @copyright{} 1993, 2002, 2003, 2004, 2005, 2006 Free
+Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
@dircategory Emacs
@direntry
* CL: (cl). Partial Common Lisp support for Emacs Lisp.
@end direntry
-@iftex
@finalout
-@end iftex
-
-@ifinfo
-This file documents the GNU Emacs Common Lisp emulation package.
-
-Copyright (C) 1993 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' may be
-included in a translation approved by the author instead of in the
-original English.
-@end ifinfo
@titlepage
@sp 6
@center Dave Gillespie
@center daveg@@synaptics.com
@page
-
@vskip 0pt plus 1filll
-Copyright @copyright{} 1993 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' may be
-included in a translation approved by the author instead of in the
-original English.
+@insertcopying
@end titlepage
-@node Top, Overview,, (dir)
-@chapter Common Lisp Extensions
+@node Top, Overview, (dir), (dir)
+@chapter Introduction
@noindent
This document describes a set of Emacs Lisp facilities borrowed from
* Numbers:: Predicates, functions, random numbers
* Sequences:: Mapping, functions, searching, sorting
* Lists:: `cadr', `sublis', `member*', `assoc*', etc.
-* Hash Tables:: `make-hash-table', `gethash', etc.
* Structures:: `defstruct'
* Assertions:: `check-type', `assert', `ignore-errors'.
@end menu
@node Overview, Program Structure, Top, Top
-@ifinfo
+@ifnottex
@chapter Overview
-@end ifinfo
-@iftex
-@section Overview
-@end iftex
+@end ifnottex
@noindent
Common Lisp is a huge language, and Common Lisp systems tend to be
implementation of Common Lisp, @dfn{CL} adds enough functionality
to make Emacs Lisp programming significantly more convenient.
+@strong{Please note:} the @dfn{CL} functions are not standard parts of
+the Emacs Lisp name space, so it is legitimate for users to define
+them with other, conflicting meanings. To avoid conflicting with
+those user activities, we have a policy that packages installed in
+Emacs must not load @dfn{CL} at run time. (It is ok for them to load
+@dfn{CL} at compile time only, with @code{eval-when-compile}, and use
+the macros it provides.) If you are writing packages that you plan to
+distribute and invite widespread use for, you might want to observe
+the same rule.
+
Some Common Lisp features have been omitted from this package
for various reasons:
The package described here was written by Dave Gillespie,
@file{daveg@@synaptics.com}. It is a total rewrite of the original
1986 @file{cl.el} package by Cesar Quiroz. Most features of the
-the Quiroz package have been retained; any incompatibilities are
+Quiroz package have been retained; any incompatibilities are
noted in the descriptions below. Care has been taken in this
version to ensure that each function is defined efficiently,
concisely, and with minimal impact on the rest of the Emacs
You may instead wish to leave this package's components all in
their own directory, and then add this directory to your
-@code{load-path} and (Emacs 19 only) @code{Info-directory-list}.
+@code{load-path} and @code{Info-directory-list}.
Add the directory to the front of the list so the old @dfn{CL}
package and its documentation are hidden.
-@node Naming Conventions, , Installation, Overview
+@node Naming Conventions, , Installation, Overview
@section Naming Conventions
@noindent
member* assoc* rassoc* get*
remove* delete* mapcar* sort*
floor* ceiling* truncate* round*
-mod* rem* random* last*
+mod* rem* random*
@end example
Internal function and variable names in the package are prefixed
prefixed by @code{cl-} which were not taken from Common Lisp:
@example
-member remove remq
floatp-safe lexical-let lexical-let*
callf callf2 letf letf*
-defsubst* defalias add-hook eval-when-compile
+defsubst*
@end example
-@noindent
-(Most of these are Emacs 19 features provided to Emacs 18 users,
-or introduced, like @code{remq}, for reasons of symmetry
-with similar features.)
-
The following simple functions and macros are defined in @file{cl.el};
they do not cause other components like @file{cl-extra} to be loaded.
@example
eql floatp-safe endp
evenp oddp plusp minusp
-butlast nbutlast caaar .. cddddr
+caaar .. cddddr
list* ldiff rest first .. tenth
copy-list subst mapcar* [2]
adjoin [3] acons pairlis pop [4]
@menu
* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
* Time of Evaluation:: The `eval-when' construct.
-* Function Aliases:: The `defalias' function.
@end menu
@iftex
This is just like @code{defun*}, except that the function that
is defined is automatically proclaimed @code{inline}, i.e.,
calls to it may be expanded into in-line code by the byte compiler.
-This is analogous to the @code{defsubst} form in Emacs 19;
+This is analogous to the @code{defsubst} form;
@code{defsubst*} uses a different method (compiler macros) which
works in all version of Emacs, and also generates somewhat more
efficient inline expansions. In particular, @code{defsubst*}
keep both @code{find-thing} and @code{member*} from complaining
about each others' keywords in the arguments.
-As a (significant) performance optimization, this package
-implements the scan for keyword arguments by calling @code{memq}
-to search for keywords in a ``rest'' argument. Technically
-speaking, this is incorrect, since @code{memq} looks at the
-odd-numbered values as well as the even-numbered keywords.
-The net effect is that if you happen to pass a keyword symbol
-as the @emph{value} of another keyword argument, where that
-keyword symbol happens to equal the name of a valid keyword
-argument of the same function, then the keyword parser will
-become confused. This minor bug can only affect you if you
-use keyword symbols as general-purpose data in your program;
-this practice is strongly discouraged in Emacs Lisp.
-
The fifth section of the argument list consists of @dfn{auxiliary
variables}. These are not really arguments at all, but simply
variables which are bound to @code{nil} or to the specified
arguments and invalid keyword arguments is disabled. By default,
argument lists are rigorously checked.
-@node Time of Evaluation, Function Aliases, Argument Lists, Program Structure
+@node Time of Evaluation, , Argument Lists, Program Structure
@section Time of Evaluation
@noindent
(compile load eval) @dots{})}.
@end defspec
-Emacs 19 includes two special forms related to @code{eval-when}.
+Emacs includes two special forms related to @code{eval-when}.
One of these, @code{eval-when-compile}, is not quite equivalent to
any @code{eval-when} construct and is described below.
@end example
@end defspec
-@node Function Aliases, , Time of Evaluation, Program Structure
-@section Function Aliases
-
-@noindent
-This section describes a feature from GNU Emacs 19 which this
-package makes available in other versions of Emacs.
-
-@defun defalias symbol function
-This function sets @var{symbol}'s function cell to @var{function}.
-It is equivalent to @code{fset}, except that in GNU Emacs 19 it also
-records the setting in @code{load-history} so that it can be undone
-by a later @code{unload-feature}.
-
-In other versions of Emacs, @code{defalias} is a synonym for
-@code{fset}.
-@end defun
-
@node Predicates, Control Structure, Program Structure, Top
@chapter Predicates
Thus @code{(typep @var{object} 'null)} is equivalent to
@code{(null @var{object})}.
+@item
+The type symbol @code{atom} represents all objects that are not cons
+cells. Thus @code{(typep @var{object} 'atom)} is equivalent to
+@code{(atom @var{object})}.
+
@item
The type symbol @code{real} is a synonym for @code{number}, and
@code{fixnum} is a synonym for @code{integer}.
@code{concatenate}, and @code{merge} functions take type-name
arguments to specify the type of sequence to return. @xref{Sequences}.
-@node Equality Predicates, , Type Predicates, Predicates
+@node Equality Predicates, , Type Predicates, Predicates
@section Equality Predicates
@noindent
and @var{b} are numbers of the same type, it compares them for numeric
equality (as if by @code{equal} instead of @code{eq}). This makes a
difference only for versions of Emacs that are compiled with
-floating-point support, such as Emacs 19. Emacs floats are allocated
+floating-point support. Emacs floats are allocated
objects just like cons cells, which means that @code{(eq 3.0 3.0)}
will not necessarily be true---if the two @code{3.0}s were allocated
separately, the pointers will be different even though the numbers are
in this package since Emacs does not distinguish between integers
and characters. In keeping with the idea that strings are less
vector-like in Emacs Lisp, this package's @code{equalp} also will
-not compare strings against vectors of integers. Finally, Common
-Lisp's @code{equalp} compares hash tables without regard to
-ordering, whereas this package simply compares hash tables in
-terms of their underlying structure (which means vectors for Lucid
-Emacs 19 hash tables, or lists for other hash tables).
+not compare strings against vectors of integers.
@end defun
Also note that the Common Lisp functions @code{member} and @code{assoc}
@var{form}.
The following Lisp forms will work as generalized variables, and
-so may legally appear in the @var{place} argument of @code{setf}:
+so may appear in the @var{place} argument of @code{setf}:
@itemize @bullet
@item
@item
The following Emacs-specific functions are also @code{setf}-able.
-(Some of these are defined only in Emacs 19 or only in Lucid Emacs.)
@smallexample
-buffer-file-name marker-position
-buffer-modified-p match-data
-buffer-name mouse-position
-buffer-string overlay-end
-buffer-substring overlay-get
-current-buffer overlay-start
-current-case-table point
-current-column point-marker
-current-global-map point-max
-current-input-mode point-min
-current-local-map process-buffer
-current-window-configuration process-filter
-default-file-modes process-sentinel
-default-value read-mouse-position
-documentation-property screen-height
-extent-data screen-menubar
-extent-end-position screen-width
-extent-start-position selected-window
-face-background selected-screen
-face-background-pixmap selected-frame
-face-font standard-case-table
-face-foreground syntax-table
-face-underline-p window-buffer
-file-modes window-dedicated-p
-frame-height window-display-table
-frame-parameters window-height
-frame-visible-p window-hscroll
-frame-width window-point
-get-register window-start
-getenv window-width
-global-key-binding x-get-cut-buffer
-keymap-parent x-get-cutbuffer
+buffer-file-name marker-position
+buffer-modified-p match-data
+buffer-name mouse-position
+buffer-string overlay-end
+buffer-substring overlay-get
+current-buffer overlay-start
+current-case-table point
+current-column point-marker
+current-global-map point-max
+current-input-mode point-min
+current-local-map process-buffer
+current-window-configuration process-filter
+default-file-modes process-sentinel
+default-value read-mouse-position
+documentation-property screen-height
+extent-data screen-menubar
+extent-end-position screen-width
+extent-start-position selected-window
+face-background selected-screen
+face-background-pixmap selected-frame
+face-font standard-case-table
+face-foreground syntax-table
+face-underline-p window-buffer
+file-modes window-dedicated-p
+frame-height window-display-table
+frame-parameters window-height
+frame-visible-p window-hscroll
+frame-width window-point
+get-register window-start
+getenv window-width
+global-key-binding x-get-cut-buffer
+keymap-parent x-get-cutbuffer
local-key-binding x-get-secondary-selection
-mark x-get-selection
-mark-marker
+mark x-get-selection
+mark-marker
@end smallexample
Most of these have directly corresponding ``set'' functions, like
@item
A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
-where @var{subplace} is itself a legal generalized variable whose
+where @var{subplace} is itself a valid generalized variable whose
current value is a string, and where the value stored is also a
string. The new string is spliced into the specified part of the
destination string. For example:
macros are used in the processing of symbol macros;
@pxref{Macro Bindings}.
-@node Customizing Setf, , Modify Macros, Generalized Variables
+@node Customizing Setf, , Modify Macros, Generalized Variables
@subsection Customizing Setf
@noindent
@code{function} to be passed on to, say, @code{mapcar}.
@end defspec
-@node Macro Bindings, , Function Bindings, Variable Bindings
+@node Macro Bindings, , Function Bindings, Variable Bindings
@subsection Macro Bindings
@noindent
Because they are implemented in terms of Emacs Lisp @code{catch}
and @code{throw}, blocks have the same overhead as actual
@code{catch} constructs (roughly two function calls). However,
-Zawinski and Furuseth's optimizing byte compiler (standard in
-Emacs 19) will optimize away the @code{catch} if the block does
+the optimizing byte compiler will optimize away the @code{catch}
+if the block does
not in fact contain any @code{return} or @code{return-from} calls
that jump to it. This means that @code{do} loops and @code{defun*}
functions which don't use @code{return} don't pay the overhead to
The @code{by} value is always positive, even for downward-counting
loops. Some sort of @code{from} value is required for downward
-loops; @samp{for x downto 5} is not a legal loop clause all by
+loops; @samp{for x downto 5} is not a valid loop clause all by
itself.
@item for @var{var} in @var{list} by @var{function}
Due to a minor implementation restriction, it will not work to have
more than one @code{for} clause iterating over symbols, hash tables,
keymaps, overlays, or intervals in a given @code{loop}. Fortunately,
-it would rarely if ever be useful to do so. It @emph{is} legal to mix
+it would rarely if ever be useful to do so. It @emph{is} valid to mix
one of these types of clauses with other clauses like @code{for ... to}
or @code{while}.
hash table entry.
@item for @var{var} being the key-codes of @var{keymap}
-This clause iterates over the entries in @var{keymap}. In GNU Emacs
-18 and 19, keymaps are either alists or vectors, and key-codes are
-integers or symbols. In Lucid Emacs 19, keymaps are a special new
-data type, and key-codes are symbols or lists of symbols. The
-iteration does not enter nested keymaps or inherited (parent) keymaps.
+This clause iterates over the entries in @var{keymap}.
+The iteration does not enter nested keymaps or inherited (parent) keymaps.
You can use @samp{the key-bindings} to access the commands bound to
the keys rather than the key codes, and you can add a @code{using}
clause to access both the codes and the bindings together.
clause to get the command bindings as well.
@item for @var{var} being the overlays [of @var{buffer}] @dots{}
-This clause iterates over the Emacs 19 ``overlays'' or Lucid
-Emacs ``extents'' of a buffer (the clause @code{extents} is synonymous
+This clause iterates over the ``overlays'' of a buffer
+(the clause @code{extents} is synonymous
with @code{overlays}). If the @code{of} term is omitted, the current
buffer is used.
This clause also accepts optional @samp{from @var{pos}} and
to the previous end position. The clause allows @code{of},
@code{from}, @code{to}, and @code{property} terms, where the latter
term restricts the search to just the specified property. The
-@code{of} term may specify either a buffer or a string. This
-clause is useful only in GNU Emacs 19; in other versions, all
-buffers and strings consist of a single interval.
+@code{of} term may specify either a buffer or a string.
@item for @var{var} being the frames
This clause iterates over all frames, i.e., X window system windows
-open on Emacs files. This clause works only under Emacs 19. The
+open on Emacs files. The
clause @code{screens} is a synonym for @code{frames}. The frames
are visited in @code{next-frame} order starting from
@code{selected-frame}.
explicit mechanism, such as @code{finally return}, to return
the accumulated result.
-It is legal for several accumulation clauses of the same type to
+It is valid for several accumulation clauses of the same type to
accumulate into the same place. From Steele:
@example
@result{} (fred bob ken sue alice joe kris sunshine june)
@end example
-@node Other Clauses, , Accumulation Clauses, Loop Facility
+@node Other Clauses, , Accumulation Clauses, Loop Facility
@subsection Other Clauses
@noindent
iterate over keymaps, overlays, intervals, frames, windows, and
buffers are Emacs-specific extensions.
-@node Multiple Values, , Loop Facility, Control Structure
+@node Multiple Values, , Loop Facility, Control Structure
@section Multiple Values
@noindent
Emacs Lisp, as the byte-code system provides little opportunity
to benefit from type information, and @code{special} declarations
are redundant in a fully dynamically-scoped Lisp. A few
-declarations are meaningful when the optimizing Emacs 19 byte
+declarations are meaningful when the optimizing byte
compiler is being used, however. Under the earlier non-optimizing
compiler, these declarations will effectively be ignored.
The following declarations are all equivalent. Note that the
@code{defsubst} form is a convenient way to define a function
-and declare it inline all at once, but it is available only in
-Emacs 19.
+and declare it inline all at once.
@example
(declaim (inline foo bar))
(eval-when (compile load eval) (proclaim '(inline foo bar)))
-(proclaim-inline foo bar) ; Lucid Emacs only
-(defsubst foo (...) ...) ; instead of defun; Emacs 19 only
+(defsubst foo (...) ...) ; instead of defun
@end example
-@strong{Note:} This declaration remains in effect after the
+@strong{Please note:} this declaration remains in effect after the
containing source file is done. It is correct to use it to
request that a function you have defined should be inlined,
but it is impolite to use it to request inlining of an external
0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
The default level for both qualities is 1.
-In this package, with the Emacs 19 optimizing compiler, the
+In this package, with the optimizing compiler, the
@code{speed} quality is tied to the @code{byte-compile-optimize}
flag, which is set to @code{nil} for @code{(speed 0)} and to
@code{t} for higher settings; and the @code{safety} quality is
(get sym prop) @equiv{} (getf (symbol-plist sym) prop)
@end example
-It is legal to use @code{getf} as a @code{setf} place, in which case
-its @var{place} argument must itself be a legal @code{setf} place.
+It is valid to use @code{getf} as a @code{setf} place, in which case
+its @var{place} argument must itself be a valid @code{setf} place.
The @var{default} argument, if any, is ignored in this context.
The effect is to change (via @code{setcar}) the value cell in the
list that corresponds to @var{property}, or to cons a new property-value
@secno=2
@end iftex
-@node Creating Symbols, , Property Lists, Symbols
+@node Creating Symbols, , Property Lists, Symbols
@section Creating Symbols
@noindent
* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
* Numerical Functions:: `abs', `floor*', etc.
* Random Numbers:: `random*', `make-random-state'
-* Implementation Parameters:: `most-positive-fixnum', `most-positive-float'
+* Implementation Parameters:: `most-positive-float'
@end menu
@iftex
@defun floor* number &optional divisor
This function implements the Common Lisp @code{floor} function.
It is called @code{floor*} to avoid name conflicts with the
-simpler @code{floor} function built-in to Emacs 19.
+simpler @code{floor} function built-in to Emacs.
With one argument, @code{floor*} returns a list of two numbers:
The argument rounded down (toward minus infinity) to an integer,
and the ``remainder'' which would have to be added back to the
first return value to yield the argument again. If the argument
is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
-If the argument is an Emacs 19 floating-point number, the first
+If the argument is a floating-point number, the first
result is a Lisp integer and the second is a Lisp float between
0 (inclusive) and 1 (exclusive).
These definitions are compatible with those in the Quiroz
@file{cl.el} package, except that this package appends @samp{*}
to certain function names to avoid conflicts with existing
-Emacs 19 functions, and that the mechanism for returning
+Emacs functions, and that the mechanism for returning
multiple values is different.
@iftex
integer; each different integer seed will result in a completely
different sequence of random numbers.
-It is legal to print a @code{random-state} object to a buffer or
+It is valid to print a @code{random-state} object to a buffer or
file and later read it back with @code{read}. If a program wishes
to use a sequence of pseudo-random numbers which can be reproduced
later for debugging, it can call @code{(make-random-state t)} to
@code{random-state} object, or @code{nil} otherwise.
@end defun
-@node Implementation Parameters, , Random Numbers, Numbers
+@node Implementation Parameters, , Random Numbers, Numbers
@section Implementation Parameters
@noindent
This package defines several useful constants having to with numbers.
-@defvar most-positive-fixnum
-This constant equals the largest value a Lisp integer can hold.
-It is typically @code{2^23-1} or @code{2^25-1}.
-@end defvar
-
-@defvar most-negative-fixnum
-This constant equals the smallest (most negative) value a Lisp
-integer can hold.
-@end defvar
-
The following parameters have to do with floating-point numbers.
This package determines their values by exercising the computer's
floating-point arithmetic in various ways. Because this operation
function that must be called before the parameters can be used.
@defun cl-float-limits
-This function makes sure that the Common Lisp floating-point
-parameters like @code{most-positive-float} have been initialized.
-Until it is called, these parameters will be @code{nil}. If this
-version of Emacs does not support floats (e.g., most versions of
-Emacs 18), the parameters will remain @code{nil}. If the parameters
-have already been initialized, the function returns immediately.
+This function makes sure that the Common Lisp floating-point parameters
+like @code{most-positive-float} have been initialized. Until it is
+called, these parameters will be @code{nil}. If this version of Emacs
+does not support floats, the parameters will remain @code{nil}. If the
+parameters have already been initialized, the function returns
+immediately.
The algorithm makes assumptions that will be valid for most modern
machines, but will fail if the machine's arithmetic is extremely
@emph{do} specify exactly the order in which the function is called
so side effects are perfectly acceptable in those cases.)
-Strings in GNU Emacs 19 may contain ``text properties'' as well
+Strings may contain ``text properties'' as well
as character data. Except as noted, it is undefined whether or
not text properties are preserved by sequence functions. For
example, @code{(remove* ?A @var{str})} may or may not preserve
@end defun
@defun mapc function seq &rest more-seqs
-This function is like @code{mapcar*}, except that the values
-returned by @var{function} are ignored and thrown away rather
-than being collected into a list. The return value of @code{mapc}
-is @var{seq}, the first sequence.
+This function is like @code{mapcar*}, except that the values returned
+by @var{function} are ignored and thrown away rather than being
+collected into a list. The return value of @code{mapc} is @var{seq},
+the first sequence. This function is more general than the Emacs
+primitive @code{mapc}.
@end defun
@defun mapl function list &rest more-lists
The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
@code{delete-if}, and @code{delete-if-not} are defined similarly.
-@defun remove item list
-This function removes from @var{list} all elements which are
-@code{equal} to @var{item}. This package defines it for symmetry
-with @code{delete}, even though @code{remove} is not built-in to
-Emacs 19.
-@end defun
-
-@defun remq item list
-This function removes from @var{list} all elements which are
-@code{eq} to @var{item}. This package defines it for symmetry
-with @code{delq}, even though @code{remq} is not built-in to
-Emacs 19.
-@end defun
-
@defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
This function returns a copy of @var{seq} with duplicate elements
removed. Specifically, if two elements from the sequence match
function finds the @emph{rightmost} matching subsequence.
@end defun
-@node Sorting Sequences, , Searching Sequences, Sequences
+@node Sorting Sequences, , Searching Sequences, Sequences
@section Sorting Sequences
@defun sort* seq predicate @t{&key :key}
@var{predicate}.
@end defun
-@node Lists, Hash Tables, Sequences, Top
+@node Lists, Structures, Sequences, Top
@chapter Lists
@noindent
The functions described here operate on lists.
@menu
-* List Functions:: `caddr', `first', `last*', `list*', etc.
+* List Functions:: `caddr', `first', `list*', etc.
* Substitution of Expressions:: `subst', `sublis', etc.
* Lists as Sets:: `member*', `adjoin', `union', etc.
* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
@code{length} function would get stuck if given a circular list.)
@end defun
-@defun last* x &optional n
-This function returns the last cons, or the @var{n}th-to-last cons,
-of the list @var{x}. If @var{n} is omitted it defaults to 1.
-The ``last cons'' means the first cons cell of the list whose
-@code{cdr} is not another cons cell. (For normal lists, the
-@code{cdr} of the last cons will be @code{nil}.) This function
-returns @code{nil} if @var{x} is @code{nil} or shorter than
-@var{n}. Note that the last @emph{element} of the list is
-@code{(car (last @var{x}))}.
-
-The Emacs function @code{last} does the same thing
-except that it does not handle the optional argument @var{n}.
-@end defun
-
-@defun butlast x &optional n
-This function returns the list @var{x} with the last element,
-or the last @var{n} elements, removed. If @var{n} is greater
-than zero it makes a copy of the list so as not to damage the
-original list. In general, @code{(append (butlast @var{x} @var{n})
-(last @var{x} @var{n}))} will return a list equal to @var{x}.
-@end defun
-
-@defun nbutlast x &optional n
-This is a version of @code{butlast} that works by destructively
-modifying the @code{cdr} of the appropriate element, rather than
-making a copy of the list.
-@end defun
-
@defun list* arg &rest others
This function constructs a list of its arguments. The final
argument becomes the @code{cdr} of the last cell constructed.
@xref{Sequences}.
Note that this function's name is suffixed by @samp{*} to avoid
-the incompatible @code{member} function defined in Emacs 19.
+the incompatible @code{member} function defined in Emacs.
(That function uses @code{equal} for comparisons; it is equivalent
to @code{(member* @var{item} @var{list} :test 'equal)}.)
@end defun
also appears in @var{list2}.
@end defun
-@node Association Lists, , Lists as Sets, Lists
+@node Association Lists, , Lists as Sets, Lists
@section Association Lists
@noindent
@var{alist})}.
@end defun
-@node Hash Tables, Structures, Lists, Top
-@chapter Hash Tables
-
-@noindent
-A @dfn{hash table} is a data structure that maps ``keys'' onto
-``values.'' Keys and values can be arbitrary Lisp data objects.
-Hash tables have the property that the time to search for a given
-key is roughly constant; simpler data structures like association
-lists take time proportional to the number of entries in the list.
-
-@defun make-hash-table @t{&key :test :size}
-This function creates and returns a hash-table object whose
-function for comparing elements is @code{:test} (@code{eql}
-by default), and which is allocated to fit about @code{:size}
-elements. The @code{:size} argument is purely advisory; the
-table will stretch automatically if you store more elements in
-it. If @code{:size} is omitted, a reasonable default is used.
-
-Common Lisp allows only @code{eq}, @code{eql}, @code{equal},
-and @code{equalp} as legal values for the @code{:test} argument.
-In this package, any reasonable predicate function will work,
-though if you use something else you should check the details of
-the hashing function described below to make sure it is suitable
-for your predicate.
-
-Some versions of Emacs (like Lucid Emacs 19) include a built-in
-hash table type; in these versions, @code{make-hash-table} with
-a test of @code{eq} will use these built-in hash tables. In all
-other cases, it will return a hash-table object which takes the
-form of a list with an identifying ``tag'' symbol at the front.
-All of the hash table functions in this package can operate on
-both types of hash table; normally you will never know which
-type is being used.
-
-This function accepts the additional Common Lisp keywords
-@code{:rehash-size} and @code{:rehash-threshold}, but it ignores
-their values.
-@end defun
-
-@defun gethash key table &optional default
-This function looks up @var{key} in @var{table}. If @var{key}
-exists in the table, in the sense that it matches any of the existing
-keys according to the table's test function, then the associated value
-is returned. Otherwise, @var{default} (or @code{nil}) is returned.
-
-To store new data in the hash table, use @code{setf} on a call to
-@code{gethash}. If @var{key} already exists in the table, the
-corresponding value is changed to the stored value. If @var{key}
-does not already exist, a new entry is added to the table and the
-table is reallocated to a larger size if necessary. The @var{default}
-argument is allowed but ignored in this case. The situation is
-exactly analogous to that of @code{get*}; @pxref{Property Lists}.
-@end defun
-
-@defun remhash key table
-This function removes the entry for @var{key} from @var{table}.
-If an entry was removed, it returns @code{t}. If @var{key} does
-not appear in the table, it does nothing and returns @code{nil}.
-@end defun
-
-@defun clrhash table
-This function removes all the entries from @var{table}, leaving
-an empty hash table.
-@end defun
-
-@defun maphash function table
-This function calls @var{function} for each entry in @var{table}.
-It passes two arguments to @var{function}, the key and the value
-of the given entry. The return value of @var{function} is ignored;
-@var{maphash} itself returns @code{nil}. @xref{Loop Facility}, for
-an alternate way of iterating over hash tables.
-@end defun
-
-@defun hash-table-count table
-This function returns the number of entries in @var{table}.
-@strong{Warning:} The current implementation of Lucid Emacs 19
-hash-tables does not decrement the stored @code{count} when
-@code{remhash} removes an entry. Therefore, the return value of
-this function is not dependable if you have used @code{remhash}
-on the table and the table's test is @code{eq}. A slower, but
-reliable, way to count the entries is @code{(loop for x being the
-hash-keys of @var{table} count t)}.
-@end defun
-
-@defun hash-table-p object
-This function returns @code{t} if @var{object} is a hash table,
-@code{nil} otherwise. It recognizes both types of hash tables
-(both Lucid Emacs built-in tables and tables implemented with
-special lists.)
-@end defun
-
-Sometimes when dealing with hash tables it is useful to know the
-exact ``hash function'' that is used. This package implements
-hash tables using Emacs Lisp ``obarrays,'' which are the same
-data structure that Emacs Lisp uses to keep track of symbols.
-Each hash table includes an embedded obarray. Key values given
-to @code{gethash} are converted by various means into strings,
-which are then looked up in the obarray using @code{intern} and
-@code{intern-soft}. The symbol, or ``bucket,'' corresponding to
-a given key string includes as its @code{symbol-value} an association
-list of all key-value pairs which hash to that string. Depending
-on the test function, it is possible for many entries to hash to
-the same bucket. For example, if the test is @code{eql}, then the
-symbol @code{foo} and two separately built strings @code{"foo"} will
-create three entries in the same bucket. Search time is linear
-within buckets, so hash tables will be most effective if you arrange
-not to store too many things that hash the same.
-
-The following algorithm is used to convert Lisp objects to hash
-strings:
-
-@itemize @bullet
-@item
-Strings are used directly as hash strings. (However, if the test
-function is @code{equalp}, strings are @code{downcase}d first.)
-
-@item
-Symbols are hashed according to their @code{symbol-name}.
-
-@item
-Integers are hashed into one of 16 buckets depending on their value
-modulo 16. Floating-point numbers are truncated to integers and
-hashed modulo 16.
-
-@item
-Cons cells are hashed according to their @code{car}s; nonempty vectors
-are hashed according to their first element.
-
-@item
-All other types of objects hash into a single bucket named @code{"*"}.
-@end itemize
-
-@noindent
-Thus, for example, searching among many buffer objects in a hash table
-will devolve to a (still fairly fast) linear-time search through a
-single bucket, whereas searching for different symbols will be very
-fast since each symbol will, in general, hash into its own bucket.
-
-The size of the obarray in a hash table is automatically adjusted
-as the number of elements increases.
-
-As a special case, @code{make-hash-table} with a @code{:size} argument
-of 0 or 1 will create a hash-table object that uses a single association
-list rather than an obarray of many lists. For very small tables this
-structure will be more efficient since lookup does not require
-converting the key to a string or looking it up in an obarray.
-However, such tables are guaranteed to take time proportional to
-their size to do a search.
-
@iftex
@chapno=18
@end iftex
-@node Structures, Assertions, Hash Tables, Top
+@node Structures, Assertions, Lists, Top
@chapter Structures
@noindent
do not appear in the argument list are initialized based on the
@var{default-value} in their slot descriptor. Also, @code{&optional}
and @code{&key} arguments which don't specify defaults take their
-defaults from the slot descriptor. It is legal to include arguments
+defaults from the slot descriptor. It is valid to include arguments
which don't correspond to slot names; these are useful if they are
referred to in the defaults for optional, keyword, or @code{&aux}
arguments which @emph{do} correspond to slots.
Common Lisp compliance has in general not been sacrificed for the
sake of efficiency. A few exceptions have been made for cases
where substantial gains were possible at the expense of marginal
-incompatibility. One example is the use of @code{memq} (which is
-treated very efficiently by the byte-compiler) to scan for keyword
-arguments; this can become confused in rare cases when keyword
-symbols are used as both keywords and data values at once. This
-is extremely unlikely to occur in practical code, and the use of
-@code{memq} allows functions with keyword arguments to be nearly
-as fast as functions that use @code{&optional} arguments.
+incompatibility.
The Common Lisp standard (as embodied in Steele's book) uses the
phrase ``it is an error if'' to indicate a situation which is not
@appendixsec Optimizing Compiler
@noindent
-The byte-compiler that comes with Emacs 18 normally fails to expand
-macros that appear in top-level positions in the file (i.e., outside
-of @code{defun}s or other enclosing forms). This would have
-disastrous consequences to programs that used such top-level macros
-as @code{defun*}, @code{eval-when}, and @code{defstruct}. To
-work around this problem, the @dfn{CL} package patches the Emacs
-18 compiler to expand top-level macros. This patch will apply to
-your own macros, too, if they are used in a top-level context.
-The patch will not harm versions of the Emacs 18 compiler which
-have already had a similar patch applied, nor will it affect the
-optimizing Emacs 19 byte-compiler written by Jamie Zawinski and
-Hallvard Furuseth. The patch is applied to the byte compiler's
-code in Emacs' memory, @emph{not} to the @file{bytecomp.elc} file
-stored on disk.
-
-Use of the Emacs 19 compiler is highly recommended; many of the Common
+Use of the optimizing Emacs compiler is highly recommended; many of the Common
Lisp macros emit
code which can be improved by optimization. In particular,
@code{block}s (whether explicit or implicit in constructs like
keyword does not work in @code{defmacro} argument lists (except
inside recursive argument lists).
-In order to allow an efficient implementation, keyword arguments use
-a slightly cheesy parser which may be confused if a keyword symbol
-is passed as the @emph{value} of another keyword argument.
-(Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})}
-is used to scan for @code{:@var{keyword}} among the supplied
-keyword arguments.)
-
The @code{eql} and @code{equal} predicates do not distinguish
between IEEE floating-point plus and minus zero. The @code{equalp}
predicate has several differences with Common Lisp; @pxref{Predicates}.
by @samp{*} in this package to avoid collision with existing
functions in Emacs. The older package simply
redefined these functions, overwriting the built-in meanings and
-causing serious portability problems with Emacs 19. (Some more
+causing serious portability problems. (Some more
recent versions of the Quiroz package changed the names to
@code{cl-member}, etc.; this package defines the latter names as
aliases for @code{member*}, etc.)
results in a list rather than as multiple values. Note that
older versions of the old package used the unadorned names
@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
-these names because they conflict with Emacs 19 built-ins.
+these names because they conflict with Emacs built-ins.
@node Porting Common Lisp, Function Index, Old CL Compatibility, Top
@appendix Porting Common Lisp
one, some of the features in this package are not fully compliant
with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
are also quite a few features that this package does not provide
-at all. Here are some major omissions that you will want watch out
+at all. Here are some major omissions that you will want to watch out
for when bringing Common Lisp code into Emacs.
@itemize @bullet
@item
Vector constants use square brackets in Emacs Lisp, but
@code{#(a b c)} notation in Common Lisp. To further complicate
-matters, Emacs 19 introduces its own @code{#(} notation for
+matters, Emacs has its own @code{#(} notation for
something entirely different---strings with properties.
@item
@printindex fn
-@node Variable Index, , Function Index, Top
+@node Variable Index, , Function Index, Top
@unnumbered Variable Index
@printindex vr
@setchapternewpage odd
@contents
@bye
+
+@ignore
+ arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8
+@end ignore