This commit was generated by cvs2svn to compensate for changes in r6453,

[chise/xemacs-chise.git.1] / info / lispref.info-6

This is Info file ../../info/lispref.info, produced by Makeinfo version
1.68 from the input file lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).           XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

\1f
File: lispref.info,  Node: List Elements,  Next: Building Lists,  Prev: List-related Predicates,  Up: Lists

Accessing Elements of Lists
===========================

 - Function: car CONS-CELL
     This function returns the value pointed to by the first pointer of
     the cons cell CONS-CELL.  Expressed another way, this function
     returns the CAR of CONS-CELL.

     As a special case, if CONS-CELL is `nil', then `car' is defined to
     return `nil'; therefore, any list is a valid argument for `car'.
     An error is signaled if the argument is not a cons cell or `nil'.

          (car '(a b c))
               => a
          (car '())
               => nil

 - Function: cdr CONS-CELL
     This function returns the value pointed to by the second pointer of
     the cons cell CONS-CELL.  Expressed another way, this function
     returns the CDR of CONS-CELL.

     As a special case, if CONS-CELL is `nil', then `cdr' is defined to
     return `nil'; therefore, any list is a valid argument for `cdr'.
     An error is signaled if the argument is not a cons cell or `nil'.

          (cdr '(a b c))
               => (b c)
          (cdr '())
               => nil

 - Function: car-safe OBJECT
     This function lets you take the CAR of a cons cell while avoiding
     errors for other data types.  It returns the CAR of OBJECT if
     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
     `car', which signals an error if OBJECT is not a list.

          (car-safe OBJECT)
          ==
          (let ((x OBJECT))
            (if (consp x)
                (car x)
              nil))

 - Function: cdr-safe OBJECT
     This function lets you take the CDR of a cons cell while avoiding
     errors for other data types.  It returns the CDR of OBJECT if
     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
     `cdr', which signals an error if OBJECT is not a list.

          (cdr-safe OBJECT)
          ==
          (let ((x OBJECT))
            (if (consp x)
                (cdr x)
              nil))

 - Function: nth N LIST
     This function returns the Nth element of LIST.  Elements are
     numbered starting with zero, so the CAR of LIST is element number
     zero.  If the length of LIST is N or less, the value is `nil'.

     If N is negative, `nth' returns the first element of LIST.

          (nth 2 '(1 2 3 4))
               => 3
          (nth 10 '(1 2 3 4))
               => nil
          (nth -3 '(1 2 3 4))
               => 1
          
          (nth n x) == (car (nthcdr n x))

 - Function: nthcdr N LIST
     This function returns the Nth CDR of LIST.  In other words, it
     removes the first N links of LIST and returns what follows.

     If N is zero or negative, `nthcdr' returns all of LIST.  If the
     length of LIST is N or less, `nthcdr' returns `nil'.

          (nthcdr 1 '(1 2 3 4))
               => (2 3 4)
          (nthcdr 10 '(1 2 3 4))
               => nil
          (nthcdr -3 '(1 2 3 4))
               => (1 2 3 4)

   Many convenience functions are provided to make it easier for you to
access particular elements in a nested list.  All of these can be
rewritten in terms of the functions just described.

 - Function: caar CONS-CELL
 - Function: cadr CONS-CELL
 - Function: cdar CONS-CELL
 - Function: cddr CONS-CELL
 - Function: caaar CONS-CELL
 - Function: caadr CONS-CELL
 - Function: cadar CONS-CELL
 - Function: caddr CONS-CELL
 - Function: cdaar CONS-CELL
 - Function: cdadr CONS-CELL
 - Function: cddar CONS-CELL
 - Function: cdddr CONS-CELL
 - Function: caaaar CONS-CELL
 - Function: caaadr CONS-CELL
 - Function: caadar CONS-CELL
 - Function: caaddr CONS-CELL
 - Function: cadaar CONS-CELL
 - Function: cadadr CONS-CELL
 - Function: caddar CONS-CELL
 - Function: cadddr CONS-CELL
 - Function: cdaaar CONS-CELL
 - Function: cdaadr CONS-CELL
 - Function: cdadar CONS-CELL
 - Function: cdaddr CONS-CELL
 - Function: cddaar CONS-CELL
 - Function: cddadr CONS-CELL
 - Function: cdddar CONS-CELL
 - Function: cddddr CONS-CELL
     Each of these functions is equivalent to one or more applications
     of `car' and/or `cdr'.  For example,

          (cadr x)

     is equivalent to

          (car (cdr x))

     and

          (cdaddr x)

     is equivalent to

          (cdr (car (cdr (cdr x))))

     That is to say, read the a's and d's from right to left and apply
     a `car' or `cdr' for each a or d found, respectively.

 - Function: first LIST
     This is equivalent to `(nth 0 LIST)', i.e. the first element of
     LIST. (Note that this is also equivalent to `car'.)

 - Function: second LIST
     This is equivalent to `(nth 1 LIST)', i.e. the second element of
     LIST.

 - Function: third LIST
 - Function: fourth LIST
 - Function: fifth LIST
 - Function: sixth LIST
 - Function: seventh LIST
 - Function: eighth LIST
 - Function: ninth LIST
 - Function: tenth LIST
     These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
     respectively, i.e. the third through tenth elements of LIST.

\1f
File: lispref.info,  Node: Building Lists,  Next: Modifying Lists,  Prev: List Elements,  Up: Lists

Building Cons Cells and Lists
=============================

   Many functions build lists, as lists reside at the very heart of
Lisp.  `cons' is the fundamental list-building function; however, it is
interesting to note that `list' is used more times in the source code
for Emacs than `cons'.

 - Function: cons OBJECT1 OBJECT2
     This function is the fundamental function used to build new list
     structure.  It creates a new cons cell, making OBJECT1 the CAR,
     and OBJECT2 the CDR.  It then returns the new cons cell.  The
     arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
     often OBJECT2 is a list.

          (cons 1 '(2))
               => (1 2)
          (cons 1 '())
               => (1)
          (cons 1 2)
               => (1 . 2)

     `cons' is often used to add a single element to the front of a
     list.  This is called "consing the element onto the list".  For
     example:

          (setq list (cons newelt list))

     Note that there is no conflict between the variable named `list'
     used in this example and the function named `list' described below;
     any symbol can serve both purposes.

 - Function: list &rest OBJECTS
     This function creates a list with OBJECTS as its elements.  The
     resulting list is always `nil'-terminated.  If no OBJECTS are
     given, the empty list is returned.

          (list 1 2 3 4 5)
               => (1 2 3 4 5)
          (list 1 2 '(3 4 5) 'foo)
               => (1 2 (3 4 5) foo)
          (list)
               => nil

 - Function: make-list LENGTH OBJECT
     This function creates a list of length LENGTH, in which all the
     elements have the identical value OBJECT.  Compare `make-list'
     with `make-string' (*note Creating Strings::.).

          (make-list 3 'pigs)
               => (pigs pigs pigs)
          (make-list 0 'pigs)
               => nil

 - Function: append &rest SEQUENCES
     This function returns a list containing all the elements of
     SEQUENCES.  The SEQUENCES may be lists, vectors, or strings, but
     the last one should be a list.  All arguments except the last one
     are copied, so none of them are altered.

     More generally, the final argument to `append' may be any Lisp
     object.  The final argument is not copied or converted; it becomes
     the CDR of the last cons cell in the new list.  If the final
     argument is itself a list, then its elements become in effect
     elements of the result list.  If the final element is not a list,
     the result is a "dotted list" since its final CDR is not `nil' as
     required in a true list.

     See `nconc' in *Note Rearrangement::, for a way to join lists with
     no copying.

     Here is an example of using `append':

          (setq trees '(pine oak))
               => (pine oak)
          (setq more-trees (append '(maple birch) trees))
               => (maple birch pine oak)
          
          trees
               => (pine oak)
          more-trees
               => (maple birch pine oak)
          (eq trees (cdr (cdr more-trees)))
               => t

     You can see how `append' works by looking at a box diagram.  The
     variable `trees' is set to the list `(pine oak)' and then the
     variable `more-trees' is set to the list `(maple birch pine oak)'.
     However, the variable `trees' continues to refer to the original
     list:

          more-trees                trees
          |                           |
          |     ___ ___      ___ ___   -> ___ ___      ___ ___
           --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
                 |            |            |            |
                 |            |            |            |
                  --> maple    -->birch     --> pine     --> oak

     An empty sequence contributes nothing to the value returned by
     `append'.  As a consequence of this, a final `nil' argument forces
     a copy of the previous argument.

          trees
               => (pine oak)
          (setq wood (append trees ()))
               => (pine oak)
          wood
               => (pine oak)
          (eq wood trees)
               => nil

     This once was the usual way to copy a list, before the function
     `copy-sequence' was invented.  *Note Sequences Arrays Vectors::.

     With the help of `apply', we can append all the lists in a list of
     lists:

          (apply 'append '((a b c) nil (x y z) nil))
               => (a b c x y z)

     If no SEQUENCES are given, `nil' is returned:

          (append)
               => nil

     Here are some examples where the final argument is not a list:

          (append '(x y) 'z)
               => (x y . z)
          (append '(x y) [z])
               => (x y . [z])

     The second example shows that when the final argument is a
     sequence but not a list, the sequence's elements do not become
     elements of the resulting list.  Instead, the sequence becomes the
     final CDR, like any other non-list final argument.

     The `append' function also allows integers as arguments.  It
     converts them to strings of digits, making up the decimal print
     representation of the integer, and then uses the strings instead
     of the original integers.  *Don't use this feature; we plan to
     eliminate it.  If you already use this feature, change your
     programs now!*  The proper way to convert an integer to a decimal
     number in this way is with `format' (*note Formatting Strings::.)
     or `number-to-string' (*note String Conversion::.).

 - Function: reverse LIST
     This function creates a new list whose elements are the elements of
     LIST, but in reverse order.  The original argument LIST is *not*
     altered.

          (setq x '(1 2 3 4))
               => (1 2 3 4)
          (reverse x)
               => (4 3 2 1)
          x
               => (1 2 3 4)

\1f
File: lispref.info,  Node: Modifying Lists,  Next: Sets And Lists,  Prev: Building Lists,  Up: Lists

Modifying Existing List Structure
=================================

   You can modify the CAR and CDR contents of a cons cell with the
primitives `setcar' and `setcdr'.

     Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
     to alter list structure; they change structure the same way as
     `setcar' and `setcdr', but the Common Lisp functions return the
     cons cell while `setcar' and `setcdr' return the new CAR or CDR.

* Menu:

* Setcar::          Replacing an element in a list.
* Setcdr::          Replacing part of the list backbone.
                      This can be used to remove or add elements.
* Rearrangement::   Reordering the elements in a list; combining lists.

\1f
File: lispref.info,  Node: Setcar,  Next: Setcdr,  Up: Modifying Lists

Altering List Elements with `setcar'
------------------------------------

   Changing the CAR of a cons cell is done with `setcar'.  When used on
a list, `setcar' replaces one element of a list with a different
element.

 - Function: setcar CONS OBJECT
     This function stores OBJECT as the new CAR of CONS, replacing its
     previous CAR.  It returns the value OBJECT.  For example:

          (setq x '(1 2))
               => (1 2)
          (setcar x 4)
               => 4
          x
               => (4 2)

   When a cons cell is part of the shared structure of several lists,
storing a new CAR into the cons changes one element of each of these
lists.  Here is an example:

     ;; Create two lists that are partly shared.
     (setq x1 '(a b c))
          => (a b c)
     (setq x2 (cons 'z (cdr x1)))
          => (z b c)
     
     ;; Replace the CAR of a shared link.
     (setcar (cdr x1) 'foo)
          => foo
     x1                           ; Both lists are changed.
          => (a foo c)
     x2
          => (z foo c)
     
     ;; Replace the CAR of a link that is not shared.
     (setcar x1 'baz)
          => baz
     x1                           ; Only one list is changed.
          => (baz foo c)
     x2
          => (z foo c)

   Here is a graphical depiction of the shared structure of the two
lists in the variables `x1' and `x2', showing why replacing `b' changes
them both:

             ___ ___        ___ ___      ___ ___
     x1---> |___|___|----> |___|___|--> |___|___|--> nil
              |        -->   |            |
              |       |      |            |
               --> a  |       --> b        --> c
                      |
            ___ ___   |
     x2--> |___|___|--
             |
             |
              --> z

   Here is an alternative form of box diagram, showing the same
relationship:

     x1:
      --------------       --------------       --------------
     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
     |   a   |   o------->|   b   |   o------->|   c   |  nil |
     |       |      |  -->|       |      |     |       |      |
      --------------  |    --------------       --------------
                      |
     x2:              |
      --------------  |
     | car   | cdr  | |
     |   z   |   o----
     |       |      |
      --------------

\1f
File: lispref.info,  Node: Setcdr,  Next: Rearrangement,  Prev: Setcar,  Up: Modifying Lists

Altering the CDR of a List
--------------------------

   The lowest-level primitive for modifying a CDR is `setcdr':

 - Function: setcdr CONS OBJECT
     This function stores OBJECT as the new CDR of CONS, replacing its
     previous CDR.  It returns the value OBJECT.

   Here is an example of replacing the CDR of a list with a different
list.  All but the first element of the list are removed in favor of a
different sequence of elements.  The first element is unchanged,
because it resides in the CAR of the list, and is not reached via the
CDR.

     (setq x '(1 2 3))
          => (1 2 3)
     (setcdr x '(4))
          => (4)
     x
          => (1 4)

   You can delete elements from the middle of a list by altering the
CDRs of the cons cells in the list.  For example, here we delete the
second element, `b', from the list `(a b c)', by changing the CDR of
the first cell:

     (setq x1 '(a b c))
          => (a b c)
     (setcdr x1 (cdr (cdr x1)))
          => (c)
     x1
          => (a c)

   Here is the result in box notation:

                        --------------------
                       |                    |
      --------------   |   --------------   |    --------------
     | car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
     |   a   |   o-----   |   b   |   o-------->|   c   |  nil |
     |       |      |     |       |      |      |       |      |
      --------------       --------------        --------------

The second cons cell, which previously held the element `b', still
exists and its CAR is still `b', but it no longer forms part of this
list.

   It is equally easy to insert a new element by changing CDRs:

     (setq x1 '(a b c))
          => (a b c)
     (setcdr x1 (cons 'd (cdr x1)))
          => (d b c)
     x1
          => (a d b c)

   Here is this result in box notation:

     --------------        -------------       -------------
     | car  | cdr   |      | car  | cdr  |     | car  | cdr  |
     |   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
     |      |   |   |  |   |      |      |     |      |      |
      --------- | --   |    -------------       -------------
                |      |
          -----         --------
         |                      |
         |    ---------------   |
         |   | car   | cdr   |  |
          -->|   d   |   o------
             |       |       |
              ---------------

\1f
File: lispref.info,  Node: Rearrangement,  Prev: Setcdr,  Up: Modifying Lists

Functions that Rearrange Lists
------------------------------

   Here are some functions that rearrange lists "destructively" by
modifying the CDRs of their component cons cells.  We call these
functions "destructive" because they chew up the original lists passed
to them as arguments, to produce a new list that is the returned value.

   See `delq', in *Note Sets And Lists::, for another function that
modifies cons cells.

 - Function: nconc &rest LISTS
     This function returns a list containing all the elements of LISTS.
     Unlike `append' (*note Building Lists::.), the LISTS are *not*
     copied.  Instead, the last CDR of each of the LISTS is changed to
     refer to the following list.  The last of the LISTS is not
     altered.  For example:

          (setq x '(1 2 3))
               => (1 2 3)
          (nconc x '(4 5))
               => (1 2 3 4 5)
          x
               => (1 2 3 4 5)

     Since the last argument of `nconc' is not itself modified, it is
     reasonable to use a constant list, such as `'(4 5)', as in the
     above example.  For the same reason, the last argument need not be
     a list:

          (setq x '(1 2 3))
               => (1 2 3)
          (nconc x 'z)
               => (1 2 3 . z)
          x
               => (1 2 3 . z)

     A common pitfall is to use a quoted constant list as a non-last
     argument to `nconc'.  If you do this, your program will change
     each time you run it!  Here is what happens:

          (defun add-foo (x)            ; We want this function to add
            (nconc '(foo) x))           ;   `foo' to the front of its arg.

          (symbol-function 'add-foo)
               => (lambda (x) (nconc (quote (foo)) x))

          (setq xx (add-foo '(1 2)))    ; It seems to work.
               => (foo 1 2)

          (setq xy (add-foo '(3 4)))    ; What happened?
               => (foo 1 2 3 4)

          (eq xx xy)
               => t

          (symbol-function 'add-foo)
               => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))

 - Function: nreverse LIST
     This function reverses the order of the elements of LIST.  Unlike
     `reverse', `nreverse' alters its argument by reversing the CDRs in
     the cons cells forming the list.  The cons cell that used to be
     the last one in LIST becomes the first cell of the value.

     For example:

          (setq x '(1 2 3 4))
               => (1 2 3 4)
          x
               => (1 2 3 4)
          (nreverse x)
               => (4 3 2 1)
          ;; The cell that was first is now last.
          x
               => (1)

     To avoid confusion, we usually store the result of `nreverse' back
     in the same variable which held the original list:

          (setq x (nreverse x))

     Here is the `nreverse' of our favorite example, `(a b c)',
     presented graphically:

          Original list head:                       Reversed list:
           -------------        -------------        ------------
          | car  | cdr  |      | car  | cdr  |      | car | cdr  |
          |   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
          |      |      |   |  |      |   |  |   |  |     |   |  |
           -------------    |   --------- | -    |   -------- | -
                            |             |      |            |
                             -------------        ------------

 - Function: sort LIST PREDICATE
     This function sorts LIST stably, though destructively, and returns
     the sorted list.  It compares elements using PREDICATE.  A stable
     sort is one in which elements with equal sort keys maintain their
     relative order before and after the sort.  Stability is important
     when successive sorts are used to order elements according to
     different criteria.

     The argument PREDICATE must be a function that accepts two
     arguments.  It is called with two elements of LIST.  To get an
     increasing order sort, the PREDICATE should return `t' if the
     first element is "less than" the second, or `nil' if not.

     The destructive aspect of `sort' is that it rearranges the cons
     cells forming LIST by changing CDRs.  A nondestructive sort
     function would create new cons cells to store the elements in their
     sorted order.  If you wish to make a sorted copy without
     destroying the original, copy it first with `copy-sequence' and
     then sort.

     Sorting does not change the CARs of the cons cells in LIST; the
     cons cell that originally contained the element `a' in LIST still
     has `a' in its CAR after sorting, but it now appears in a
     different position in the list due to the change of CDRs.  For
     example:

          (setq nums '(1 3 2 6 5 4 0))
               => (1 3 2 6 5 4 0)
          (sort nums '<)
               => (0 1 2 3 4 5 6)
          nums
               => (1 2 3 4 5 6)

     Note that the list in `nums' no longer contains 0; this is the same
     cons cell that it was before, but it is no longer the first one in
     the list.  Don't assume a variable that formerly held the argument
     now holds the entire sorted list!  Instead, save the result of
     `sort' and use that.  Most often we store the result back into the
     variable that held the original list:

          (setq nums (sort nums '<))

     *Note Sorting::, for more functions that perform sorting.  See
     `documentation' in *Note Accessing Documentation::, for a useful
     example of `sort'.

\1f
File: lispref.info,  Node: Sets And Lists,  Next: Association Lists,  Prev: Modifying Lists,  Up: Lists

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

   A list can represent an unordered mathematical set--simply consider a
value an element of a set if it appears in the list, and ignore the
order of the list.  To form the union of two sets, use `append' (as
long as you don't mind having duplicate elements).  Other useful
functions for sets include `memq' and `delq', and their `equal'
versions, `member' and `delete'.

     Common Lisp note: Common Lisp has functions `union' (which avoids
     duplicate elements) and `intersection' for set operations, but
     XEmacs Lisp does not have them.  You can write them in Lisp if you
     wish.

 - Function: memq OBJECT LIST
     This function tests to see whether OBJECT is a member of LIST.  If
     it is, `memq' returns a list starting with the first occurrence of
     OBJECT.  Otherwise, it returns `nil'.  The letter `q' in `memq'
     says that it uses `eq' to compare OBJECT against the elements of
     the list.  For example:

          (memq 'b '(a b c b a))
               => (b c b a)
          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
               => nil

 - Function: delq OBJECT LIST
     This function destructively removes all elements `eq' to OBJECT
     from LIST.  The letter `q' in `delq' says that it uses `eq' to
     compare OBJECT against the elements of the list, like `memq'.

   When `delq' deletes elements from the front of the list, it does so
simply by advancing down the list and returning a sublist that starts
after those elements:

     (delq 'a '(a b c)) == (cdr '(a b c))

   When an element to be deleted appears in the middle of the list,
removing it involves changing the CDRs (*note Setcdr::.).

     (setq sample-list '(a b c (4)))
          => (a b c (4))
     (delq 'a sample-list)
          => (b c (4))
     sample-list
          => (a b c (4))
     (delq 'c sample-list)
          => (a b (4))
     sample-list
          => (a b (4))

   Note that `(delq 'c sample-list)' modifies `sample-list' to splice
out the third element, but `(delq 'a sample-list)' does not splice
anything--it just returns a shorter list.  Don't assume that a variable
which formerly held the argument LIST now has fewer elements, or that
it still holds the original list!  Instead, save the result of `delq'
and use that.  Most often we store the result back into the variable
that held the original list:

     (setq flowers (delq 'rose flowers))

   In the following example, the `(4)' that `delq' attempts to match
and the `(4)' in the `sample-list' are not `eq':

     (delq '(4) sample-list)
          => (a c (4))

   The following two functions are like `memq' and `delq' but use
`equal' rather than `eq' to compare elements.  They are new in Emacs 19.

 - Function: member OBJECT LIST
     The function `member' tests to see whether OBJECT is a member of
     LIST, comparing members with OBJECT using `equal'.  If OBJECT is a
     member, `member' returns a list starting with its first occurrence
     in LIST.  Otherwise, it returns `nil'.

     Compare this with `memq':

          (member '(2) '((1) (2)))  ; `(2)' and `(2)' are `equal'.
               => ((2))
          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
               => nil
          ;; Two strings with the same contents are `equal'.
          (member "foo" '("foo" "bar"))
               => ("foo" "bar")

 - Function: delete OBJECT LIST
     This function destructively removes all elements `equal' to OBJECT
     from LIST.  It is to `delq' as `member' is to `memq': it uses
     `equal' to compare elements with OBJECT, like `member'; when it
     finds an element that matches, it removes the element just as
     `delq' would.  For example:

          (delete '(2) '((2) (1) (2)))
               => '((1))

     Common Lisp note: The functions `member' and `delete' in XEmacs
     Lisp are derived from Maclisp, not Common Lisp.  The Common Lisp
     versions do not use `equal' to compare elements.

   See also the function `add-to-list', in *Note Setting Variables::,
for another way to add an element to a list stored in a variable.

\1f
File: lispref.info,  Node: Association Lists,  Next: Property Lists,  Prev: Sets And Lists,  Up: Lists

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

   An "association list", or "alist" for short, records a mapping from
keys to values.  It is a list of cons cells called "associations": the
CAR of each cell is the "key", and the CDR is the "associated value".(1)

   Here is an example of an alist.  The key `pine' is associated with
the value `cones'; the key `oak' is associated with `acorns'; and the
key `maple' is associated with `seeds'.

     '((pine . cones)
       (oak . acorns)
       (maple . seeds))

   The associated values in an alist may be any Lisp objects; so may the
keys.  For example, in the following alist, the symbol `a' is
associated with the number `1', and the string `"b"' is associated with
the *list* `(2 3)', which is the CDR of the alist element:

     ((a . 1) ("b" 2 3))

   Sometimes it is better to design an alist to store the associated
value in the CAR of the CDR of the element.  Here is an example:

     '((rose red) (lily white) (buttercup yellow))

Here we regard `red' as the value associated with `rose'.  One
advantage of this method is that you can store other related
information--even a list of other items--in the CDR of the CDR.  One
disadvantage is that you cannot use `rassq' (see below) to find the
element containing a given value.  When neither of these considerations
is important, the choice is a matter of taste, as long as you are
consistent about it for any given alist.

   Note that the same alist shown above could be regarded as having the
associated value in the CDR of the element; the value associated with
`rose' would be the list `(red)'.

   Association lists are often used to record information that you might
otherwise keep on a stack, since new associations may be added easily to
the front of the list.  When searching an association list for an
association with a given key, the first one found is returned, if there
is more than one.

   In XEmacs Lisp, it is *not* an error if an element of an association
list is not a cons cell.  The alist search functions simply ignore such
elements.  Many other versions of Lisp signal errors in such cases.

   Note that property lists are similar to association lists in several
respects.  A property list behaves like an association list in which
each key can occur only once.  *Note Property Lists::, for a comparison
of property lists and association lists.

 - Function: assoc KEY ALIST
     This function returns the first association for KEY in ALIST.  It
     compares KEY against the alist elements using `equal' (*note
     Equality Predicates::.).  It returns `nil' if no association in
     ALIST has a CAR `equal' to KEY.  For example:

          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
               => ((pine . cones) (oak . acorns) (maple . seeds))
          (assoc 'oak trees)
               => (oak . acorns)
          (cdr (assoc 'oak trees))
               => acorns
          (assoc 'birch trees)
               => nil

     Here is another example, in which the keys and values are not
     symbols:

          (setq needles-per-cluster
                '((2 "Austrian Pine" "Red Pine")
                  (3 "Pitch Pine")
                  (5 "White Pine")))
          
          (cdr (assoc 3 needles-per-cluster))
               => ("Pitch Pine")
          (cdr (assoc 2 needles-per-cluster))
               => ("Austrian Pine" "Red Pine")

 - Function: rassoc VALUE ALIST
     This function returns the first association with value VALUE in
     ALIST.  It returns `nil' if no association in ALIST has a CDR
     `equal' to VALUE.

     `rassoc' is like `assoc' except that it compares the CDR of each
     ALIST association instead of the CAR.  You can think of this as
     "reverse `assoc'", finding the key for a given value.

 - Function: assq KEY ALIST
     This function is like `assoc' in that it returns the first
     association for KEY in ALIST, but it makes the comparison using
     `eq' instead of `equal'.  `assq' returns `nil' if no association
     in ALIST has a CAR `eq' to KEY.  This function is used more often
     than `assoc', since `eq' is faster than `equal' and most alists
     use symbols as keys.  *Note Equality Predicates::.

          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
               => ((pine . cones) (oak . acorns) (maple . seeds))
          (assq 'pine trees)
               => (pine . cones)

     On the other hand, `assq' is not usually useful in alists where the
     keys may not be symbols:

          (setq leaves
                '(("simple leaves" . oak)
                  ("compound leaves" . horsechestnut)))
          
          (assq "simple leaves" leaves)
               => nil
          (assoc "simple leaves" leaves)
               => ("simple leaves" . oak)

 - Function: rassq VALUE ALIST
     This function returns the first association with value VALUE in
     ALIST.  It returns `nil' if no association in ALIST has a CDR `eq'
     to VALUE.

     `rassq' is like `assq' except that it compares the CDR of each
     ALIST association instead of the CAR.  You can think of this as
     "reverse `assq'", finding the key for a given value.

     For example:

          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
          
          (rassq 'acorns trees)
               => (oak . acorns)
          (rassq 'spores trees)
               => nil

     Note that `rassq' cannot search for a value stored in the CAR of
     the CDR of an element:

          (setq colors '((rose red) (lily white) (buttercup yellow)))
          
          (rassq 'white colors)
               => nil

     In this case, the CDR of the association `(lily white)' is not the
     symbol `white', but rather the list `(white)'.  This becomes
     clearer if the association is written in dotted pair notation:

          (lily white) == (lily . (white))

 - Function: remassoc KEY ALIST
     This function deletes by side effect any associations with key KEY
     in ALIST - i.e. it removes any elements from ALIST whose `car' is
     `equal' to KEY.  The modified ALIST is returned.

     If the first member of ALIST has a `car' that is `equal' to KEY,
     there is no way to remove it by side effect; therefore, write
     `(setq foo (remassoc key foo))' to be sure of changing the value
     of `foo'.

 - Function: remassq KEY ALIST
     This function deletes by side effect any associations with key KEY
     in ALIST - i.e. it removes any elements from ALIST whose `car' is
     `eq' to KEY.  The modified ALIST is returned.

     This function is exactly like `remassoc', but comparisons between
     KEY and keys in ALIST are done using `eq' instead of `equal'.

 - Function: remrassoc VALUE ALIST
     This function deletes by side effect any associations with value
     VALUE in ALIST - i.e. it removes any elements from ALIST whose
     `cdr' is `equal' to VALUE.  The modified ALIST is returned.

     If the first member of ALIST has a `car' that is `equal' to VALUE,
     there is no way to remove it by side effect; therefore, write
     `(setq foo (remassoc value foo))' to be sure of changing the value
     of `foo'.

     `remrassoc' is like `remassoc' except that it compares the CDR of
     each ALIST association instead of the CAR.  You can think of this
     as "reverse `remassoc'", removing an association based on its
     value instead of its key.

 - Function: remrassq VALUE ALIST
     This function deletes by side effect any associations with value
     VALUE in ALIST - i.e. it removes any elements from ALIST whose
     `cdr' is `eq' to VALUE.  The modified ALIST is returned.

     This function is exactly like `remrassoc', but comparisons between
     VALUE and values in ALIST are done using `eq' instead of `equal'.

 - Function: copy-alist ALIST
     This function returns a two-level deep copy of ALIST: it creates a
     new copy of each association, so that you can alter the
     associations of the new alist without changing the old one.

          (setq needles-per-cluster
                '((2 . ("Austrian Pine" "Red Pine"))
                  (3 . ("Pitch Pine"))
                  (5 . ("White Pine"))))
          =>
          ((2 "Austrian Pine" "Red Pine")
           (3 "Pitch Pine")
           (5 "White Pine"))
          
          (setq copy (copy-alist needles-per-cluster))
          =>
          ((2 "Austrian Pine" "Red Pine")
           (3 "Pitch Pine")
           (5 "White Pine"))
          
          (eq needles-per-cluster copy)
               => nil
          (equal needles-per-cluster copy)
               => t
          (eq (car needles-per-cluster) (car copy))
               => nil
          (cdr (car (cdr needles-per-cluster)))
               => ("Pitch Pine")
          (eq (cdr (car (cdr needles-per-cluster)))
              (cdr (car (cdr copy))))
               => t

     This example shows how `copy-alist' makes it possible to change
     the associations of one copy without affecting the other:

          (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
          (cdr (assq 3 needles-per-cluster))
               => ("Pitch Pine")

   ---------- Footnotes ----------

   (1) This usage of "key" is not related to the term "key sequence";
it means a value used to look up an item in a table.  In this case, the
table is the alist, and the alist associations are the items.

\1f
File: lispref.info,  Node: Property Lists,  Next: Weak Lists,  Prev: Association Lists,  Up: Lists

Property Lists
==============

   A "property list" (or "plist") is another way of representing a
mapping from keys to values.  Instead of the list consisting of conses
of a key and a value, the keys and values alternate as successive
entries in the list.  Thus, the association list

     ((a . 1) (b . 2) (c . 3))

   has the equivalent property list form

     (a 1 b 2 c 3)

   Property lists are used to represent the properties associated with
various sorts of objects, such as symbols, strings, frames, etc.  The
convention is that property lists can be modified in-place, while
association lists generally are not.

   Plists come in two varieties: "normal" plists, whose keys are
compared with `eq', and "lax" plists, whose keys are compared with
`equal',

 - Function: valid-plist-p PLIST
     Given a plist, this function returns non-`nil' if its format is
     correct.  If it returns `nil', `check-valid-plist' will signal an
     error when given the plist; that means it's a malformed or circular
     plist or has non-symbols as keywords.

 - Function: check-valid-plist PLIST
     Given a plist, this function signals an error if there is anything
     wrong with it.  This means that it's a malformed or circular plist.

* Menu:

* Working With Normal Plists::       Functions for normal plists.
* Working With Lax Plists::          Functions for lax plists.
* Converting Plists To/From Alists:: Alist to plist and vice-versa.

\1f
File: lispref.info,  Node: Working With Normal Plists,  Next: Working With Lax Plists,  Up: Property Lists

Working With Normal Plists
--------------------------

 - Function: plist-get PLIST PROP &optional DEFAULT
     This function extracts a value from a property list.  The function
     returns the value corresponding to the given PROP, or DEFAULT if
     PROP is not one of the properties on the list.

 - Function: plist-put PLIST PROP VAL
     This function changes the value in PLIST of PROP to VAL.  If PROP
     is already a property on the list, its value is set to VAL,
     otherwise the new PROP VAL pair is added.  The new plist is
     returned; use `(setq x (plist-put x prop val))' to be sure to use
     the new value.  The PLIST is modified by side effects.

 - Function: plist-remprop PLIST PROP
     This function removes from PLIST the property PROP and its value.
     The new plist is returned; use `(setq x (plist-remprop x prop
     val))' to be sure to use the new value.  The PLIST is modified by
     side effects.

 - Function: plist-member PLIST PROP
     This function returns `t' if PROP has a value specified in PLIST.

   In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
non-`nil', then a property with a `nil' value is ignored or removed.
This feature is a virus that has infected old Lisp implementations (and
thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
used except for backward compatibility.

 - Function: plists-eq A B &optional NIL-MEANS-NOT-PRESENT
     This function returns non-`nil' if property lists A and B are `eq'
     (i.e. their values are `eq').

 - Function: plists-equal A B &optional NIL-MEANS-NOT-PRESENT
     This function returns non-`nil' if property lists A and B are
     `equal' (i.e. their values are `equal'; their keys are still
     compared using `eq').

 - Function: canonicalize-plist PLIST &optional NIL-MEANS-NOT-PRESENT
     This function destructively removes any duplicate entries from a
     plist.  In such cases, the first entry applies.

     The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
     return value may not be `eq' to the passed-in value, so make sure
     to `setq' the value back into where it came from.

\1f
File: lispref.info,  Node: Working With Lax Plists,  Next: Converting Plists To/From Alists,  Prev: Working With Normal Plists,  Up: Property Lists

Working With Lax Plists
-----------------------

   Recall that a "lax plist" is a property list whose keys are compared
using `equal' instead of `eq'.

 - Function: lax-plist-get LAX-PLIST PROP &optional DEFAULT
     This function extracts a value from a lax property list.  The
     function returns the value corresponding to the given PROP, or
     DEFAULT if PROP is not one of the properties on the list.

 - Function: lax-plist-put LAX-PLIST PROP VAL
     This function changes the value in LAX-PLIST of PROP to VAL.

 - Function: lax-plist-remprop LAX-PLIST PROP
     This function removes from LAX-PLIST the property PROP and its
     value.  The new plist is returned; use `(setq x (lax-plist-remprop
     x prop val))' to be sure to use the new value.  The LAX-PLIST is
     modified by side effects.

 - Function: lax-plist-member LAX-PLIST PROP
     This function returns `t' if PROP has a value specified in
     LAX-PLIST.

   In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
non-`nil', then a property with a `nil' value is ignored or removed.
This feature is a virus that has infected old Lisp implementations (and
thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
used except for backward compatibility.

 - Function: lax-plists-eq A B &optional NIL-MEANS-NOT-PRESENT
     This function returns non-`nil' if lax property lists A and B are
     `eq' (i.e. their values are `eq'; their keys are still compared
     using `equal').

 - Function: lax-plists-equal A B &optional NIL-MEANS-NOT-PRESENT
     This function returns non-`nil' if lax property lists A and B are
     `equal' (i.e. their values are `equal').

 - Function: canonicalize-lax-plist LAX-PLIST &optional
          NIL-MEANS-NOT-PRESENT
     This function destructively removes any duplicate entries from a
     lax plist.  In such cases, the first entry applies.

     The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
     return value may not be `eq' to the passed-in value, so make sure
     to `setq' the value back into where it came from.

\1f
File: lispref.info,  Node: Converting Plists To/From Alists,  Prev: Working With Lax Plists,  Up: Property Lists

Converting Plists To/From Alists
--------------------------------

 - Function: alist-to-plist ALIST
     This function converts association list ALIST into the equivalent
     property-list form.  The plist is returned.  This converts from

          ((a . 1) (b . 2) (c . 3))

     into

          (a 1 b 2 c 3)

     The original alist is not modified.

 - Function: plist-to-alist PLIST
     This function converts property list PLIST into the equivalent
     association-list form.  The alist is returned.  This converts from

          (a 1 b 2 c 3)

     into

          ((a . 1) (b . 2) (c . 3))

     The original plist is not modified.

   The following two functions are equivalent to the preceding two
except that they destructively modify their arguments, using cons cells
from the original list to form the new list rather than allocating new
cons cells.

 - Function: destructive-alist-to-plist ALIST
     This function destructively converts association list ALIST into
     the equivalent property-list form.  The plist is returned.

 - Function: destructive-plist-to-alist PLIST
     This function destructively converts property list PLIST into the
     equivalent association-list form.  The alist is returned.

\1f
File: lispref.info,  Node: Weak Lists,  Prev: Property Lists,  Up: Lists

Weak Lists
==========

   A "weak list" is a special sort of list whose members are not counted
as references for the purpose of garbage collection.  This means that,
for any object in the list, if there are no references to the object
anywhere outside of the list (or other weak list or weak hash table),
that object will disappear the next time a garbage collection happens.
Weak lists can be useful for keeping track of things such as unobtrusive
lists of another function's buffers or markers.  When that function is
done with the elements, they will automatically disappear from the list.

   Weak lists are used internally, for example, to manage the list
holding the children of an extent - an extent that is unused but has a
parent will still be reclaimed, and will automatically be removed from
its parent's list of children.

   Weak lists are similar to weak hash tables (*note Weak Hash
Tables::.).

 - Function: weak-list-p OBJECT
     This function returns non-`nil' if OBJECT is a weak list.

   Weak lists come in one of four types:

`simple'
     Objects in the list disappear if not referenced outside of the
     list.

`assoc'
     Objects in the list disappear if they are conses and either the
     car or the cdr of the cons is not referenced outside of the list.

`key-assoc'
     Objects in the list disappear if they are conses and the car is not
     referenced outside of the list.

`value-assoc'
     Objects in the list disappear if they are conses and the cdr is not
     referenced outside of the list.

 - Function: make-weak-list &optional TYPE
     This function creates a new weak list of type TYPE.  TYPE is a
     symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
     as described above) and defaults to `simple'.

 - Function: weak-list-type WEAK
     This function returns the type of the given weak-list object.

 - Function: weak-list-list WEAK
     This function returns the list contained in a weak-list object.

 - Function: set-weak-list-list WEAK NEW-LIST
     This function changes the list contained in a weak-list object.

\1f
File: lispref.info,  Node: Sequences Arrays Vectors,  Next: Symbols,  Prev: Lists,  Up: Top

Sequences, Arrays, and Vectors
******************************

   Recall that the "sequence" type is the union of four other Lisp
types: lists, vectors, bit vectors, and strings.  In other words, any
list is a sequence, any vector is a sequence, any bit vector is a
sequence, and any string is a sequence.  The common property that all
sequences have is that each is an ordered collection of elements.

   An "array" is a single primitive object that has a slot for each
elements.  All the elements are accessible in constant time, but the
length of an existing array cannot be changed.  Strings, vectors, and
bit vectors are the three types of arrays.

   A list is a sequence of elements, but it is not a single primitive
object; it is made of cons cells, one cell per element.  Finding the
Nth element requires looking through N cons cells, so elements farther
from the beginning of the list take longer to access.  But it is
possible to add elements to the list, or remove elements.

   The following diagram shows the relationship between these types:

               ___________________________________
              |                                   |
              |          Sequence                 |
              |  ______   ______________________  |
              | |      | |                      | |
              | | List | |         Array        | |
              | |      | |  ________   _______  | |
              | |______| | |        | |       | | |
              |          | | Vector | | String| | |
              |          | |________| |_______| | |
              |          |  __________________  | |
              |          | |                  | | |
              |          | |    Bit Vector    | | |
              |          | |__________________| | |
              |          |______________________| |
              |___________________________________|

   The elements of vectors and lists may be any Lisp objects.  The
elements of strings are all characters.  The elements of bit vectors
are the numbers 0 and 1.

* Menu:

* Sequence Functions::    Functions that accept any kind of sequence.
* Arrays::                Characteristics of arrays in XEmacs Lisp.
* Array Functions::       Functions specifically for arrays.
* Vectors::               Special characteristics of XEmacs Lisp vectors.
* Vector Functions::      Functions specifically for vectors.
* Bit Vectors::           Special characteristics of XEmacs Lisp bit vectors.
* Bit Vector Functions::  Functions specifically for bit vectors.