cl: Sequence Functions
9.3 Sequence Functions
======================
This section describes a number of Common Lisp functions for operating
on sequences.
-- Function: cl-subseq sequence start &optional end
This function returns a given subsequence of the argument SEQUENCE,
which may be a list, string, or vector. The indices START and END
must be in range, and START must be no greater than END. If END is
omitted, it defaults to the length of the sequence. The return
value is always a copy; it does not share structure with SEQUENCE.
As an extension to Common Lisp, START and/or END may be negative,
in which case they represent a distance back from the end of the
sequence. This is for compatibility with Emacs’s ‘substring’
function. Note that ‘cl-subseq’ is the _only_ sequence function
that allows negative START and END.
You can use ‘setf’ on a ‘cl-subseq’ form to replace a specified
range of elements with elements from another sequence. The
replacement is done as if by ‘cl-replace’, described below.
-- Function: cl-concatenate result-type &rest seqs
This function concatenates the argument sequences together to form
a result sequence of type RESULT-TYPE, one of the symbols ‘vector’,
‘string’, or ‘list’. The arguments are always copied, even in
cases such as ‘(cl-concatenate 'list '(1 2 3))’ where the result is
identical to an argument.
-- Function: cl-fill seq item &key :start :end
This function fills the elements of the sequence (or the specified
part of the sequence) with the value ITEM.
-- Function: cl-replace seq1 seq2 &key :start1 :end1 :start2 :end2
This function copies part of SEQ2 into part of SEQ1. The sequence
SEQ1 is not stretched or resized; the amount of data copied is
simply the shorter of the source and destination (sub)sequences.
The function returns SEQ1.
If SEQ1 and SEQ2 are ‘eq’, then the replacement will work correctly
even if the regions indicated by the start and end arguments
overlap. However, if SEQ1 and SEQ2 are lists that share storage
but are not ‘eq’, and the start and end arguments specify
overlapping regions, the effect is undefined.
-- Function: cl-remove item seq &key :test :test-not :key :count :start
:end :from-end
This returns a copy of SEQ with all elements matching ITEM removed.
The result may share storage with or be ‘eq’ to SEQ in some
circumstances, but the original SEQ will not be modified. The
‘:test’, ‘:test-not’, and ‘:key’ arguments define the matching test
that is used; by default, elements ‘eql’ to ITEM are removed. The
‘:count’ argument specifies the maximum number of matching elements
that can be removed (only the leftmost COUNT matches are removed).
The ‘:start’ and ‘:end’ arguments specify a region in SEQ in which
elements will be removed; elements outside that region are not
matched or removed. The ‘:from-end’ argument, if true, says that
elements should be deleted from the end of the sequence rather than
the beginning (this matters only if COUNT was also specified).
-- Function: cl-delete item seq &key :test :test-not :key :count :start
:end :from-end
This deletes all elements of SEQ that match ITEM. It is a
destructive operation. Since Emacs Lisp does not support
stretchable strings or vectors, this is the same as ‘cl-remove’ for
those sequence types. On lists, ‘cl-remove’ will copy the list if
necessary to preserve the original list, whereas ‘cl-delete’ will
splice out parts of the argument list. Compare ‘append’ and
‘nconc’, which are analogous non-destructive and destructive list
operations in Emacs Lisp.
The predicate-oriented functions ‘cl-remove-if’, ‘cl-remove-if-not’,
‘cl-delete-if’, and ‘cl-delete-if-not’ are defined similarly.
-- Function: cl-remove-duplicates seq &key :test :test-not :key :start
:end :from-end
This function returns a copy of SEQ with duplicate elements
removed. Specifically, if two elements from the sequence match
according to the ‘:test’, ‘:test-not’, and ‘:key’ arguments, only
the rightmost one is retained. If ‘:from-end’ is true, the
leftmost one is retained instead. If ‘:start’ or ‘:end’ is
specified, only elements within that subsequence are examined or
removed.
-- Function: cl-delete-duplicates seq &key :test :test-not :key :start
:end :from-end
This function deletes duplicate elements from SEQ. It is a
destructive version of ‘cl-remove-duplicates’.
-- Function: cl-substitute new old seq &key :test :test-not :key :count
:start :end :from-end
This function returns a copy of SEQ, with all elements matching OLD
replaced with NEW. The ‘:count’, ‘:start’, ‘:end’, and ‘:from-end’
arguments may be used to limit the number of substitutions made.
-- Function: cl-nsubstitute new old seq &key :test :test-not :key
:count :start :end :from-end
This is a destructive version of ‘cl-substitute’; it performs the
substitution using ‘setcar’ or ‘aset’ rather than by returning a
changed copy of the sequence.
The functions ‘cl-substitute-if’, ‘cl-substitute-if-not’,
‘cl-nsubstitute-if’, and ‘cl-nsubstitute-if-not’ are defined similarly.
For these, a PREDICATE is given in place of the OLD argument.
Info Catalog
cl: Mapping over Sequences
cl: Sequences
cl: Searching Sequences