   This version is newer than the second printed edition of the GNU
Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.

   Published by the Free Software Foundation 675 Massachusetts Avenue
Cambridge, MA 02139 USA

   Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.

   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.

The Case Table
==============

   You can customize case conversion by installing a special "case
table".  A case table specifies the mapping between upper case and lower
case letters.  It affects both the string and character case conversion
functions (see the previous section) and those that apply to text in the
buffer (see Case Changes.).  Use case table if you are using a
language which has letters that are not the standard ASCII letters.

   A case table is a list of this form:

     (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)

where each element is either `nil' or a string of length 256.  The
element DOWNCASE says how to map each character to its lower-case
equivalent.  The element UPCASE maps each character to its upper-case
equivalent.  If lower and upper case characters are in one-to-one
correspondence, use `nil' for UPCASE; then Emacs deduces the upcase
table from DOWNCASE.

   For some languages, upper and lower case letters are not in
one-to-one correspondence.  There may be two different lower case
letters with the same upper case equivalent.  In these cases, you need
to specify the maps for both directions.

   The element CANONICALIZE maps each character to a canonical
equivalent; any two characters that are related by case-conversion have
the same canonical equivalent character.

   The element EQUIVALENCES is a map that cyclicly permutes each
equivalence class (of characters with the same canonical equivalent).
(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
likewise for each set of equivalent characters.)

   You can provide `nil' for both CANONICALIZE and EQUIVALENCES, in
which case both are deduced from DOWNCASE and UPCASE.  Normally, that's
what you should do, when you construct a case table.  Alternatively,
you can provide suitable strings for both CANONICALIZE and
EQUIVALENCES.  When you look at the case table that's in use, you will
find non-`nil' values for those components.  Do not try to make just
one of these components `nil'; that is not meaningful.

   Each buffer has a case table.  Emacs also has a "standard case
table" which is copied into each buffer when you create the buffer.
(Changing the standard case table doesn't affect any existing buffers.)

   Here are the functions for working with case tables:

 - Function: case-table-p OBJECT
     This predicate returns non-`nil' if OBJECT is a valid case table.

 - Function: set-standard-case-table TABLE
     This function makes TABLE the standard case table, so that it will
     apply to any buffers created subsequently.

 - Function: standard-case-table
     This returns the standard case table.

 - Function: current-case-table
     This function returns the current buffer's case table.

 - Function: set-case-table TABLE
     This sets the current buffer's case table to TABLE.

   The following three functions are convenient subroutines for packages
that define non-ASCII character sets.  They modify a string
DOWNCASE-TABLE provided as an argument; this should be a string to be
used as the DOWNCASE part of a case table.  They also modify two syntax
tables, the standard syntax table and the Text mode syntax table.
(see Syntax Tables.)

 - Function: set-case-syntax-pair UC LC DOWNCASE-TABLE
     This function specifies a pair of corresponding letters, one upper
     case and one lower case.

 - Function: set-case-syntax-delims L R DOWNCASE-TABLE
     This function makes characters L and R a matching pair of
     case-invariant delimiters.

 - Function: set-case-syntax CHAR SYNTAX DOWNCASE-TABLE
     This function makes CHAR case-invariant, with syntax SYNTAX.

 - Command: describe-buffer-case-table
     This command displays a description of the contents of the current
     buffer's case table.

   You can load the library `iso-syntax' to set up the syntax and case
table for the 256 bit ISO Latin 1 character set.

Lists
*****

   A "list" represents a sequence of zero or more elements (which may
be any Lisp objects).  The important difference between lists and
vectors is that two or more lists can share part of their structure; in
addition, you can insert or delete elements in a list without copying
the whole list.

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

   Lists in Lisp are not a primitive data type; they are built up from
"cons cells".  A cons cell is a data object which represents an ordered
pair.  It records two Lisp objects, one labeled as the CAR, and the
other labeled as the CDR.  (These names are traditional.)

   A list is made by chaining cons cells together, one cons cell per
element.  By convention, the CARs of the cons cells are the elements of
the list, and the CDRs are used to chain the list: the CDR of each cons
cell is the following cons cell.  The CDR of the last cons cell is
`nil'.  This asymmetry between the CAR and the CDR is entirely a matter
of convention; at the level of cons cells, the CAR and CDR slots have
the same characteristics.

   The symbol `nil' is considered a list as well as a symbol; it is the
list with no elements.  For convenience, the symbol `nil' is considered
to have `nil' as its CDR (and also as its CAR).

   The CDR of any nonempty list L is a list containing all the elements
of L except the first.

Lists as Linked Pairs of Boxes
==============================

   A cons cell can be illustrated as a pair of boxes.  The first box
represents the CAR and the second box represents the CDR.  Here is an
illustration of the two-element list, `(tulip lily)', made from two
cons cells:

      ---------------         ---------------
     | car   | cdr   |       | car   | cdr   |
     | tulip |   o---------->| lily  |  nil  |
     |       |       |       |       |       |
      ---------------         ---------------

   Each pair of boxes represents a cons cell.  Each box "refers to",
