GNU Info

(cl)Sequence Functions

---

Next: Searching Sequences Prev: Mapping over Sequences Up: Sequences

---

Enter node , (file) or (file)node

Sequence Functions
==================

This section describes a number of Common Lisp functions for operating
on sequences.

 - Function: 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' `substring'
     function.  Note that `subseq' is the _only_ sequence function that
     allows negative START and END.

     You can use `setf' on a `subseq' form to replace a specified range
     of elements with elements from another sequence.  The replacement
     is done as if by `replace', described below.

 - Function: 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 `(concatenate 'list '(1 2 3))' where the
     result is identical to an argument.

 - Function: 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: 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 which
     share storage but are not `eq', and the start and end arguments
     specify overlapping regions, the effect is undefined.

 - Function: 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: delete* item seq &key :test :test-not :key :count :start
          :end :from-end
     This deletes all elements of SEQ which match ITEM.  It is a
     destructive operation.  Since Emacs Lisp does not support
     stretchable strings or vectors, this is the same as `remove*' for
     those sequence types.  On lists, `remove*' will copy the list if
     necessary to preserve the original list, whereas `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 `remove-if', `remove-if-not',
`delete-if', and `delete-if-not' are defined similarly.

 - Function: 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: 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 `remove-duplicates'.

 - Function: 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: nsubstitute new old seq &key :test :test-not :key :count
          :start :end :from-end
     This is a destructive version of `substitute'; it performs the
     substitution using `setcar' or `aset' rather than by returning a
     changed copy of the sequence.

   The `substitute-if', `substitute-if-not', `nsubstitute-if', and
`nsubstitute-if-not' functions are defined similarly.  For these, a
PREDICATE is given in place of the OLD argument.