]> code.delx.au - gnu-emacs/blobdiff - man/cl.texi
(Fformat): Add comment about the treatment of 0 as a multibyte
[gnu-emacs] / man / cl.texi
index b5fb683b7c9c6ca520977307c24bf13e098c5f6b..6c717066e22e6b816af9a24e69e1cd0dae946bd4 100644 (file)
@@ -2,21 +2,12 @@
 @setfilename ../info/cl
 @settitle Common Lisp Extensions
 
 @setfilename ../info/cl
 @settitle Common Lisp Extensions
 
-@dircategory Emacs
-@direntry
-* CL: (cl).            Partial Common Lisp support for Emacs Lisp.
-@end direntry
-
-@iftex
-@finalout
-@end iftex
-
-@ifinfo
+@copying
 This file documents the GNU Emacs Common Lisp emulation package.
 
 This file documents the GNU Emacs Common Lisp emulation package.
 
-Copyright (C) 1993 Free Software Foundation, Inc.
-
+Copyright (C) 1993, 2002 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.1 or
 any later version published by the Free Software Foundation; with no
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
 any later version published by the Free Software Foundation; with no
@@ -33,7 +24,15 @@ 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.
 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 ifinfo
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* CL: (cl).            Partial Common Lisp support for Emacs Lisp.
+@end direntry
+
+@finalout
 
 @titlepage
 @sp 6
 
 @titlepage
 @sp 6
@@ -46,26 +45,8 @@ license to the document, as described in section 6 of the license.
 @center Dave Gillespie
 @center daveg@@synaptics.com
 @page
 @center Dave Gillespie
 @center daveg@@synaptics.com
 @page
-
 @vskip 0pt plus 1filll
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1993 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 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.
+@insertcopying
 @end titlepage
 
 @node Top, Overview, (dir), (dir)
 @end titlepage
 
 @node Top, Overview, (dir), (dir)
@@ -121,6 +102,16 @@ control structures to Emacs Lisp.  While not a 100% complete
 implementation of Common Lisp, @dfn{CL} adds enough functionality
 to make Emacs Lisp programming significantly more convenient.
 
 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:
 
 Some Common Lisp features have been omitted from this package
 for various reasons:
 
@@ -280,7 +271,7 @@ defun*        defsubst*     defmacro*     function*
 member*       assoc*        rassoc*       get*
 remove*       delete*       mapcar*       sort*
 floor*        ceiling*      truncate*     round*
 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
 @end example
 
 Internal function and variable names in the package are prefixed
@@ -299,7 +290,7 @@ they do not cause other components like @file{cl-extra} to be loaded.
 @example
 eql           floatp-safe   endp
 evenp         oddp          plusp         minusp
 @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]
 list*         ldiff         rest          first .. tenth
 copy-list     subst         mapcar* [2]
 adjoin [3]    acons         pairlis       pop [4]
@@ -498,19 +489,6 @@ accepts other keyword arguments which are passed on to the
 keep both @code{find-thing} and @code{member*} from complaining
 about each others' keywords in the arguments.
 
 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
 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
@@ -3373,7 +3351,7 @@ which were left out of Emacs Lisp.
 * Predicates on Numbers::       `plusp', `oddp', `floatp-safe', etc.
 * Numerical Functions::         `abs', `floor*', etc.
 * Random Numbers::              `random*', `make-random-state'
 * 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
 @end menu
 
 @iftex
@@ -3580,16 +3558,6 @@ This predicate returns @code{t} if @var{object} is a
 @noindent
 This package defines several useful constants having to with numbers.
 
 @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
 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
@@ -3808,10 +3776,11 @@ that it passes in the list pointers themselves rather than the
 @end defun
 
 @defun mapc function seq &rest more-seqs
 @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
 @end defun
 
 @defun mapl function list &rest more-lists
@@ -4160,7 +4129,7 @@ a merged sequence which is (stably) sorted according to
 The functions described here operate on lists.
 
 @menu
 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'
 * Substitution of Expressions::   `subst', `sublis', etc.
 * Lists as Sets::                 `member*', `adjoin', `union', etc.
 * Association Lists::             `assoc*', `rassoc*', `acons', `pairlis'
@@ -4206,34 +4175,6 @@ with @code{nil}), this function returns @code{nil}.  (The regular
 @code{length} function would get stuck if given a circular list.)
 @end defun
 
 @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.
 @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.
@@ -4991,13 +4932,7 @@ have built-in compiler macros to optimize them in common cases.
 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
 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
 
 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
@@ -5057,13 +4992,6 @@ which understand full-featured argument lists.  The @code{&whole}
 keyword does not work in @code{defmacro} argument lists (except
 inside recursive argument lists).
 
 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}.
 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}.