From: Glenn Morris Date: Thu, 25 Dec 2014 00:55:57 +0000 (-0800) Subject: * doc/lispref/sequences.texi (Sequence Functions): Copyedits. X-Git-Tag: emacs-25.0.90~2634^2~12 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=218520e97c52bf43b82e9be1709b3462bf6627aa;p=emacs.git * doc/lispref/sequences.texi (Sequence Functions): Copyedits. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 84654387dcd..56a073035cf 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,7 @@ 2014-12-25 Glenn Morris + * sequences.texi (Sequence Functions): Copyedits. + * control.texi (Pattern matching case statement): * positions.texi (List Motion): * streams.texi (Output Functions): diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 8f8cfe72fa3..b1e315c7987 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -217,14 +217,14 @@ y @result{} [foo (69 2)] @end example @end defun -@defun reverse seq +@defun reverse sequence @cindex string reverse @cindex list reverse @cindex vector reverse @cindex sequence reverse This function creates a new sequence whose elements are the elements -of @var{seq}, but in reverse order. The original argument @var{seq} -is @emph{not} altered. Note that char-table cannot be reversed. +of @var{sequence}, but in reverse order. The original argument @var{sequence} +is @emph{not} altered. Note that char-tables cannot be reversed. @example @group @@ -260,12 +260,12 @@ x @end example @end defun -@defun nreverse seq +@defun nreverse sequence @cindex reversing a string @cindex reversing a list @cindex reversing a vector - This function reverses the order of the elements of @var{seq}. -Unlike @code{reverse} the original @var{seq} may be modified. + This function reverses the order of the elements of @var{sequence}. +Unlike @code{reverse} the original @var{sequence} may be modified. For example: @@ -421,22 +421,20 @@ useful example of @code{sort}. @cindex sequence functions in seq @cindex seq library - The @file{seq} library provides the following additional sequence + The @file{seq.el} library provides the following additional sequence manipulation macros and functions, prefixed with @code{seq-}. To use -them, you need to load the @file{seq} library first. +them, you must first load the @file{seq} library. - All functions defined in the @code{seq} library are free of -side-effects, meaning that sequence(s) passed as argument(s) to -functions defined in @code{seq} are not modified. + All functions defined in this library are free of side-effects; +i.e., they do not modify any sequence (list, vector, or string) that +you pass as an argument. Unless otherwise stated, the result is a +sequence of the same type as the input. For those functions that take +a predicate, this should be a function of one argument. -@defun seq-drop seq n - This function returns a sequence of all but the first @var{n} -elements of the sequence @var{seq}. - -@var{seq} may be a list, vector or string and @var{n} must be an -integer. The result is the same type of sequence as @var{seq}. - -If @var{n} is a negative integer or zero, @var{seq} is returned. +@defun seq-drop sequence n + This function returns all but the first @var{n} (an integer) +elements of @var{sequence}. If @var{n} is negative or zero, +the result is @var{sequence}. @example @group @@ -450,14 +448,10 @@ If @var{n} is a negative integer or zero, @var{seq} is returned. @end example @end defun -@defun seq-take seq n - This function returns a sequence of the first @var{n} elements of -@var{seq}. - -@var{seq} may be a list, vector or string and @var{n} must be an -integer. The result is the same type of sequence as @var{seq}. - -If @var{n} is a negative integer or zero, an empty sequence is returned. +@defun seq-take sequence n + This function returns the first @var{n} (an integer) elements of +@var{sequence}. If @var{n} is negative or zero, the result +is @code{nil}. @example @group @@ -471,17 +465,9 @@ If @var{n} is a negative integer or zero, an empty sequence is returned. @end example @end defun -@defun seq-take-while pred seq - This function returns a sub-sequence of the successive elements of -@var{seq} for which calling @code{pred} with that element returns -non-nil. - -@var{pred} must be a one-argument function and @var{seq} may be a -list, vector or string. The result is the same type of sequence as -@var{seq}. - -If evaluating @var{pred} with the first element of @var{seq} as argument -returns @code{nil}, an empty sequence is returned. +@defun seq-take-while predicate sequence + This function returns the members of @var{sequence} in order, +stopping before the first one for which @var{predicate} returns @code{nil}. @example @group @@ -495,17 +481,9 @@ returns @code{nil}, an empty sequence is returned. @end example @end defun -@defun seq-drop-while pred seq - This function returns a sub-sequence of @var{seq} from the first -element for which calling @var{pred} with that element returns -@code{nil}. - -@var{pred} must be a one-argument function and @var{seq} may be a -list, vector or string. The result is the same type of sequence as -@var{seq}. - -If evaluating @var{pred} with every element of @var{seq} returns -@code{nil}, @var{seq} is returned. +@defun seq-drop-while predicate sequence + This function returns the members of @var{sequence} in order, +starting from the first one for which @var{predicate} returns @code{nil}. @example @group @@ -519,13 +497,10 @@ If evaluating @var{pred} with every element of @var{seq} returns @end example @end defun -@defun seq-filter pred seq +@defun seq-filter predicate sequence @cindex filtering sequences - This function returns a list of all the elements in @var{seq} for -which calling @var{pred} with that element returns non-nil. - -@var{pred} must be a one-argument function and @var{seq} may be a -list, vector or string. + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns non-@code{nil}. @example @group @@ -539,13 +514,10 @@ list, vector or string. @end example @end defun -@defun seq-remove pred seq +@defun seq-remove predicate sequence @cindex removing from sequences - This function returns a list of all the elements in @var{seq} for -which calling @var{pred} with that element returns @code{nil}. - -@var{pred} must be a one-argument function and @var{seq} may be a -list, vector or string. + This function returns a list of all the elements in @var{sequence} +for which @var{predicate} returns @code{nil}. @example @group @@ -559,18 +531,15 @@ list, vector or string. @end example @end defun -@defun seq-reduce function seq initial-value +@defun seq-reduce function sequence initial-value @cindex reducing sequences This function returns the result of calling @var{function} with -@var{initial-value} and the first element of @var{seq}, then calling -@var{function} with that result and the second element of @var{seq}, -then with that result and the third element of @var{seq}, etc. - -@var{function} must be a two-arguments function and @var{seq} may be a -list, vector or string. - -If @var{seq} is empty, @var{initial-value} is returned and -@var{function} is not called. +@var{initial-value} and the first element of @var{sequence}, then calling +@var{function} with that result and the second element of @var{sequence}, +then with that result and the third element of @var{sequence}, etc. +@var{function} should be a function of two arguments. If +@var{sequence} is empty, this returns @var{initial-value} without +calling @var{function}. @example @group @@ -588,14 +557,9 @@ If @var{seq} is empty, @var{initial-value} is returned and @end example @end defun -@defun seq-some-p pred seq - This function returns any element in @var{seq} for which calling -@var{pred} with that element returns non-nil. If successively calling -@var{pred} with each element of @var{seq} always returns @code{nil}, -@code{nil} is returned. - -@var{pred} must be a one-argument function and @var{seq} may be a -list, vector or string. +@defun seq-some-p predicate sequence + This function returns the first member of sequence for which @var{predicate} +returns non-@code{nil}. @example @group @@ -609,12 +573,9 @@ list, vector or string. @end example @end defun -@defun seq-every-p pred seq - This function returns non-nil if successively calling @var{pred} with -each element of @var{seq} always returns non-nil, @code{nil} otherwise. - -@var{pred} must be a one-argument function and @var{seq} may be a -list, vector or string. +@defun seq-every-p predicate sequence + This function returns non-@code{nil} if applying @var{predicate} +to every element of @var{sequence} returns non-@code{nil}. @example @group @@ -628,11 +589,8 @@ list, vector or string. @end example @end defun -@defun seq-empty-p seq - This function returns non-nil if the sequence @var{seq} is empty, -@code{nil} otherwise. - -@var{seq} may be a list, vector or string. +@defun seq-empty-p sequence + This function returns non-@code{nil} if @var{sequence} is empty. @example @group @@ -646,12 +604,9 @@ list, vector or string. @end example @end defun -@defun seq-count pred seq - This function returns the number of elements in @var{seq} for which -calling @var{pred} with that element returns non-nil. - -@var{pred} must be a one-argument function and @var{seq} may be a -list, vector or string. +@defun seq-count predicate sequence + This function returns the number of elements in @var{sequence} for which +@var{predicate} returns non-@code{nil}. @example (seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2]) @@ -659,27 +614,17 @@ list, vector or string. @end example @end defun -@defun seq-sort pred seq - This function returns a sorted sequence of the elements of -@var{seq}, comparing its elements with @var{pred}. Called with two -elements of @var{seq}, @var{pred} should return non-nil if the first -element should sort before the second. - -@var{pred} must be a two-arguments function, @var{seq} may be a list, -vector or string. - -The result is a sequence of the same type as SEQ. @cindex sorting sequences +@defun seq-sort function sequence + This function returns a copy of @var{sequence} that is sorted +according to @var{function}, a function of two arguments that returns +non-@code{nil} if the first argument should sort before the second. @end defun -@defun seq-contains-p seq elt testfn - This function returns the first element in @var{seq} that equals to -@var{elt}. - -Equality is defined by @var{testfn} if non-nil or by @code{equal} if -@code{nil}. - -@var{seq} may be a list, vector or string. +@defun seq-contains-p sequence elt &optional function + This function returns the first element in @var{sequence} that is equal to +@var{elt}. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. @example @group @@ -694,13 +639,10 @@ Equality is defined by @var{testfn} if non-nil or by @code{equal} if @end defun -@defun seq-uniq seq testfn - This function returns a list of the elements of @var{seq} with -duplicates removed. @var{testfn} is used to compare elements, or -@code{equal} if @var{testfn} is @code{nil}. - -@var{testfn} must be a two-argument function or @code{nil} and -@var{seq} may be a list, vector or string. +@defun seq-uniq sequence &optional function + This function returns a list of the elements of @var{sequence} with +duplicates removed. If the optional argument @var{function} is non-@code{nil}, +it is a function of two arguments to use instead of the default @code{equal}. @example @group @@ -714,14 +656,11 @@ duplicates removed. @var{testfn} is used to compare elements, or @end example @end defun -@defun seq-subseq seq start &optional end - This function returns a sub-sequence of @var{seq} from @var{start} -to @var{end}. If @var{end} is omitted, it default to the length of -@var{seq}. If @var{start} or @var{end} is negative, it counts from -the end of @var{seq}. - -@var{seq} may be a list, vector or string. -The result is the same type of sequence as @var{seq}. +@defun seq-subseq sequence start &optional end + This function returns a subset of @var{sequence} from @var{start} +to @var{end}, both integers (@var{end} defaults to the last element). +If @var{start} or @var{end} is negative, it counts from the end of +@var{sequence}. @example @group @@ -739,11 +678,10 @@ The result is the same type of sequence as @var{seq}. @end example @end defun -@defun seq-concatenate type &rest seqs - This function returns a sequence made of the concatenation of -@var{seqs}. The result is a sequence of type @var{type}. @var{type} -may be one of the following symbols: @code{vector}, @code{list} or -@code{string}. +@defun seq-concatenate type &rest sequences + This function returns a sequence of type @var{type} made of the +concatenation of @var{sequences}. @var{type} may be: @code{vector}, +@code{list} or @code{string}. @example @group @@ -757,26 +695,11 @@ may be one of the following symbols: @code{vector}, @code{list} or @end example @end defun -@defmac seq-doseq (var seq [result]) body@dots{} +@defmac seq-doseq (var sequence [result]) body@dots{} @cindex sequence iteration -This macro is like @code{dolist}, except that @var{seq} can be a list, +This macro is like @code{dolist}, except that @var{sequence} can be a list, vector or string (@pxref{Iteration} for more information about the -@code{dolist} macro). - -@var{seq-doseq} is primarily useful for side-effects. - -@example -(seq-doseq (elt [1 2 3]) - (print (* 2 elt))) - @print{} - @print{} 2 - @print{} - @print{} 4 - @print{} - @print{} 6 - @result{} nil - -@end example +@code{dolist} macro). This is primarily useful for side-effects. @end defmac @node Arrays