@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
@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:
@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
@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
@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
@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
@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
@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
@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
@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
@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
@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
@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])
@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
@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
@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
@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
@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
projects / emacs.git / commitdiff