From: Nicolas Petton <nicolas@petton.fr>
Date: Mon, 28 Sep 2015 20:18:26 +0000 (+0200)
Subject: Add documentation for seq.el
X-Git-Tag: emacs-25.0.90~1223^2~78
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=f6e1f158f0517cd2520eae2c54065adfd42a8925;p=emacs.git

Add documentation for seq.el

* doc/lispref/sequences.texi: Add documentation regarding extending
seq.el, as well as missing documentation for seq-elt, seq-length, seq-p,
seq-do and seq-map.
---

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 2dc494aec5d..0a6f4c6623c 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -72,6 +72,7 @@ string, bool-vector, or char-table, @code{nil} otherwise.
 @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
@@ -113,6 +114,7 @@ since @code{length} only counts the number of characters, but does not
 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
@@ -431,6 +433,57 @@ 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.
 
+  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}.
+
+@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}.
+
+@example
+@group
+(seq-elt [1 2 3 4] 2)
+@result{} 3
+@end group
+
+  @code{seq-elt} returns settable places using @code{setf}.
+
+@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 seq-p 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
+(seq-p [1 2])
+@result{} t
+@end group
+@group
+(seq-p 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,
@@ -497,6 +550,28 @@ starting from the first one for which @var{predicate} returns @code{nil}.
 @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-filter predicate sequence
 @cindex filtering sequences
   This function returns a list of all the elements in @var{sequence}