@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Sequences Arrays Vectors
@cindex vector length
@cindex sequence length
@cindex char-table length
+@anchor{Definition of length}
This function returns the number of elements in @var{sequence}. If
@var{sequence} is a dotted list, a @code{wrong-type-argument} error is
signaled. Circular lists may cause an infinite loop. For a
account for the display width of each character.
@defun elt sequence index
+@anchor{Definition of elt}
@cindex elements of sequences
This function returns the element of @var{sequence} indexed by
@var{index}. Legitimate values of @var{index} are integers ranging
The argument @var{predicate} must be a function that accepts two
arguments. It is called with two elements of @var{sequence}. To get an
increasing order sort, the @var{predicate} should return non-@code{nil} if the
-first element is ``less than'' the second, or @code{nil} if not.
+first element is ``less'' than the second, or @code{nil} if not.
The comparison function @var{predicate} must give reliable results for
any given pair of arguments, at least within a single call to
sequence of the same type as the input. For those functions that take
a predicate, this should be a function of one argument.
+ The @file{seq.el} library can be extended to work with additional
+types of sequential data-structures. For that purpose, all functions
+are defined using @code{cl-defgeneric}. @xref{Generic Functions}, for
+more details about using @code{cl-defgeneric} for adding extensions.
+
+@defun seq-elt sequence index
+ This function returns the element of @var{sequence} at the specified
+@var{index}, which is an integer whose valid value range is zero to
+one less than the length of @var{sequence}. For out-of-range values
+on built-in sequence types, @code{seq-elt} behaves like @code{elt}.
+For the details, see @ref{Definition of elt}.
+
+@example
+@group
+(seq-elt [1 2 3 4] 2)
+@result{} 3
+@end group
+@end example
+
+ @code{seq-elt} returns places settable using @code{setf}
+(@pxref{Setting Generalized Variables}).
+
+@example
+@group
+(setq vec [1 2 3 4])
+(setf (seq-elt vec 2) 5)
+vec
+@result{} [1 2 5 4]
+@end group
+@end example
+@end defun
+
+@defun seq-length sequence
+ This function returns the number of elements in @var{sequence}. For
+built-in sequence types, @code{seq-length} behaves like @code{length}.
+@xref{Definition of length}.
+@end defun
+
+@defun seqp sequence
+ This function returns non-@code{nil} if @var{sequence} is a sequence
+(a list or array), or any additional type of sequence defined via
+@file{seq.el} generic functions.
+
+@example
+@group
+(seqp [1 2])
+@result{} t
+@end group
+@group
+(seqp 2)
+@result{} nil
+@end group
+@end example
+@end defun
+
@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,
@end example
@end defun
+@defun seq-do function sequence
+ This function applies @var{function} to each element of
+@var{sequence} in turn (presumably for side effects), and returns
+@var{sequence}.
+@end defun
+
+@defun seq-map function sequence
+ This function returns the result of applying @var{function} to each
+element of @var{sequence}. The returned value is a list.
+
+@example
+@group
+(seq-map #'1+ '(2 4 6))
+@result{} (3 5 7)
+@end group
+@group
+(seq-map #'symbol-name [foo bar])
+@result{} ("foo" "bar")
+@end group
+@end example
+@end defun
+
+@defun seq-map-indexed function sequence
+ This function returns the result of applying @var{function} to each
+element of @var{sequence} and its index within @var{seq}. The
+returned value is a list.
+
+@example
+@group
+(seq-map-indexed (lambda (elt idx)
+ (list idx elt))
+ '(a b c))
+@result{} ((0 a) (b 1) (c 2))
+@end group
+@end example
+@end defun
+
+@defun seq-mapn function &rest sequences
+ This function returns the result of applying @var{function} to each
+element of @var{sequences}. The arity (@pxref{What Is a Function,
+sub-arity}) of @var{function} must match the number of sequences.
+Mapping stops at the end of the shortest sequence, and the returned
+value is a list.
+
+@example
+@group
+(seq-mapn #'+ '(2 4 6) '(20 40 60))
+@result{} (22 44 66)
+@end group
+@group
+(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"])
+@result{} ("moskitobee" "bitesting")
+@end group
+@end example
+@end defun
+
@defun seq-filter predicate sequence
@cindex filtering sequences
This function returns a list of all the elements in @var{sequence}
@end defun
@defun seq-some predicate sequence
- This function returns non-@code{nil} if @var{predicate} returns
-non-@code{nil} for any element of @var{sequence}. If so, the returned
-value is the value returned by @var{predicate}.
+ This function returns the first non-@code{nil} value returned by
+applying @var{predicate} to each element of @var{sequence} in turn.
@example
@group
(seq-some #'null ["abc" 1 nil])
@result{} t
@end group
+@group
+(seq-some #'1+ [2 4 6])
+@result{} 3
+@end group
@end example
@end defun
-@defun seq-find predicate sequence &optional sentinel
- This function returns the first element for which @var{predicate}
-returns non-@code{nil} in @var{sequence}. If no element matches
-@var{predicate}, @var{sentinel} is returned if non-@code{nil},
-@code{nil} otherwise.
+@defun seq-find predicate sequence &optional default
+ This function returns the first element in @var{sequence} for which
+@var{predicate} returns non-@code{nil}. If no element matches
+@var{predicate}, the function returns @var{default}.
Note that this function has an ambiguity if the found element is
-@code{nil}, and if no @var{sentinel} is specified, as it cannot be
-known if an element was found or not.
+identical to @var{default}, as in that case it cannot be known whether
+an element was found or not.
@example
@group
non-@code{nil} if the first argument should sort before the second.
@end defun
+@defun seq-sort-by function predicate sequence
+ This function is similar to @code{seq-sort}, but the elements of
+@var{sequence} are transformed by applying @var{function} on them
+before being sorted. @var{function} is a function of one argument.
+
+@example
+(seq-sort-by #'seq-length #'> ["a" "ab" "abc"])
+@result{} ["abc" "ab" "a"]
+@end example
+@end defun
+
+
@defun seq-contains 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},
@end defun
+@defun seq-position sequence elt &optional function
+ This function returns the index of 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
+(seq-position '(a b c) 'b)
+@result{} 1
+@end group
+@group
+(seq-position '(a b c) 'd)
+@result{} nil
+@end group
+@end example
+@end defun
+
+
@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},
This function returns a list of the elements of @var{sequence}
grouped into sub-sequences of length @var{n}. The last sequence may
contain less elements than @var{n}. @var{n} must be an integer. If
-@var{n} is a negative integer or 0, nil is returned.
+@var{n} is a negative integer or 0, the return value is @code{nil}.
@example
@group
@end defun
@defun seq-min sequence
- This function returns the smallest element of
-@var{sequence}. @var{sequence} must be a sequence of numbers or
-markers.
+ This function returns the smallest element of @var{sequence}. The
+elements of @var{sequence} must be numbers or markers
+(@pxref{Markers}).
@example
@group
@end defun
@defun seq-max sequence
- This function returns the largest element of
-@var{sequence}. @var{sequence} must be a sequence of numbers or
-markers.
+ This function returns the largest element of @var{sequence}. The
+elements of @var{sequence} must be numbers or markers.
@example
@group
@defmac seq-doseq (var sequence) body@dots{}
@cindex sequence iteration
- 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). This is primarily useful for side-effects.
+ This macro is like @code{dolist} (@pxref{Iteration, dolist}), except
+that @var{sequence} can be a list, vector or string. This is
+primarily useful for side-effects.
@end defmac
@defmac seq-let arguments sequence body@dots{}
@cindex sequence destructuring
This macro binds the variables defined in @var{arguments} to the
-elements of the sequence @var{sequence}. @var{arguments} can itself
-include sequences allowing for nested destructuring.
+elements of @var{sequence}. @var{arguments} can themselves include
+sequences, allowing for nested destructuring.
The @var{arguments} sequence can also include the @code{&rest} marker
followed by a variable name to be bound to the rest of
@end defun
@defun char-table-extra-slot char-table n
-This function returns the contents of extra slot @var{n} of
-@var{char-table}. The number of extra slots in a char-table is
+This function returns the contents of extra slot @var{n} (zero based)
+of @var{char-table}. The number of extra slots in a char-table is
determined by its subtype.
@end defun
@defun set-char-table-extra-slot char-table n value
-This function stores @var{value} in extra slot @var{n} of
+This function stores @var{value} in extra slot @var{n} (zero based) of
@var{char-table}.
@end defun
efficient ring data structure is implemented by the @code{ring}
package. It provides the functions listed in this section.
- Note that several ``rings'' in Emacs, like the kill ring and the
+ Note that several rings in Emacs, like the kill ring and the
mark ring, are actually implemented as simple lists, @emph{not} using
the @code{ring} package; thus the following functions won't work on
them.