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}.
+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 the element at the index @var{index} in
-@var{sequence}. @var{index} can be an integer from zero up to the
-length of @var{sequence} minus one. For out-of-range values on
-built-in sequence types, @code{seq-elt} behaves like @code{elt}.
-@xref{Definition of elt}.
+ 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 settable places using @code{setf}.
+ @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)
@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} in turn (presumably for side effects), and returns
@var{sequence}.
@end defun
@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 of @var{function} must match
-the number of sequences. Mapping stops at the shortest sequence, and
-the returned value is a list.
+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
@end defun
@defun seq-find predicate sequence &optional default
- This function returns the first element for which @var{predicate}
-returns non-@code{nil} in @var{sequence}. If no element matches
-@var{predicate}, @var{default} is returned.
+ 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
-identical to @var{default}, 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},
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