[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110774: Further edits for doc/mis
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110774: Further edits for doc/misc/cl.texi |
Date: |
Sat, 03 Nov 2012 10:56:30 -0700 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 110774
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Sat 2012-11-03 10:56:30 -0700
message:
Further edits for doc/misc/cl.texi
* cl.texi: Further general copyedits.
(List Functions): Remove copy-tree, standard elisp for some time.
(Efficiency Concerns): Comment out examples that no longer apply.
(Compiler Optimizations): Rename from "Optimizing Compiler"; reword.
modified:
doc/misc/ChangeLog
doc/misc/cl.texi
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2012-11-03 01:19:40 +0000
+++ b/doc/misc/ChangeLog 2012-11-03 17:56:30 +0000
@@ -1,6 +1,9 @@
2012-11-03 Glenn Morris <address@hidden>
* cl.texi: Further general copyedits.
+ (List Functions): Remove copy-tree, standard elisp for some time.
+ (Efficiency Concerns): Comment out examples that no longer apply.
+ (Compiler Optimizations): Rename from "Optimizing Compiler"; reword.
2012-11-02 Glenn Morris <address@hidden>
=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi 2012-11-03 01:19:40 +0000
+++ b/doc/misc/cl.texi 2012-11-03 17:56:30 +0000
@@ -2867,6 +2867,7 @@
This function creates a new, uninterned symbol (using @code{make-symbol})
with a unique name. (The name of an uninterned symbol is relevant
only if the symbol is printed.) By default, the name is generated
address@hidden FIXME no longer true?
from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
@samp{G1002}, etc. If the optional argument @var{x} is a string, that
string is used as a prefix instead of @samp{G}. Uninterned symbols
@@ -3207,7 +3208,7 @@
The @code{:key} argument should be passed either @code{nil}, or a
function of one argument. This key function is used as a filter
through which the elements of the sequence are seen; for example,
address@hidden(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}:
address@hidden(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}.
It searches for an element of the list whose @sc{car} equals
@code{x}, rather than for an element which equals @code{x} itself.
If @code{:key} is omitted or @code{nil}, the filter is effectively
@@ -3225,7 +3226,7 @@
@code{:test-not} to give a function which returns @emph{false} to
indicate a match. The default test function is @code{eql}.
-Many functions which take @var{item} and @code{:test} or @code{:test-not}
+Many functions that take @var{item} and @code{:test} or @code{:test-not}
arguments also come in @code{-if} and @code{-if-not} varieties,
where a @var{predicate} function is passed instead of @var{item},
and sequence elements match if the predicate returns true on them
@@ -3239,7 +3240,7 @@
to remove all zeros from sequence @code{seq}.
Some operations can work on a subsequence of the argument sequence;
-these function take @code{:start} and @code{:end} arguments which
+these function take @code{:start} and @code{:end} arguments, which
default to zero and the length of the sequence, respectively.
Only elements between @var{start} (inclusive) and @var{end}
(exclusive) are affected by the operation. The @var{end} argument
@@ -3347,7 +3348,7 @@
@defun cl-some predicate seq &rest more-seqs
This function calls @var{predicate} on each element of @var{seq}
in turn; if @var{predicate} returns a address@hidden value,
address@hidden returns that value, otherwise it returns @code{nil}.
address@hidden returns that value, otherwise it returns @code{nil}.
Given several sequence arguments, it steps through the sequences
in parallel until the shortest one runs out, just as in
@code{cl-mapcar}. You can rely on the left-to-right order in which
@@ -3396,7 +3397,7 @@
@equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
@end example
-If @code{:key} is specified, it is a function of one argument which
+If @code{:key} is specified, it is a function of one argument, which
is called on each of the sequence elements in turn.
If @code{:initial-value} is specified, it is effectively added to the
@@ -3465,7 +3466,7 @@
If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
will work correctly even if the regions indicated by the start
and end arguments overlap. However, if @var{seq1} and @var{seq2}
-are lists which share storage but are not @code{eq}, and the
+are lists that share storage but are not @code{eq}, and the
start and end arguments specify overlapping regions, the effect
is undefined.
@end defun
@@ -3488,7 +3489,7 @@
@end defun
@defun cl-delete item seq @t{&key :test :test-not :key :count :start :end
:from-end}
-This deletes all elements of @var{seq} which match @var{item}.
+This deletes all elements of @var{seq} that match @var{item}.
It is a destructive operation. Since Emacs Lisp does not support
stretchable strings or vectors, this is the same as @code{cl-remove}
for those sequence types. On lists, @code{cl-remove} will copy the
@@ -3588,7 +3589,7 @@
and @code{:key}), the function returns @code{nil}. If there is
a mismatch, the function returns the index (relative to @var{seq1})
of the first mismatching element. This will be the leftmost pair of
-elements which do not match, or the position at which the shorter of
+elements that do not match, or the position at which the shorter of
the two otherwise-matching sequences runs out.
If @code{:from-end} is true, then the elements are compared from right
@@ -3603,7 +3604,7 @@
@defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1
:end1 :start2 :end2}
This function searches @var{seq2} for a subsequence that matches
@var{seq1} (or part of it specified by @code{:start1} and
address@hidden:end1}.) Only matches which fall entirely within the region
address@hidden:end1}). Only matches that fall entirely within the region
defined by @code{:start2} and @code{:end2} will be considered.
The return value is the index of the leftmost element of the
leftmost match, relative to the start of @var{seq2}, or @code{nil}
@@ -3614,7 +3615,7 @@
@node Sorting Sequences
@section Sorting Sequences
address@hidden clsort seq predicate @t{&key :key}
address@hidden cl-sort seq predicate @t{&key :key}
This function sorts @var{seq} into increasing order as determined
by using @var{predicate} to compare pairs of elements. @var{predicate}
should return true (address@hidden) if and only if its first argument
@@ -3625,7 +3626,7 @@
This function differs from Emacs's built-in @code{sort} in that it
can operate on any type of sequence, not just lists. Also, it
-accepts a @code{:key} argument which is used to preprocess data
+accepts a @code{:key} argument, which is used to preprocess data
fed to the @var{predicate} function. For example,
@example
@@ -3636,7 +3637,7 @@
sorts @var{data}, a sequence of strings, into increasing alphabetical
order without regard to case. A @code{:key} function of @code{car}
would be useful for sorting association lists. It should only be a
-simple accessor though, it's used heavily in the current
+simple accessor though, since it's used heavily in the current
implementation.
The @code{cl-sort} function is destructive; it sorts lists by actually
@@ -3692,7 +3693,7 @@
@defun cl-caddr x
This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
-Likewise, this package defines all 28 @address@hidden functions
+Likewise, this package defines all 24 @address@hidden functions
where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
All of these functions are @code{setf}-able, and calls to them
are expanded inline by the byte-compiler for maximum efficiency.
@@ -3720,7 +3721,8 @@
@code{(length @var{x})}, except that if @var{x} is a circular
list (where the @sc{cdr}-chain forms a loop rather than terminating
with @code{nil}), this function returns @code{nil}. (The regular
address@hidden function would get stuck if given a circular list.)
address@hidden function would get stuck if given a circular list.
+See also the @code{safe-length} function.)
@end defun
@defun cl-list* arg &rest others
@@ -3748,18 +3750,6 @@
dotted lists like @code{(1 2 . 3)} correctly.
@end defun
address@hidden copy-tree x &optional vecp
-This function returns a copy of the tree of cons cells @var{x}.
address@hidden FIXME? cl-copy-list is not an alias of copy-sequence.
-Unlike @code{copy-sequence} (and its alias @code{cl-copy-list}),
-which copies only along the @sc{cdr} direction, this function
-copies (recursively) along both the @sc{car} and the @sc{cdr}
-directions. If @var{x} is not a cons cell, the function simply
-returns @var{x} unchanged. If the optional @var{vecp} argument
-is true, this function copies vectors (recursively) as well as
-cons cells.
address@hidden defun
-
@defun cl-tree-equal x y @t{&key :test :test-not :key}
This function compares two trees of cons cells. If @var{x} and
@var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are
@@ -3822,7 +3812,7 @@
@section Lists as Sets
@noindent
-These functions perform operations on lists which represent sets
+These functions perform operations on lists that represent sets
of elements.
@defun cl-member item list @t{&key :test :test-not :key}
@@ -3835,13 +3825,14 @@
The standard Emacs lisp function @code{member} uses @code{equal} for
comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
-:test 'equal)}.
+:test 'equal)}. With no keyword arguments, @code{cl-member} is
+equivalent to @code{memq}.
@end defun
@findex cl-member-if
@findex cl-member-if-not
The @code{cl-member-if} and @code{cl-member-if-not} functions
-analogously search for elements which satisfy a given predicate.
+analogously search for elements that satisfy a given predicate.
@defun cl-tailp sublist list
This function returns @code{t} if @var{sublist} is a sublist of
@@ -3860,11 +3851,11 @@
@end defun
@defun cl-union list1 list2 @t{&key :test :test-not :key}
-This function combines two lists which represent sets of items,
+This function combines two lists that represent sets of items,
returning a list that represents the union of those two sets.
-The result list will contain all items which appear in @var{list1}
+The resulting list contains all items that appear in @var{list1}
or @var{list2}, and no others. If an item appears in both
address@hidden and @var{list2} it will be copied only once. If
address@hidden and @var{list2} it is copied only once. If
an item is duplicated in @var{list1} or @var{list2}, it is
undefined whether or not that duplication will survive in the
result list. The order of elements in the result list is also
@@ -3879,7 +3870,7 @@
@defun cl-intersection list1 list2 @t{&key :test :test-not :key}
This function computes the intersection of the sets represented
by @var{list1} and @var{list2}. It returns the list of items
-which appear in both @var{list1} and @var{list2}.
+that appear in both @var{list1} and @var{list2}.
@end defun
@defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
@@ -3929,7 +3920,7 @@
element whose @sc{car} matches (in the sense of @code{:test},
@code{:test-not}, and @code{:key}, or by comparison with @code{eql})
a given @var{item}. It returns the matching element, if any,
-otherwise @code{nil}. It ignores elements of @var{a-list} which
+otherwise @code{nil}. It ignores elements of @var{a-list} that
are not cons cells. (This corresponds to the behavior of
@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
@code{assoc} ignores @code{nil}s but considers any other non-cons
@@ -3990,11 +3981,11 @@
@end example
@noindent
-defines a struct type called @code{person} which contains three
+defines a struct type called @code{person} that contains three
slots. Given a @code{person} object @var{p}, you can access those
slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
and @code{(person-sex @var{p})}. You can also change these slots by
-using @code{setf} on any of these place forms:
+using @code{setf} on any of these place forms, for example:
@example
(cl-incf (person-age birthday-boy))
@@ -4011,10 +4002,10 @@
object of the same type whose slots are @code{eq} to those of @var{p}.
Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
-true if @var{x} looks like a @code{person}, false otherwise. (Again,
+true if @var{x} looks like a @code{person}, and false otherwise. (Again,
in Common Lisp this predicate would be exact; in Emacs Lisp the
best it can do is verify that @var{x} is a vector of the correct
-length which starts with the correct tag symbol.)
+length that starts with the correct tag symbol.)
Accessors like @code{person-name} normally check their arguments
(effectively using @code{person-p}) and signal an error if the
@@ -4051,7 +4042,7 @@
symbol followed by any number of @dfn{struct options}; each @var{slot}
is either a slot symbol or a list of the form @samp{(@var{slot-name}
@var{default-value} @address@hidden)}. The @var{default-value}
-is a Lisp form which is evaluated any time an instance of the
+is a Lisp form that is evaluated any time an instance of the
structure type is created without specifying that slot's value.
Common Lisp defines several slot options, but the only one
@@ -4109,11 +4100,11 @@
initialized from the corresponding argument. Slots whose names
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
+and @code{&key} arguments that don't specify defaults take their
defaults from the slot descriptor. It is valid to include arguments
-which don't correspond to slot names; these are useful if they are
+that 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.
+arguments that @emph{do} correspond to slots.
You can specify any number of full-format @code{:constructor}
options on a structure. The default constructor is still generated
@@ -4154,7 +4145,7 @@
all copier functions are simply synonyms for @code{copy-sequence}.)
@item :predicate
-The argument is an alternate name for the predicate which recognizes
+The argument is an alternate name for the predicate that recognizes
objects of this type. The default is @address@hidden @code{nil}
means not to generate a predicate function. (If the @code{:type}
option is used without the @code{:named} option, no predicate is
@@ -4214,7 +4205,7 @@
@item :print-function
In full Common Lisp, this option allows you to specify a function
-which is called to print an instance of the structure type. The
+that is called to print an instance of the structure type. The
Emacs Lisp system offers no hooks into the Lisp printer which would
allow for such a feature, so this package simply ignores
@code{:print-function}.
@@ -4391,7 +4382,7 @@
This function takes a single Lisp form as an argument and inserts
a nicely formatted copy of it in the current buffer (which must be
in Lisp mode so that indentation works properly). It also expands
-all Lisp macros which appear in the form. The easiest way to use
+all Lisp macros that appear in the form. The easiest way to use
this function is to go to the @file{*scratch*} buffer and type, say,
@example
@@ -4400,7 +4391,7 @@
@noindent
and type @kbd{C-x C-e} immediately after the closing parenthesis;
-the expansion
+an expansion similar to:
@example
(cl-block nil
@@ -4421,7 +4412,11 @@
If the optional argument @var{full} is true, then @emph{all}
macros are expanded, including @code{cl-block}, @code{cl-eval-when},
and compiler macros. Expansion is done as if @var{form} were
-a top-level form in a file being compiled. For example,
+a top-level form in a file being compiled.
+
address@hidden FIXME none of these examples are still applicable.
address@hidden
+For example,
@example
(cl-prettyexpand '(cl-pushnew 'x list))
@@ -4431,16 +4426,12 @@
(cl-prettyexpand '(caddr (cl-member 'a list)) t)
@print{} (car (cdr (cdr (memq 'a list))))
@end example
address@hidden ignore
Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
have built-in compiler macros to optimize them in common cases.
@end defun
address@hidden
address@hidden
-
address@hidden example
address@hidden ifinfo
@appendixsec Error Checking
@noindent
@@ -4450,7 +4441,7 @@
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
+phrase ``it is an error if'' to indicate a situation that is not
supposed to arise in complying programs; implementations are strongly
encouraged but not required to signal an error in these situations.
This package sometimes omits such error checking in the interest of
@@ -4472,20 +4463,16 @@
defined in this package such as @code{cl-find} and @code{cl-member}
do check their keyword arguments for validity.
address@hidden
address@hidden
-
address@hidden example
address@hidden ifinfo
address@hidden Optimizing Compiler
address@hidden Compiler Optimizations
@noindent
-Use of the optimizing Emacs compiler is highly recommended; many of the Common
+Changing the value of @code{byte-optimize} from the default @code{t}
+is highly discouraged; many of the Common
Lisp macros emit
-code which can be improved by optimization. In particular,
+code that can be improved by optimization. In particular,
@code{cl-block}s (whether explicit or implicit in constructs like
@code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
-byte-compiler removes @code{cl-block}s which are not actually
+byte-compiler removes @code{cl-block}s that are not actually
referenced by @code{cl-return} or @code{cl-return-from} inside the block.
@node Common Lisp Compatibility
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/emacs-24 r110774: Further edits for doc/misc/cl.texi,
Glenn Morris <=