root/branches/2.1/info/cl-4

This is ../info/cl, produced by makeinfo version 4.2 from cl.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* CL: (cl).             Partial Common Lisp support for Emacs Lisp.
END-INFO-DIR-ENTRY

   This file documents the GNU Emacs Common Lisp emulation package.

   Copyright (C) 1993 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being "A GNU Manual",
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled "GNU Free Documentation License" in
the Emacs manual.

   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development."

   This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.


File: cl,  Node: Implementation Parameters,  Prev: Random Numbers,  Up: Numbers

Implementation Parameters
=========================

This package defines several useful constants having to with numbers.

 - Variable: most-positive-fixnum
     This constant equals the largest value a Lisp integer can hold.
     It is typically `2^23-1' or `2^25-1'.

 - Variable: most-negative-fixnum
     This constant equals the smallest (most negative) value a Lisp
     integer can hold.

   The following parameters have to do with floating-point numbers.
This package determines their values by exercising the computer's
floating-point arithmetic in various ways.  Because this operation
might be slow, the code for initializing them is kept in a separate
function that must be called before the parameters can be used.

 - Function: cl-float-limits
     This function makes sure that the Common Lisp floating-point
     parameters like `most-positive-float' have been initialized.
     Until it is called, these parameters will be `nil'.  If this
     version of Emacs does not support floats, the parameters will
     remain `nil'.  If the parameters have already been initialized,
     the function returns immediately.

     The algorithm makes assumptions that will be valid for most modern
     machines, but will fail if the machine's arithmetic is extremely
     unusual, e.g., decimal.

   Since true Common Lisp supports up to four different floating-point
precisions, it has families of constants like
`most-positive-single-float', `most-positive-double-float',
`most-positive-long-float', and so on.  Emacs has only one
floating-point precision, so this package omits the precision word from
the constants' names.

 - Variable: most-positive-float
     This constant equals the largest value a Lisp float can hold.  For
     those systems whose arithmetic supports infinities, this is the
     largest _finite_ value.  For IEEE machines, the value is
     approximately `1.79e+308'.

 - Variable: most-negative-float
     This constant equals the most-negative value a Lisp float can hold.
     (It is assumed to be equal to `(- most-positive-float)'.)

 - Variable: least-positive-float
     This constant equals the smallest Lisp float value greater than
     zero.  For IEEE machines, it is about `4.94e-324' if denormals are
     supported or `2.22e-308' if not.

 - Variable: least-positive-normalized-float
     This constant equals the smallest _normalized_ Lisp float greater
     than zero, i.e., the smallest value for which IEEE denormalization
     will not result in a loss of precision.  For IEEE machines, this
     value is about `2.22e-308'.  For machines that do not support the
     concept of denormalization and gradual underflow, this constant
     will always equal `least-positive-float'.

 - Variable: least-negative-float
     This constant is the negative counterpart of
     `least-positive-float'.

 - Variable: least-negative-normalized-float
     This constant is the negative counterpart of
     `least-positive-normalized-float'.

 - Variable: float-epsilon
     This constant is the smallest positive Lisp float that can be added
     to 1.0 to produce a distinct value.  Adding a smaller number to 1.0
     will yield 1.0 again due to roundoff.  For IEEE machines, epsilon
     is about `2.22e-16'.

 - Variable: float-negative-epsilon
     This is the smallest positive value that can be subtracted from
     1.0 to produce a distinct value.  For IEEE machines, it is about
     `1.11e-16'.


File: cl,  Node: Sequences,  Next: Lists,  Prev: Numbers,  Up: Top

Sequences
*********

Common Lisp defines a number of functions that operate on "sequences",
which are either lists, strings, or vectors.  Emacs Lisp includes a few
of these, notably `elt' and `length'; this package defines most of the
rest.

* Menu:

* Sequence Basics::          Arguments shared by all sequence functions
* Mapping over Sequences::   `mapcar*', `mapcan', `map', `every', etc.
* Sequence Functions::       `subseq', `remove*', `substitute', etc.
* Searching Sequences::      `find', `position', `count', `search', etc.
* Sorting Sequences::        `sort*', `stable-sort', `merge'


File: cl,  Node: Sequence Basics,  Next: Mapping over Sequences,  Prev: Sequences,  Up: Sequences

Sequence Basics
===============

Many of the sequence functions take keyword arguments; *note Argument
Lists::.  All keyword arguments are optional and, if specified, may
appear in any order.

   The `:key' argument should be passed either `nil', or a function of
one argument.  This key function is used as a filter through which the
elements of the sequence are seen; for example, `(find x y :key 'car)'
is similar to `(assoc* x y)': It searches for an element of the list
whose `car' equals `x', rather than for an element which equals `x'
itself.  If `:key' is omitted or `nil', the filter is effectively the
identity function.

   The `:test' and `:test-not' arguments should be either `nil', or
functions of two arguments.  The test function is used to compare two
sequence elements, or to compare a search value with sequence elements.
(The two values are passed to the test function in the same order as
the original sequence function arguments from which they are derived,
or, if they both come from the same sequence, in the same order as they
appear in that sequence.)  The `:test' argument specifies a function
which must return true (non-`nil') to indicate a match; instead, you
may use `:test-not' to give a function which returns _false_ to
indicate a match.  The default test function is `:test 'eql'.

   Many functions which take ITEM and `:test' or `:test-not' arguments
also come in `-if' and `-if-not' varieties, where a PREDICATE function
is passed instead of ITEM, and sequence elements match if the predicate
returns true on them (or false in the case of `-if-not').  For example:

     (remove* 0 seq :test '=)  ==  (remove-if 'zerop seq)

to remove all zeros from sequence `seq'.

   Some operations can work on a subsequence of the argument sequence;
these function take `:start' and `:end' arguments which default to zero
and the length of the sequence, respectively.  Only elements between
START (inclusive) and END (exclusive) are affected by the operation.
The END argument may be passed `nil' to signify the length of the
sequence; otherwise, both START and END must be integers, with `0 <=
START <= END <= (length SEQ)'.  If the function takes two sequence
arguments, the limits are defined by keywords `:start1' and `:end1' for
the first, and `:start2' and `:end2' for the second.

   A few functions accept a `:from-end' argument, which, if non-`nil',
causes the operation to go from right-to-left through the sequence
instead of left-to-right, and a `:count' argument, which specifies an
integer maximum number of elements to be removed or otherwise processed.

   The sequence functions make no guarantees about the order in which
the `:test', `:test-not', and `:key' functions are called on various
elements.  Therefore, it is a bad idea to depend on side effects of
these functions.  For example, `:from-end' may cause the sequence to be
scanned actually in reverse, or it may be scanned forwards but
computing a result "as if" it were scanned backwards.  (Some functions,
like `mapcar*' and `every', _do_ specify exactly the order in which the
function is called so side effects are perfectly acceptable in those
cases.)

   Strings may contain "text properties" as well as character data.
Except as noted, it is undefined whether or not text properties are
preserved by sequence functions.  For example, `(remove* ?A STR)' may
or may not preserve the properties of the characters copied from STR
into the result.


File: cl,  Node: Mapping over Sequences,  Next: Sequence Functions,  Prev: Sequence Basics,  Up: Sequences

Mapping over Sequences
======================

These functions "map" the function you specify over the elements of
lists or arrays.  They are all variations on the theme of the built-in
function `mapcar'.

 - Function: mapcar* function seq &rest more-seqs
     This function calls FUNCTION on successive parallel sets of
     elements from its argument sequences.  Given a single SEQ argument
     it is equivalent to `mapcar'; given N sequences, it calls the
     function with the first elements of each of the sequences as the N
     arguments to yield the first element of the result list, then with
     the second elements, and so on.  The mapping stops as soon as the
     shortest sequence runs out.  The argument sequences may be any
     mixture of lists, strings, and vectors; the return sequence is
     always a list.

     Common Lisp's `mapcar' accepts multiple arguments but works only
     on lists; Emacs Lisp's `mapcar' accepts a single sequence
     argument.  This package's `mapcar*' works as a compatible superset
     of both.

 - Function: map result-type function seq &rest more-seqs
     This function maps FUNCTION over the argument sequences, just like
     `mapcar*', but it returns a sequence of type RESULT-TYPE rather
     than a list.  RESULT-TYPE must be one of the following symbols:
     `vector', `string', `list' (in which case the effect is the same
     as for `mapcar*'), or `nil' (in which case the results are thrown
     away and `map' returns `nil').

 - Function: maplist function list &rest more-lists
     This function calls FUNCTION on each of its argument lists, then
     on the `cdr's of those lists, and so on, until the shortest list
     runs out.  The results are returned in the form of a list.  Thus,
     `maplist' is like `mapcar*' except that it passes in the list
     pointers themselves rather than the `car's of the advancing
     pointers.

 - Function: mapc function seq &rest more-seqs
     This function is like `mapcar*', except that the values returned
     by FUNCTION are ignored and thrown away rather than being
     collected into a list.  The return value of `mapc' is SEQ, the
     first sequence.  This function is more general than the Emacs
     primitive `mapc'.

 - Function: mapl function list &rest more-lists
     This function is like `maplist', except that it throws away the
     values returned by FUNCTION.

 - Function: mapcan function seq &rest more-seqs
     This function is like `mapcar*', except that it concatenates the
     return values (which must be lists) using `nconc', rather than
     simply collecting them into a list.

 - Function: mapcon function list &rest more-lists
     This function is like `maplist', except that it concatenates the
     return values using `nconc'.

 - Function: some predicate seq &rest more-seqs
     This function calls PREDICATE on each element of SEQ in turn; if
     PREDICATE returns a non-`nil' value, `some' returns that value,
     otherwise it returns `nil'.  Given several sequence arguments, it
     steps through the sequences in parallel until the shortest one
     runs out, just as in `mapcar*'.  You can rely on the left-to-right
     order in which the elements are visited, and on the fact that
     mapping stops immediately as soon as PREDICATE returns non-`nil'.

 - Function: every predicate seq &rest more-seqs
     This function calls PREDICATE on each element of the sequence(s)
     in turn; it returns `nil' as soon as PREDICATE returns `nil' for
     any element, or `t' if the predicate was true for all elements.

 - Function: notany predicate seq &rest more-seqs
     This function calls PREDICATE on each element of the sequence(s)
     in turn; it returns `nil' as soon as PREDICATE returns a non-`nil'
     value for any element, or `t' if the predicate was `nil' for all
     elements.

 - Function: notevery predicate seq &rest more-seqs
     This function calls PREDICATE on each element of the sequence(s)
     in turn; it returns a non-`nil' value as soon as PREDICATE returns
     `nil' for any element, or `t' if the predicate was true for all
     elements.

 - Function: reduce function seq &key :from-end :start :end
          :initial-value :key
     This function combines the elements of SEQ using an associative
     binary operation.  Suppose FUNCTION is `*' and SEQ is the list `(2
     3 4 5)'.  The first two elements of the list are combined with `(*
     2 3) = 6'; this is combined with the next element, `(* 6 4) = 24',
     and that is combined with the final element: `(* 24 5) = 120'.
     Note that the `*' function happens to be self-reducing, so that
     `(* 2 3 4 5)' has the same effect as an explicit call to `reduce'.

     If `:from-end' is true, the reduction is right-associative instead
     of left-associative:

          (reduce '- '(1 2 3 4))
               == (- (- (- 1 2) 3) 4) => -8
          (reduce '- '(1 2 3 4) :from-end t)
               == (- 1 (- 2 (- 3 4))) => -2

     If `:key' is specified, it is a function of one argument which is
     called on each of the sequence elements in turn.

     If `:initial-value' is specified, it is effectively added to the
     front (or rear in the case of `:from-end') of the sequence.  The
     `:key' function is _not_ applied to the initial value.

     If the sequence, including the initial value, has exactly one
     element then that element is returned without ever calling
     FUNCTION.  If the sequence is empty (and there is no initial
     value), then FUNCTION is called with no arguments to obtain the
     return value.

   All of these mapping operations can be expressed conveniently in
terms of the `loop' macro.  In compiled code, `loop' will be faster
since it generates the loop as in-line code with no function calls.


File: cl,  Node: Sequence Functions,  Next: Searching Sequences,  Prev: Mapping over Sequences,  Up: Sequences

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.


File: cl,  Node: Searching Sequences,  Next: Sorting Sequences,  Prev: Sequence Functions,  Up: Sequences

Searching Sequences
===================

These functions search for elements or subsequences in a sequence.
(See also `member*' and `assoc*'; *note Lists::.)

 - Function: find item seq &key :test :test-not :key :start :end
          :from-end
     This function searches SEQ for an element matching ITEM.  If it
     finds a match, it returns the matching element.  Otherwise, it
     returns `nil'.  It returns the leftmost match, unless `:from-end'
     is true, in which case it returns the rightmost match.  The
     `:start' and `:end' arguments may be used to limit the range of
     elements that are searched.

 - Function: position item seq &key :test :test-not :key :start :end
          :from-end
     This function is like `find', except that it returns the integer
     position in the sequence of the matching item rather than the item
     itself.  The position is relative to the start of the sequence as
     a whole, even if `:start' is non-zero.  The function returns `nil'
     if no matching element was found.

 - Function: count item seq &key :test :test-not :key :start :end
     This function returns the number of elements of SEQ which match
     ITEM.  The result is always a nonnegative integer.

   The `find-if', `find-if-not', `position-if', `position-if-not',
`count-if', and `count-if-not' functions are defined similarly.

 - Function: mismatch seq1 seq2 &key :test :test-not :key :start1 :end1
          :start2 :end2 :from-end
     This function compares the specified parts of SEQ1 and SEQ2.  If
     they are the same length and the corresponding elements match
     (according to `:test', `:test-not', and `:key'), the function
     returns `nil'.  If there is a mismatch, the function returns the
     index (relative to SEQ1) of the first mismatching element.  This
     will be the leftmost pair of elements which do not match, or the
     position at which the shorter of the two otherwise-matching
     sequences runs out.

     If `:from-end' is true, then the elements are compared from right
     to left starting at `(1- END1)' and `(1- END2)'.  If the sequences
     differ, then one plus the index of the rightmost difference
     (relative to SEQ1) is returned.

     An interesting example is `(mismatch str1 str2 :key 'upcase)',
     which compares two strings case-insensitively.

 - Function: search seq1 seq2 &key :test :test-not :key :from-end
          :start1 :end1 :start2 :end2
     This function searches SEQ2 for a subsequence that matches SEQ1
     (or part of it specified by `:start1' and `:end1'.)  Only matches
     which fall entirely within the region defined by `:start2' and
     `:end2' will be considered.  The return value is the index of the
     leftmost element of the leftmost match, relative to the start of
     SEQ2, or `nil' if no matches were found.  If `:from-end' is true,
     the function finds the _rightmost_ matching subsequence.


File: cl,  Node: Sorting Sequences,  Prev: Searching Sequences,  Up: Sequences

Sorting Sequences
=================

 - Function: sort* seq predicate &key :key
     This function sorts SEQ into increasing order as determined by
     using PREDICATE to compare pairs of elements.  PREDICATE should
     return true (non-`nil') if and only if its first argument is less
     than (not equal to) its second argument.  For example, `<' and
     `string-lessp' are suitable predicate functions for sorting
     numbers and strings, respectively; `>' would sort numbers into
     decreasing rather than increasing order.

     This function differs from Emacs' built-in `sort' in that it can
     operate on any type of sequence, not just lists.  Also, it accepts
     a `:key' argument which is used to preprocess data fed to the
     PREDICATE function.  For example,

          (setq data (sort data 'string-lessp :key 'downcase))

     sorts DATA, a sequence of strings, into increasing alphabetical
     order without regard to case.  A `:key' function of `car' would be
     useful for sorting association lists.

     The `sort*' function is destructive; it sorts lists by actually
     rearranging the `cdr' pointers in suitable fashion.

 - Function: stable-sort seq predicate &key :key
     This function sorts SEQ "stably", meaning two elements which are
     equal in terms of PREDICATE are guaranteed not to be rearranged
     out of their original order by the sort.

     In practice, `sort*' and `stable-sort' are equivalent in Emacs
     Lisp because the underlying `sort' function is stable by default.
     However, this package reserves the right to use non-stable methods
     for `sort*' in the future.

 - Function: merge type seq1 seq2 predicate &key :key
     This function merges two sequences SEQ1 and SEQ2 by interleaving
     their elements.  The result sequence, of type TYPE (in the sense
     of `concatenate'), has length equal to the sum of the lengths of
     the two input sequences.  The sequences may be modified
     destructively.  Order of elements within SEQ1 and SEQ2 is
     preserved in the interleaving; elements of the two sequences are
     compared by PREDICATE (in the sense of `sort') and the lesser
     element goes first in the result.  When elements are equal, those
     from SEQ1 precede those from SEQ2 in the result.  Thus, if SEQ1
     and SEQ2 are both sorted according to PREDICATE, then the result
     will be a merged sequence which is (stably) sorted according to
     PREDICATE.


File: cl,  Node: Lists,  Next: Structures,  Prev: Sequences,  Up: Top

Lists
*****

The functions described here operate on lists.

* Menu:

* List Functions::                `caddr', `first', `list*', etc.
* Substitution of Expressions::   `subst', `sublis', etc.
* Lists as Sets::                 `member*', `adjoin', `union', etc.
* Association Lists::             `assoc*', `rassoc*', `acons', `pairlis'


File: cl,  Node: List Functions,  Next: Substitution of Expressions,  Prev: Lists,  Up: Lists

List Functions
==============

This section describes a number of simple operations on lists, i.e.,
chains of cons cells.

 - Function: caddr x
     This function is equivalent to `(car (cdr (cdr X)))'.  Likewise,
     this package defines all 28 `cXXXr' functions where XXX is up to
     four `a's and/or `d's.  All of these functions are `setf'-able,
     and calls to them are expanded inline by the byte-compiler for
     maximum efficiency.

 - Function: first x
     This function is a synonym for `(car X)'.  Likewise, the functions
     `second', `third', ..., through `tenth' return the given element
     of the list X.

 - Function: rest x
     This function is a synonym for `(cdr X)'.

 - Function: endp x
     Common Lisp defines this function to act like `null', but
     signaling an error if `x' is neither a `nil' nor a cons cell.
     This package simply defines `endp' as a synonym for `null'.

 - Function: list-length x
     This function returns the length of list X, exactly like `(length
     X)', except that if X is a circular list (where the cdr-chain
     forms a loop rather than terminating with `nil'), this function
     returns `nil'.  (The regular `length' function would get stuck if
     given a circular list.)

 - Function: list* arg &rest others
     This function constructs a list of its arguments.  The final
     argument becomes the `cdr' of the last cell constructed.  Thus,
     `(list* A B C)' is equivalent to `(cons A (cons B C))', and
     `(list* A B nil)' is equivalent to `(list A B)'.

     (Note that this function really is called `list*' in Common Lisp;
     it is not a name invented for this package like `member*' or
     `defun*'.)

 - Function: ldiff list sublist
     If SUBLIST is a sublist of LIST, i.e., is `eq' to one of the cons
     cells of LIST, then this function returns a copy of the part of
     LIST up to but not including SUBLIST.  For example, `(ldiff x
     (cddr x))' returns the first two elements of the list `x'.  The
     result is a copy; the original LIST is not modified.  If SUBLIST
     is not a sublist of LIST, a copy of the entire LIST is returned.

 - Function: copy-list list
     This function returns a copy of the list LIST.  It copies dotted
     lists like `(1 2 . 3)' correctly.

 - Function: copy-tree x &optional vecp
     This function returns a copy of the tree of cons cells X.  Unlike
     `copy-sequence' (and its alias `copy-list'), which copies only
     along the `cdr' direction, this function copies (recursively)
     along both the `car' and the `cdr' directions.  If X is not a cons
     cell, the function simply returns X unchanged.  If the optional
     VECP argument is true, this function copies vectors (recursively)
     as well as cons cells.

 - Function: tree-equal x y &key :test :test-not :key
     This function compares two trees of cons cells.  If X and Y are
     both cons cells, their `car's and `cdr's are compared recursively.
     If neither X nor Y is a cons cell, they are compared by `eql', or
     according to the specified test.  The `:key' function, if
     specified, is applied to the elements of both trees.  *Note
     Sequences::.


File: cl,  Node: Substitution of Expressions,  Next: Lists as Sets,  Prev: List Functions,  Up: Lists

Substitution of Expressions
===========================

These functions substitute elements throughout a tree of cons cells.
(*Note Sequence Functions::, for the `substitute' function, which works
on just the top-level elements of a list.)

 - Function: subst new old tree &key :test :test-not :key
     This function substitutes occurrences of OLD with NEW in TREE, a
     tree of cons cells.  It returns a substituted tree, which will be
     a copy except that it may share storage with the argument TREE in
     parts where no substitutions occurred.  The original TREE is not
     modified.  This function recurses on, and compares against OLD,
     both `car's and `cdr's of the component cons cells.  If OLD is
     itself a cons cell, then matching cells in the tree are
     substituted as usual without recursively substituting in that
     cell.  Comparisons with OLD are done according to the specified
     test (`eql' by default).  The `:key' function is applied to the
     elements of the tree but not to OLD.

 - Function: nsubst new old tree &key :test :test-not :key
     This function is like `subst', except that it works by destructive
     modification (by `setcar' or `setcdr') rather than copying.

   The `subst-if', `subst-if-not', `nsubst-if', and `nsubst-if-not'
functions are defined similarly.

 - Function: sublis alist tree &key :test :test-not :key
     This function is like `subst', except that it takes an association
     list ALIST of OLD-NEW pairs.  Each element of the tree (after
     applying the `:key' function, if any), is compared with the `car's
     of ALIST; if it matches, it is replaced by the corresponding `cdr'.

 - Function: nsublis alist tree &key :test :test-not :key
     This is a destructive version of `sublis'.


File: cl,  Node: Lists as Sets,  Next: Association Lists,  Prev: Substitution of Expressions,  Up: Lists

Lists as Sets
=============

These functions perform operations on lists which represent sets of
elements.

 - Function: member* item list &key :test :test-not :key
     This function searches LIST for an element matching ITEM.  If a
     match is found, it returns the cons cell whose `car' was the
     matching element.  Otherwise, it returns `nil'.  Elements are
     compared by `eql' by default; you can use the `:test',
     `:test-not', and `:key' arguments to modify this behavior.  *Note
     Sequences::.

     Note that this function's name is suffixed by `*' to avoid the
     incompatible `member' function defined in Emacs.  (That function
     uses `equal' for comparisons; it is equivalent to `(member* ITEM
     LIST :test 'equal)'.)

   The `member-if' and `member-if-not' functions analogously search for
elements which satisfy a given predicate.

 - Function: tailp sublist list
     This function returns `t' if SUBLIST is a sublist of LIST, i.e.,
     if SUBLIST is `eql' to LIST or to any of its `cdr's.

 - Function: adjoin item list &key :test :test-not :key
     This function conses ITEM onto the front of LIST, like `(cons ITEM
     LIST)', but only if ITEM is not already present on the list (as
     determined by `member*').  If a `:key' argument is specified, it
     is applied to ITEM as well as to the elements of LIST during the
     search, on the reasoning that ITEM is "about" to become part of
     the list.

 - Function: union list1 list2 &key :test :test-not :key
     This function combines two lists which represent sets of items,
     returning a list that represents the union of those two sets.  The
     result list will contain all items which appear in LIST1 or LIST2,
     and no others.  If an item appears in both LIST1 and LIST2 it will
     be copied only once.  If an item is duplicated in LIST1 or LIST2,
     it is undefined whether or not that duplication will survive in the
     result list.  The order of elements in the result list is also
     undefined.

 - Function: nunion list1 list2 &key :test :test-not :key
     This is a destructive version of `union'; rather than copying, it
     tries to reuse the storage of the argument lists if possible.

 - Function: intersection list1 list2 &key :test :test-not :key
     This function computes the intersection of the sets represented by
     LIST1 and LIST2.  It returns the list of items which appear in
     both LIST1 and LIST2.

 - Function: nintersection list1 list2 &key :test :test-not :key
     This is a destructive version of `intersection'.  It tries to
     reuse storage of LIST1 rather than copying.  It does _not_ reuse
     the storage of LIST2.

 - Function: set-difference list1 list2 &key :test :test-not :key
     This function computes the "set difference" of LIST1 and LIST2,
     i.e., the set of elements that appear in LIST1 but _not_ in LIST2.

 - Function: nset-difference list1 list2 &key :test :test-not :key
     This is a destructive `set-difference', which will try to reuse
     LIST1 if possible.

 - Function: set-exclusive-or list1 list2 &key :test :test-not :key
     This function computes the "set exclusive or" of LIST1 and LIST2,
     i.e., the set of elements that appear in exactly one of LIST1 and
     LIST2.

 - Function: nset-exclusive-or list1 list2 &key :test :test-not :key
     This is a destructive `set-exclusive-or', which will try to reuse
     LIST1 and LIST2 if possible.

 - Function: subsetp list1 list2 &key :test :test-not :key
     This function checks whether LIST1 represents a subset of LIST2,
     i.e., whether every element of LIST1 also appears in LIST2.


File: cl,  Node: Association Lists,  Prev: Lists as Sets,  Up: Lists

Association Lists
=================

An "association list" is a list representing a mapping from one set of
values to another; any list whose elements are cons cells is an
association list.

 - Function: assoc* item a-list &key :test :test-not :key
     This function searches the association list A-LIST for an element
     whose `car' matches (in the sense of `:test', `:test-not', and
     `:key', or by comparison with `eql') a given ITEM.  It returns the
     matching element, if any, otherwise `nil'.  It ignores elements of
     A-LIST which are not cons cells.  (This corresponds to the
     behavior of `assq' and `assoc' in Emacs Lisp; Common Lisp's
     `assoc' ignores `nil's but considers any other non-cons elements
     of A-LIST to be an error.)

 - Function: rassoc* item a-list &key :test :test-not :key
     This function searches for an element whose `cdr' matches ITEM.
     If A-LIST represents a mapping, this applies the inverse of the
     mapping to ITEM.

   The `assoc-if', `assoc-if-not', `rassoc-if', and `rassoc-if-not'
functions are defined similarly.

   Two simple functions for constructing association lists are:

 - Function: acons key value alist
     This is equivalent to `(cons (cons KEY VALUE) ALIST)'.

 - Function: pairlis keys values &optional alist
     This is equivalent to `(nconc (mapcar* 'cons KEYS VALUES) ALIST)'.