(lispref.info)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

          (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)
               => 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, 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)
               => (pine oak)
               => (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

          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.

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

     This once was the standard 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

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

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

               => 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' (Note: Formatting Strings.)
     or `number-to-string' (Note: 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 Note: 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*

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

automatically generated by info2www