[Emacs-diffs] master f6e1f15: Add documentation for seq.el

[Nicolas Petton]

branch: master
commit f6e1f158f0517cd2520eae2c54065adfd42a8925
Author: Nicolas Petton <address@hidden>
Commit: Nicolas Petton <address@hidden>

    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.
---
 doc/lispref/sequences.texi |   75 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 75 insertions(+), 0 deletions(-)

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 2dc494a..0a6f4c6 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
address@hidden 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
address@hidden 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}.
+
address@hidden seq-elt sequence index
+  This function the element at the index @var{index} in
address@hidden  @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}.
address@hidden of elt}.
+
address@hidden
address@hidden
+(seq-elt [1 2 3 4] 2)
address@hidden 3
address@hidden group
+
+  @code{seq-elt} returns settable places using @code{setf}.
+
address@hidden
+(setq vec [1 2 3 4])
+(setf (seq-elt vec 2) 5)
+vec
address@hidden [1 2 5 4]
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden 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}.
address@hidden of length}.
address@hidden defun
+
address@hidden seq-p sequence
+  This function returns address@hidden if @var{sequence} is a sequence
+(a list or array), or any additional type of sequence defined via
address@hidden generic functions.
+
address@hidden
address@hidden
+(seq-p [1 2])
address@hidden t
address@hidden group
address@hidden
+(seq-p 2)
address@hidden nil
address@hidden group
address@hidden example
address@hidden 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
 
address@hidden seq-do function sequence
+  This function applies @var{function} to each element of
address@hidden in turn (presumably for side effects) and returns
address@hidden
address@hidden defun
+
address@hidden 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.
+
address@hidden
address@hidden
+(seq-map #'1+ '(2 4 6))
address@hidden (3 5 7)
address@hidden group
address@hidden
+(seq-map #'symbol-name [foo bar])
address@hidden ("foo" "bar")
address@hidden group
address@hidden example
address@hidden defun
+
 @defun seq-filter predicate sequence
 @cindex filtering sequences
   This function returns a list of all the elements in @var{sequence}