REF LISTS                                 Titch Le Bek, Rob Duncan, 1986

       COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<   LISP OPERATIONS ON LISTS  >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file  briefly  describes  the functions,  variables  and  constants
documented in Chapter 15  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
-------------------------------------------------

(acons key datum &optional alist)                             [function]
        Returns alist with (key .  datum) pair added. alist defaults  to
        nil.


(adjoin item alist)                                           [function]
        Conses item onto alist unless item is already a member of alist.


(append &rest lists)                                          [function]
        Returns the concatenation of lists.


(assoc item alist &key :test :test-not :key)                  [function]
        Returns the first pair from the association list alist whose car
        is equal to item (according to  :test and :key). If none  exists
        nil is returned.


(assoc-if predicate alist &key key)                           [function]
        Returns the first pair in  alist whose car satisfies  predicate.
        If none exists nil is returned.


(assoc-if-not predicate alist &key key)                       [function]
        Returns the  first pair  in  alist whose  car does  not  satisfy
        predicate. If none exists nil is returned.


(butlast list &optional number)                               [function]
        Creates and  returns a  list  with the  same elements  as  list,
        excepting the last number elements. number defaults to 1. ()  is
        returned if list has fewer than number elements.


(caaaar list)                                                 [function]
        Returns (car (car (car (car list))))


(caaadr list)                                                 [function]
        Returns (car (car (car (cdr list))))


(caaar list)                                                  [function]
        Returns (car (car (car list)))


(caadar list)                                                 [function]
        Returns (car (car (cdr (car list))))


(caaddr list)                                                 [function]
        Returns (car (car (cdr (cdr list))))


(caadr list)                                                  [function]
        Returns (car (car (cdr list)))