"points to" or "contains" a Lisp object.  (These terms are synonymous.)
The first box, which is the CAR of the first cons cell, contains the
symbol `tulip'.  The arrow from the CDR of the first cons cell to the
second cons cell indicates that the CDR of the first cons cell points
to the second cons cell.

   The same list can be illustrated in a different sort of box notation
like this:

         ___ ___      ___ ___
        |___|___|--> |___|___|--> nil
          |            |
          |            |
           --> tulip    --> lily

   Here is a more complex illustration, this time of the three-element
list, `((pine needles) oak maple)', the first element of which is a
two-element list:

         ___ ___      ___ ___      ___ ___
        |___|___|--> |___|___|--> |___|___|--> nil
          |            |            |
          |            |            |
          |             --> oak      --> maple
          |
          |     ___ ___      ___ ___
           --> |___|___|--> |___|___|--> nil
                 |            |
                 |            |
                  --> pine     --> needles

   The same list is represented in the first box notation like this:

      --------------       --------------       --------------
     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
     |   o   |   o------->| oak   |   o------->| maple |  nil |
     |   |   |      |     |       |      |     |       |      |
      -- | ---------       --------------       --------------
         |
         |
         |        --------------       ----------------
         |       | car   | cdr  |     | car     | cdr  |
          ------>| pine  |   o------->| needles |  nil |
                 |       |      |     |         |      |
                  --------------       ----------------

   See List Type, for the read and print syntax of lists, and for
more "box and arrow" illustrations of lists.

Predicates on Lists
===================

   The following predicates test whether a Lisp object is an atom, is a
