REF SEQUENCES                             Titch Le Bek, Rob Duncan, 1986

       COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<        PREDICATES ON        >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<        LISP SEQUENCES       >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file  briefly  describes  the functions,  variables  and  constants
documented in Chapter 14  of the standard Common  Lisp guide, which  is:
Common Lisp: The Language (Guy L. Steele, Digital Press, 1984).


-------------------------------------------------
1  A Listing of Functions Variables and Constants
-------------------------------------------------

(complement function)                                         [function]
        Creates and  returns  the complement  of  function, i.e.  a  new
        function which calls function and  then inverts its truth  value
        by calling not. The new function is equivalent to:

            (lambda (&rest args) (not (apply function args)))


(concatenate type &rest sequences)                            [function]
        Returns a  new  sequence of  type  type that  contains  all  the
        elements of sequences in order.


(copy-seq sequence)                                           [function]
        Copies sequence; the result is equalp to sequence but not eq  to
        it.


(count item sequence                                          [function]
            &key :from-end :test :test-not :start :end :key)
        Returns the number of elements  in the specified subsequence  of
        sequence that are `equal' to item (according to :test).


(count-if test sequence                                       [function]
            &key :from-end :start :end :key)
        Returns the number of elements  in the specified subsequence  of
        sequence satisfying the test.


(count-if-not test sequence                                   [function]
            &key :from-end :start :end :key)
        Returns the number of elements  in the specified subsequence  of
        sequence not satisfying the test.


(delete item sequence                                         [function]
            &key :from-end :test :test-not :start :end :count :key)
        The destructive counterpart to remove. Returns a sequence of the
        same kind as  sequence that  has the same  elements except  that
        those in  the  subsequence  delimited by  :start  and  :end  and
        satisfying :test have been deleted.


(delete-duplicates sequence                                   [function]
            &key :from-end :test :test-not :start :end :key)
        Returns a  sequence of  the same  kind as  sequence with  enough
        elements removed so that no two of the remaining elements match.
        The order of  elements is  maintained. This  is the  destructive
        version of remove-duplicates.


(delete-if test sequence                                      [function]
            &key :from-end :start :end :count :key)
        Destructive counterpart to remove-if. Returns a sequence of  the
        same kind as  sequence that  has the same  elements except  that
        those in  the  subsequence  delimited by  :start  and  :end  and
        satisfying the test have been deleted.


(delete-if-not test sequence                                  [function]
            &key :from-end :start :end :count :key)
        Destructive counterpart to remove-if-not. Returns a sequence  of
        the same type as sequence that has the same elements except that
        those in  the  subsequence  delimited by  :start  and  :end  and
        satisfying the test have been deleted.


(elt sequence index)                                          [function]
        Returns the element of sequence specified by index.


(every predicate sequence &rest sequences)                    [function]
        True if predicate is true of every item in sequence.


(fill sequence item &key :start :end)                         [function]
        Inserts item  into  each element  of  the specified  portion  of
        sequence. Returns sequence.


(find item sequence                                           [function]
            &key :from-end :test :test-not :start :end :key)
        If sequence contains an element  satisfying the :test, then  the
        leftmost such element is returned. nil otherwise.


(find-if test sequence                                        [function]
            &key :from-end :start :end :key)
        If sequence contains  an element satisfying  the test, then  the
        leftmost such element is returned. nil otherwise.


(find-if-not test sequence                                    [function]
            &key :from-end :start :end :key)
        If sequence contains  an element not  satisfying the test,  then
        the leftmost such element is returned. nil otherwise.


(length sequence)                                             [function]
        Returns the length of sequence as an integer.


(make-sequence type number &key :initial-element)             [function]
        Returns a sequence of  type type and of  length number, each  of
        whose elements has been initialized to :initial-element.


(map type function sequence &rest sequences)                  [function]
        Returns a sequence whose j'th element is the result of  applying
        function to the j'th element of each of the argument  sequences.
        The result sequence  is as  long as  the shortest  of the  input
        sequences. The type of the result is specified by type. If  type
        is nil then function is invoked only for effect, and map returns
        nil.


(map-into result-sequence function &rest sequences)           [function]
        This function  destructively  modifies  the  result-sequence  to
        contain  the  results  of  applying  function  to  corresponding
        elements of  the argument  sequences in  turn; it  then  returns
        result-sequence.

        The function  must accept  at  least as  many arguments  as  the
        number  of   argument  sequences   supplied  to   map-into.   If
        result-sequence and the other argument sequences are not all the
        same length, the iteration terminates when the shortest sequence
        is exhausted.


(merge type sequence1 sequence2 predicate &key :key)          [function]
        The sequences sequence1 and  sequence2 are destructively  merged
        according to an order determined  by predicate. The result  is a
        sequence of type type. predicate takes two arguments and returns
        non-nil iff the first argument is strictly less than the second.
        If the first  argument is greater  than or equal  to the  second
        then the predicate returns nil.


(mismatch sequence1 sequence2                                 [function]
            &key :from-end :test :test-not :key
                  :start1 :start2 :end :end2)
        The  subsequences   sequence1   and   sequence2   are   compared
        element-wise. If they  are of  equal length and  match in  every
        element,  the  result   is  nil.  Otherwise   the  result   is a
        non-negative integer which is the index within sequence1 of  the
        leftmost position at which the  two subsequences fail to  match,
        or if one subsequence is shorter  than and a matching prefix  of
        the other, the result is the index relative to sequence1  beyond
        the last position tested.


(notany predicate sequence &rest sequences)                   [function]
        Returns a non-nil value if  no invocation of predicate is  true.
        nil otherwise.


(notevery predicate sequence &rest sequences)                 [function]
        Returns a non-nil value if not every invocation of predicate  is
        true. nil otherwise.


(nreverse sequence)                                           [function]
        Returns a sequence containing the same elements as sequence  but
        in reverse  order.  sequence may  be  destroyed and  re-used  to
        produce the result.


(nsubstitute new old sequence                                 [function]
            &key :from-end :test :test-not :start :end :count :key)
        Returns sequence with all top level elements which satisfy the
        :test replaced with new. The  relevant parts of sequence  are
        destructively modified.


(nsubstitute-if new test sequence                             [function]
            &key :from-end :start :end :count :key)
        Returns  sequence  with  all  top  level  elements  of  sequence
        statisfying :test  subtituted  by  new. The  relevant  parts  of
        sequence are destructively modified.


(nsubstitute-if-not new test sequence                         [function]
            &key :from-end :start :end :count :key)
        Returns sequence with all the  top level elements which fail  to
        satisfy :test substituted by new. The relevant parts of sequence
        are destructively modified.


(position item sequence                                       [function]
            &key :from-end :test :test-not :start :end :key)
        If sequence contains an element  satisfying the :test, then  the
        index within  the  sequence  of the  leftmost  such  element  is
        returned as a non-negative  integer, otherwise nil is  returned.
        If :start and :end are given then only the specified subsequence
        is searched.  However  the index  returned  is relative  to  the
        entire sequence. If  a non-nil :from-end  argument is  specified
        then the result is the index of the rightmost element satisfying
        the :test.


(position-if test sequence                                    [function]
            &key :from-end :start :end :key)
        If sequence contains an element satisfying test, then the  index
        within sequence of  the leftmost such  element is returned  as a
        non-negative integer, otherwise nil  is returned. If :start  and
        :end are given then only the specified subsequence is  searched.
        However the index returned is  relative to the entire  sequence.
        If a non-nil :from-end argument is specified then the result  is
        the index of the rightmost element satisfying the test.


(position-if-not test sequence                                [function]
            &key :from-end :start :end :key)
        If sequence contains  an element satisfying  the test, then  the
        index within  the  sequence  of the  leftmost  such  element  is
        returned as a non-negative  integer, otherwise nil is  returned.
        If :start and :end are given then only the specified subsequence
        is searched.  However  the index  returned  is relative  to  the
        entire sequence. If  a non-nil :from-end  argument is  specified
        then the result is the index of the rightmost element satisfying
        the test.


(reduce function sequence                                     [function]
            &key :from-end :start :end :initial-value :key)
        Combines all the elements sequence using a binary operation  (eg
        + ). The  specified subsequence of  sequence is "reduced"  using
        function which must accept two arguments. The reduction is  left
        associative unless the :from-end  is true, in  which case it  is
        right associative. If :initial-value  is given, it is  logically
        placed before  the subsequence  and  included in  the  reduction
        operation. If  the specified  subsequence contains  exactly  one
        element and no  :initial-value is  given, then  that element  is
        returned and  function is  not called.  If it  is empty  and  an
        :initial-value  is  given,  then  that  value  is  returned  and
        function is not called. If it is empty and no :initial-value  is
        given then  the  function is  called  with zero  arguments,  and
        reduce returns whatever function does.


(remove item sequence &key                                    [function]
            :from-end :test :test-not :start :end :count :key)
        Returns the same kind of sequence as sequence that has the  same
        elements except  that  those  in the  subsequence  delimited  by
        :start and :end and satisfying the :test have been removed.


(remove-duplicates sequence                                   [function]
            &key :from-end :test :test-not :start :end :key)
        remove-duplicates does a pairwise comparison of the elements  in
        sequence to  produce a  sequence of  the same  kind with  enough
        elements removed so that no two of the remaining elements match.


(remove-if test sequence                                      [function]
            &key :from-end :start :end :count :key)
        Returns the same kind of sequence as sequence that has the  same
        elements except  that  those  in the  subsequence  delimited  by
        :start and :end and satisfying the test have been removed.


(remove-if-not test sequence                                  [function]
            &key :from-end :start :end :count :key)
        Returns the same kind of sequence as sequence that has the  same
        elements except  that  those  in the  subsequence  delimited  by
        :start and :end and not satisfying the test have been removed.


(replace sequence1 sequence2                                  [function]
            &key :start1 :end1 :start2 :end2)
        sequence1  is  destructively  modified  by  copying   successive
        elements into it from sequence2. The elements of sequence2  must
        be of a type that may be stored into sequence1. The  subsequence
        of sequence2 specified by :start2  and :end2 is copied into  the
        subsequence of  sequence1 specified  by :start1  and :end1.  The
        value of the modified sequence1 is returned.


(reverse sequence)                                            [function]
        Returns a copy of sequence with the elements in reverse order.


(search sequence1 sequence2                                   [function]
            &key :from-end :test :test-not :key
              :start1 :start2 :end1 :end2)
        Returns nil or the index within  the range :start2 and :end2  in
        sequence2 of  the leftmost  element which  matches sequence1  as
        delimited by :start1 and :end1 and which satisfies :test.


(some predicate sequence &rest sequences)                     [function]
        Returns a non-nil value if some invocation of predicate is true.
        nil otherwise.


(sort sequence predicate &key :key)                           [function]
        Destructively sorts sequence to an order according to  predicate
        which should  determine  a strictly-less-than  ordering  on  the
        elements of sequence.


(stable-sort sequence predicate &key :key)                    [function]
        Destructively sorts sequence to an order according to  predicate
        which should  determine  a strictly-less-than  ordering  on  the
        elements of sequence.  Guarantees stability  where elements  are
        equal.


(subseq sequence start &optional end)                         [function]
        Returns the subsequence of sequence specified by start and end.


(substitute new old sequence                                  [function]
            &key :from-end :test :test-not :start :end :count :key)
        Returns sequence  with  all  top level  occurrances  of  old  in
        substituted by new as in nsubstitute.


(substitute-if new test sequence                              [function]
           &key :from-end :start :end :count :key)
        Returns  a  copy  of  sequence  with  all  top  level   elements
        satisfying  test   in  sequence   subtituted   by  new   as   in
        nsubstitute-if.


(substitute-if-not new test sequence                          [function]
            &key :from-end :start :end :count :key)
        Returns a  copy of  sequence  with all  top level  elements  not
        satisfying  test   in  sequence   subtituted   by  new   as   in
        nsubstitute-if-not.



--- C.all/lisp/ref/sequences
--- Copyright University of Sussex 1993. All rights reserved.
