procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add documentation for seq.el

Browse source 
* 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.
This commit is contained in:
Nicolas Petton 2015-09-28 22:18:26 +02:00
parent f0b71429b9
commit f6e1f158f0
1 changed files with 75 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

75
doc/lispref/sequences.texi
View file

@ -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}