cons cell or is a list, or whether it is the distinguished object `nil'.
(Many of these tests can be defined in terms of the others, but they are
used so often that it is worth having all of them.)

 - Function: consp OBJECT
     This function returns `t' if OBJECT is a cons cell, `nil'
     otherwise.  `nil' is not a cons cell, although it *is* a list.

 - Function: atom OBJECT
     This function returns `t' if OBJECT is an atom, `nil' otherwise.
     All objects except cons cells are atoms.  The symbol `nil' is an
     atom and is also a list; it is the only Lisp object which is both.

          (atom OBJECT) == (not (consp OBJECT))

 - Function: listp OBJECT
     This function returns `t' if OBJECT is a cons cell or `nil'.
     Otherwise, it returns `nil'.

          (listp '(1))
               => t
          (listp '())
               => t

 - Function: nlistp OBJECT
     This function is the opposite of `listp': it returns `t' if OBJECT
     is not a list.  Otherwise, it returns `nil'.

          (listp OBJECT) == (not (nlistp OBJECT))

 - Function: null OBJECT
     This function returns `t' if OBJECT is `nil', and returns `nil'
     otherwise.  This function is identical to `not', but as a matter
     of clarity we use `null' when OBJECT is considered a list and
     `not' when it is considered a truth value (see `not' in
     Combining Conditions).

          (null '(1))
               => nil
          (null '())
               => t

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 less than zero, then the first element is returned.

          (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 less than or equal to zero, then all of LIST is returned.
     If the length of LIST is N or less, the value is `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)

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 functions.

 - 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' (see 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, strings, or
     integers.  All arguments except the last one are copied, so none
     of them are altered.

     The final argument to `append' may be any object but it is
     typically a list.  The final argument is not copied or converted;
     it becomes part of the structure of the new list.

     Here is an example:

          (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 what happens 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 standard way to copy a list, before the function
     `copy-sequence' was invented.  See 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

     In the special case where one of the SEQUENCES is an integer (not
     a sequence of integers), it is first converted to a string of
     digits making up the decimal print representation of the integer.
     This special case exists for compatibility with Mocklisp, and we
     don't recommend you take advantage of it.  If you want to convert
     an integer in this way, use `format' (see Formatting Strings.)
     or `number-to-string' (see String Conversion.).

          (setq trees '(pine oak))
               => (pine oak)
          (char-to-string 54)
               => "6"
          (setq longer-list (append trees 6 '(spruce)))
               => (pine oak 54 spruce)
          (setq x-list (append trees 6 6))
               => (pine oak 54 . 6)

     See `nconc' in Rearrangement, for another way to join lists
     without copying.

 - 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)

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.

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

   Changing the CAR of a cons cell is done with `setcar' and 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 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----
     |       |      |
      --------------

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

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

 - Function: setcdr CONS OBJECT
     This function stores OBJECT into the cdr of CONS.  The value
     returned is OBJECT, not CONS.

   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------
             |       |       |
              ---------------

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 the original lists passed as arguments
to them are chewed up to produce a new list that is subsequently
returned.

 - Function: nconc &rest LISTS
     This function returns a list containing all the elements of LISTS.
     Unlike `append' (see 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 is done 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)            ; This function should 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 destructively by
     reversing the CDRs in the cons cells forming the list.  The cons
     cell which 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 sort a list without destroying the
     original, copy it first with `copy-sequence'.

     The CARs of the cons cells are not changed; 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 '<))

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

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

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 GNU
     Emacs 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 2 '(1 2 3 2 1))
               => (2 3 2 1)
          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
               => nil

 - Function: delq OBJECT LIST
     This function 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 (see Setcdr.).

     (setq sample-list '(1 2 3 (4)))
          => (1 2 3 (4))
     (delq 1 sample-list)
          => (2 3 (4))
     sample-list
          => (1 2 3 (4))
     (delq 2 sample-list)
          => (1 3 (4))
     sample-list
          => (1 3 (4))

   Note that `(delq 2 sample-list)' modifies `sample-list' to splice
out the second element, but `(delq 1 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)
          => (1 3 (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 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 GNU Emacs
     Lisp are derived from Maclisp, not Common Lisp.  The Common Lisp
     versions do not use `equal' to compare elements.

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".
(This usage of "key" is not related to the term "key sequence"; it
means any object which can be looked up in a table.)

   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 Emacs 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.  See 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' (see
     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: 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.  See Equality Predicates.

          (setq trees '((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 the CDR of the ALIST
     associations is tested 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 be used to 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 can be seen
     more clearly if the association is written in dotted pair notation:

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

 - 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

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

   Recall that the "sequence" type is the union of three other Lisp
types: lists, vectors, and strings.  In other words, any list is a
sequence, any 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 directly containing all its
elements.  Therefore, all the elements are accessible in constant time.
The length of an existing array cannot be changed.  Both strings and
vectors are 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.  Therefore, 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 elements of vectors and lists may be any Lisp
objects.  The elements of strings are all characters.

   The following diagram shows the relationship between these types:

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

          The Relationship between Sequences, Arrays, and Vectors

Sequences
=========

   In Emacs Lisp, a "sequence" is either a list, a vector or a string.
The common property that all sequences have is that each is an ordered
collection of elements.  This section describes functions that accept
any kind of sequence.

 - Function: sequencep OBJECT
     Returns `t' if OBJECT is a list, vector, or string, `nil'
     otherwise.

 - Function: copy-sequence SEQUENCE
     Returns a copy of SEQUENCE.  The copy is the same type of object
     as the original sequence, and it has the same elements in the same
     order.

     Storing a new element into the copy does not affect the original
     SEQUENCE, and vice versa.  However, the elements of the new
     sequence are not copies; they are identical (`eq') to the elements
     of the original.  Therefore, changes made within these elements, as
     found via the copied sequence, are also visible in the original
     sequence.

     If the sequence is a string with text properties, the property
     list in the copy is itself a copy, not shared with the original's
     property list.  However, the actual values of the properties are
     shared.  See Text Properties.

     See also `append' in Building Lists, `concat' in
     Creating Strings, and `vconcat' in Vectors, for others
     ways to copy sequences.

          (setq bar '(1 2))
               => (1 2)
          (setq x (vector 'foo bar))
               => [foo (1 2)]
          (setq y (copy-sequence x))
               => [foo (1 2)]

          (eq x y)
               => nil
          (equal x y)
               => t
          (eq (elt x 1) (elt y 1))
               => t

          ;; Replacing an element of one sequence.
          (aset x 0 'quux)
          x => [quux (1 2)]
          y => [foo (1 2)]

          ;; Modifying the inside of a shared element.
          (setcar (aref x 1) 69)
          x => [quux (69 2)]
          y => [foo (69 2)]

 - Function: length SEQUENCE
     Returns the number of elements in SEQUENCE.  If SEQUENCE is a cons
     cell that is not a list (because the final CDR is not `nil'), a
     `wrong-type-argument' error is signaled.

          (length '(1 2 3))
              => 3
          (length ())
              => 0
          (length "foobar")
              => 6
          (length [1 2 3])
              => 3

 - Function: elt SEQUENCE INDEX
     This function returns the element of SEQUENCE indexed by INDEX.
     Legitimate values of INDEX are integers ranging from 0 up to one
     less than the length of SEQUENCE.  If SEQUENCE is a list, then
     out-of-range values of index return `nil'; otherwise, they produce
     an `args-out-of-range' error.

          (elt [1 2 3 4] 2)
               => 3
          (elt '(1 2 3 4) 2)
               => 3
          (char-to-string (elt "1234" 2))
               => "3"
          (elt [1 2 3 4] 4)
               error-->Args out of range: [1 2 3 4], 4
          (elt [1 2 3 4] -1)
               error-->Args out of range: [1 2 3 4], -1

     This function duplicates `aref' (see Array Functions.) and
     `nth' (see List Elements.), except that it works for any kind
     of sequence.

Arrays
======

   An "array" object refers directly to a number of other Lisp objects,
called the elements of the array.  Any element of an array may be
accessed in constant time.  In contrast, an element of a list requires
access time that is proportional to the position of the element in the
list.

   When you create an array, you must specify how many elements it has.
The amount of space allocated depends on the number of elements.
Therefore, it is impossible to change the size of an array once it is
created.  You cannot add or remove elements.  However, you can replace
an element with a different value.

   Emacs defines two types of array, both of which are one-dimensional:
"strings" and "vectors".  A vector is a general array; its elements can
be any Lisp objects.  A string is a specialized array; its elements
must be characters (i.e., integers between 0 and 255).  Each type of
array has its own read syntax.  See String Type, and Vector Type.

   Both kinds of arrays share these characteristics:

   * The first element of an array has index zero, the second element
     has index 1, and so on.  This is called "zero-origin" indexing.
     For example, an array of four elements has indices 0, 1, 2, and 3.

   * The elements of an array may be referenced or changed with the
     functions `aref' and `aset', respectively (see Array Functions.).

   In principle, if you wish to have an array of characters, you could
use either a string or a vector.  In practice, we always choose strings
for such applications, for four reasons:

   * They occupy one-fourth the space of a vector of the same elements.

   * Strings are printed in a way that shows the contents more clearly
     as characters.

   * Strings can hold text properties.  See Text Properties.

   * Many of the specialized editing and I/O facilities of Emacs accept
     only strings.  For example, you cannot insert a vector of
     characters into a buffer the way you can insert a string.  See
     Strings and Characters.