(caar list)                                                   [function]
        Returns (car (car list)


(cadaar list)                                                 [function]
        Returns (car (cdr (car (car list))))


(cadadr list)                                                 [function]
        Returns (car (cdr (car (cdr list))))


(cadar list)                                                  [function]
        Returns (car (cdr (car list)))


(caddar list)                                                 [function]
        Returns (car (cdr (cdr (car list))))


(cadddr list)                                                 [function]
        Returns (car (cdr (cdr (cdr list))))


(caddr list)                                                  [function]
        Returns (car (cdr (cdr list)))


(cadr list)                                                   [function]
        Returns the second element of list, i.e. (car (cdr list))


(car list)                                                    [function]
        Returns the first element of list.


(cdaaar list)                                                 [function]
        Returns (cdr (car (car (cdr list))))


(cdaadr list)                                                 [function]
        Returns (cdr (car (car (cdr list))))


(cdaar list)                                                  [function]
        Returns (cdr (car (car list)))


(cdadar list)                                                 [function]
        Returns (cdr (car (cdr (car list))))


(cdaddr list)                                                 [function]
        Returns (cdr (car (cdr (cdr list))))


(cdadr list)                                                  [function]
        Returns (cdr (car (cdr list)))


(cdar list)                                                   [function]
        Returns (cdr (car list))


(cddaar list)                                                 [function]
        Returns (cdr (cdr (car (car list))))


(cddadr list)                                                 [function]
        Returns (cdr (cdr (car (cdr list))))


(cddar list)                                                  [function]
        Returns (cdr (cdr (car list)))


(cdddar list)                                                 [function]
        Returns (cdr (cdr (cdr (car list))))


(cddddr list)                                                 [function]
        Returns (cdr (cdr (cdr (cdr list))))


(cdddr list)                                                  [function]
        Returns (cdr (cdr (cdr list)))


(cddr list)                                                   [function]
        Returns (cdr (cdr list))


(cdr list)                                                    [function]
        Returns the tail of list.


(cons x y)                                                    [function]
        Creates a new cons (pair) whose car is x and whose cdr is y.


(copy-alist alist)                                            [function]
        Copies the  top  level list  structure  of list  replacing  each
        element of list that is a cons  by a new cons with the same  car
        and cdr.


(copy-list list)                                              [function]
        Returns a list that is  equal to list but  not eq. Only the  top
        level list structure is copied.


(copy-tree object)                                            [function]
        object may  be any  Lisp  object. If  it is  not  a cons  it  is
        returned. Otherwise the result is a  new cons of the results  of
        calling copy-tree on the car and  cdr of the arg: All conses  of
        the tree are  copied recursively stopping  only when  non-conses
        are encountered.


(eighth list)                                                 [function]
        Returns the eighth element of list.


(endp object)                                                 [function]
        Tests for the end of a list. It is false of conses, true of nil,
        and for all other arguments causes an error.


(fifth list)                                                  [function]
        Returns the fifth element of list.


(first list)                                                  [function]
        Returns the first element in list.


(fourth list)                                                 [function]
        Returns the fourth element in list.


(intersection list1 list2 &key :test :test-not :key)          [function]
        Returns a new list containing  everything that is an element  of
        list1 and  list2.  If  either list  has  duplicate  entries  the
        redundant entries may or may not appear in the result.


(last list &optional n)                                       [function]
        If n is  unsupplied or  equal to 1,  returns the  final cons  in
        list. If n  is 0,  returns the  cdr of  the last  cons in  list.
        Otherwise, returns the n'th-to-last cons in list.


(ldiff list sublist)                                          [function]
        Returns the elements of list that appear before sublist in list.


(list &rest args)                                             [function]
        Returns a list of the arguments args.


(list* arg &rest others)                                      [function]
        Returns a list containing arg  and the arguments in others.  The
        last cons is dotted.


(list-length list)                                            [function]
        Returns the length of list. Differs from length when the list is
        circular; length may  fail to return,  whereas list-length  will
        return nil.


(make-list number &key :initial-element)                      [function]
        Creates and  returns  a  list containing  number  elements  each
        initialized to :initial-element which defaults to nil.


(member item list &key :test :test-not :key)                  [function]
        list is searched  for an  element that satisfies  the :test.  If
        none is  found  nil is  returned;  otherwise the  tail  of  list
        beginning with  the first  element that  satisfied the  test  is
        returned.


(member-if predicate list &key :key)                          [function]
        list is searched for an element that satisfies the predicate. If
        none is  found  nil is  returned;  otherwise the  tail  of  list
        beginning with the first element that satisfied the predicate is
        returned.


(member-if-not predicate list &key :key)                      [function]
        list is  searched  for an  element  that fails  to  satisfy  the
        predicate. If none is found nil is returned; otherwise the  tail
        of list beginning with the first element that failed to  satisfy
        the predicate is returned.


(nbutlast list &optional n)                                   [function]
        Destructive version of butlast. Changes the cdr of the cons  n+1
        from the end of list to nil. n defaults to 1. If list has  fewer
        than n elements then  nbutlast returns (),  and the argument  is
        not modified. (list - n) last elements are returned.


(nconc &rest lists)                                           [function]
        Returns a list  with the argument  lists concatenated  together.
        The lists are changed rather than copied.


(nintersection list1 list2 &key :test :test-not :key)         [function]
        Identical to  intersection but  may destroy  list1 and  use  its
        cells to construct the resulting list.


(ninth list)                                                  [function]
        Returns the ninth element in list.


(nreconc x y)                                                 [function]
        (nreconc x y)  is exactly  the same  as (nconc  (nreverse x)  y)
        except that  it  is potentially  more  efficient. Both  x  and y
        should be lists. The argument x is destroyed.


(nset-difference list1 list2 &key :test :test-not :key)       [function]
        Returns a list of  the elements in list1  that do not appear  in
        list2. list1 may be destroyed.


(nset-exclusive-or list1 list2 &key :test :test-not :key)     [function]
        Returns a list of elements that  appear in exactly one of  list1
        and list2. Both lists may be destroyed.


(nsublis alist tree &key :test :test-not :key)                [function]
        Returns tree with substitutions from the association list  alist
        as in  sublis.  The relevant  parts  of tree  are  destructively
        modified.


(nsubst new old tree &key :test :test-not :key)               [function]
        Returns tree, substituting  new for  every sub-tree  or leaf  of
        tree which together with old  satisfies the :test. The  relevant
        parts of tree are destructively modified.


(nsubst-if new test tree &key :key)                           [function]
        Returns tree with new substituted  where test is satisfied.  The
        relevant parts of tree are destructively modified.


(nsubst-if-not new test tree &key :key)                       [function]
        Returns tree with new substituted  where test is not  satisfied.
        The relevant parts of tree are destructively modified.


(nth n list)                                                  [function]
        Returns the n'th element of list.


(nthcdr n list)                                               [function]
        Returns the n'th cdr of list.


(nunion list1 list2 &key :test :test-not :key)                [function]
        Returns a list that is the union of list1 with list2. If  either
        argument has duplicate entries within it, the redundant  entries
        may appear in the result.  nunion is the destructive version  of
        union.


(pairlis keys data &optional alist)                           [function]
        Returns an association list pairing  elements of the first  list
        keys with corresponding elements of the second list data. It  is
        an error if the two lists are  not of the same length. If  alist
        is provided then the new pairs are added to the front of it.


(pop place)                                                      [macro]
        place is a generalized variable  containing a list. pop  returns
        the car of this list , and stores the cdr of the list back  into
        place.


(push object place)                                              [macro]
        place is a  generalized variable  containing a  list. object  is
        consed onto the  front of  the list  and the  augmented list  is
        stored back into place and returned.


(pushnew object place &key :test :test-not :key)                 [macro]
        place is the name of  a generalized variable containing a  list.
        If object is not already a member of the list it is consed  onto
        the front of  the list, and  the augmented list  is stored  back
        into place  and  returned.  Otherwise the  unaugmented  list  is
        returned. The keywords are passed on to the adjoin function.


(rassoc item alist &key :test :test-not :key)                 [function]
        rassoc is the  reverse form  of assoc;  it searches  for a  pair
        whose cdr is equal to item (according to :test and :key), and if
        found, returns that pair.


(rassoc-if predicate alist &key key)                          [function]
        rassoc-if is the  reverse form  of assoc-if;  it searches  for a
        pair whose cdr  satisfies predicate and  if found, returns  that
        pair.


(rassoc-if-not predicate alist &key key)                      [function]
        rassoc-if-not is the reverse  form of assoc-if-not; it  searches
        for a pair whose  cdr does not satisfy  predicate and if  found,
        returns that pair.


(rest list)                                                   [function]
        Returns the cdr of list.


(revappend x y)                                               [function]
        Behaves exactly as (append (reverse x)  y). Both x and y  should
        be lists.


(rplaca x y)                                                  [function]
        Changes the car of x to y and returns the modified x. x must  be
        a cons, but y may be any Lisp object.


(rplacd x y)                                                  [function]
        Changes the cdr of x to y and returns the modified x. x must  be
        a cons, but y may be any Lisp object.


(second list)                                                 [function]
        Returns the second element in list.


(set-difference list1 list2 &key :test :test-not :key)        [function]
        Returns a list of  the elements in list1  that do not appear  in
        list2.


(set-exclusive-or list1 list2 &key :test :test-not :key)      [function]
        Returns a list of elements that  appear in exactly one of  list1
        and list2.


(seventh list)                                                [function]
        Returns the seventh element in list.


(sixth list)                                                  [function]
        Returns the sixth element in list.


(sublis alist tree &key :test :test-not :key)                 [function]
        Returns tree with substitutions from the association list  alist
        as in nsublis.


(subsetp list1 list2 &key :test :test-not :key)               [function]
        subsetp is a predicate  that is true if  every element of  list1
        appears in list2. nil otherwise.


(subst new old tree &key :test :test-not :key)                [function]
        Returns tree with all occurrances  of old substituted by new  as
        in nsubst.


(subst-if new test tree &key :key)                            [function]
        Returns tree with new substituted where :test is satisfied as in
        nsubst-if.


(subst-if-not new test tree &key :key)                        [function]
        Returns tree with new substituted where test is not satisfied as
        in nsubst-if-not.


(tailp sublist list)                                          [function]
        tailp is true if sublist is a sublist of list. nil otherwise.


(tenth list)                                                  [function]
        Returns the tenth element in list.


(third list)                                                  [function]
        Returns the third element in list.


(tree-equal x y &key :test :test-not)                         [function]
        Returns true  if x  and y  are isomorphic  trees with  identical
        leaves. nil otherwise.


(union list1 list2 &key :test :test-not :key)                 [function]
        Returns a single list of the elements in list1 and list2.



--- C.all/lisp/ref/lists
--- Copyright University of Sussex 1990. All rights reserved.
