* lisp/emacs-lisp/seq.el: New file.

* doc/lispref/sequences.texi (Seq Library): Add documentation for seq.el.
* test/automated/seq-tests.el: New file.

1 files changed, 360 insertions, 0 deletions

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index d3a6792c1ba..8f8cfe72fa3 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -419,6 +419,366 @@ See @code{documentation} in @ref{Accessing Documentation}, for a
 useful example of @code{sort}.
 @end defun
 
+@cindex sequence functions in seq
+@cindex seq library
+  The @file{seq} 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.
+
+  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.
+
+@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.
+
+@example
+@group
+(seq-drop [1 2 3 4 5 6] 3)
+@result{} [4 5 6]
+@end group
+@group
+(seq-drop "hello world" -4)
+@result{} "hello world"
+@end 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.
+
+@example
+@group
+(seq-take '(1 2 3 4) 3)
+@result{} (1 2 3)
+@end group
+@group
+(seq-take [1 2 3 4] 0)
+@result{} []
+@end 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.
+
+@example
+@group
+(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
+@result{} (1 2 3)
+@end group
+@group
+(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6])
+@result{} []
+@end 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.
+
+@example
+@group
+(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
+@result{} (-1 -2)
+@end group
+@group
+(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6])
+@result{} [1 4 6]
+@end group
+@end example
+@end defun
+
+@defun seq-filter pred seq
+@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.
+
+@example
+@group
+(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
+@result{} (1 3 5)
+@end group
+@group
+(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5))
+@result{} nil
+@end group
+@end example
+@end defun
+
+@defun seq-remove pred seq
+@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.
+
+@example
+@group
+(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
+@result{} (-1 -3)
+@end group
+@group
+(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5))
+@result{} nil
+@end group
+@end example
+@end defun
+
+@defun seq-reduce function seq 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.
+
+@example
+@group
+(seq-reduce #'+ [1 2 3 4] 0)
+@result{} 10
+@end group
+@group
+(seq-reduce #'+ '(1 2 3 4) 5)
+@result{} 15
+@end group
+@group
+(seq-reduce #'+ '() 3)
+@result{} 3
+@end 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.
+
+@example
+@group
+(seq-some-p #'numberp ["abc" 1 nil])
+@result{} 1
+@end group
+@group
+(seq-some-p #'numberp ["abc" "def"])
+@result{} nil
+@end 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.
+
+@example
+@group
+(seq-every-p #'numberp [2 4 6])
+@result{} t
+@end group
+@group
+(seq-some-p #'numberp [2 4 "6"])
+@result{} nil
+@end 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.
+
+@example
+@group
+(seq-empty-p "not empty")
+@result{} nil
+@end group
+@group
+(seq-empty-p "")
+@result{} t
+@end 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.
+
+@example
+(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2])
+@result{} 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
+@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.
+
+@example
+@group
+(seq-contains-p '(symbol1 symbol2) 'symbol1)
+@result{} symbol1
+@end group
+@group
+(seq-contains-p '(symbol1 symbol2) 'symbol3)
+@result{} nil
+@end group
+@end example
+
+@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.
+
+@example
+@group
+(seq-uniq '(1 2 2 1 3))
+@result{} (1 2 3)
+@end group
+@group
+(seq-uniq '(1 2 2.0 1.0) #'=)
+@result{} [3 4]
+@end 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}.
+
+@example
+@group
+(seq-subseq '(1 2 3 4 5) 1)
+@result{} (2 3 4 5)
+@end group
+@group
+(seq-subseq '[1 2 3 4 5] 1 3)
+@result{} [2 3]
+@end group
+@group
+(seq-subseq '[1 2 3 4 5] -3 -1)
+@result{} [3 4]
+@end 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}.
+
+@example
+@group
+(seq-concatenate 'list '(1 2) '(3 4) [5 6])
+@result{} (1 2 3 5 6)
+@end group
+@group
+(seq-concatenate 'string "Hello " "world")
+@result{} "Hello world"
+@end group
+@end example
+@end defun
+
+@defmac seq-doseq (var seq [result]) body@dots{}
+@cindex sequence iteration
+This macro is like @code{dolist}, except that @var{seq} 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
+@end defmac
+
 @node Arrays
 @section Arrays
 @cindex array