comparison lispref/lists.texi @ 22253:ed6b191416cf

*** empty log message ***

22252:40089afa2b1d

@cindex lists and cons cells
@cindex @code{nil} and lists

  Lists in Lisp are not a primitive data type; they are built up from
@dfn{cons cells}.  A cons cell is a data object that represents an
ordered pair.  It records two Lisp objects, one labeled as the @sc{car},
and the other labeled as the @sc{cdr}.  These names are traditional; see
@ref{Cons Cell Type}.  @sc{cdr} is pronounced ``could-er.''

  A list is a series of cons cells chained together, one cons cell per
element of the list.  By convention, the @sc{car}s of the cons cells are
the elements of the list, and the @sc{cdr}s are used to chain the list:
the @sc{cdr} of each cons cell is the following cons cell.  The @sc{cdr}

@end group
@end example

  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 @sc{car} of the first cons
cell, contains the symbol @code{tulip}.  The arrow from the @sc{cdr} of
the first cons cell to the second cons cell indicates that the @sc{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:

@example

used on a list, @code{setcar} replaces one element of a list with a
different element.

@defun setcar cons object
This function stores @var{object} as the new @sc{car} of @var{cons},
replacing its previous @sc{car}.  It returns the value @var{object}.
For example:

@example
@group
(setq x '(1 2))
     @result{} (1 2)

  The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:

@defun setcdr cons object
This function stores @var{object} as the new @sc{cdr} of @var{cons},
replacing its previous @sc{cdr}.  It returns the value @var{object}.
@end defun

  Here is an example of replacing the @sc{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

@end example

  You can delete elements from the middle of a list by altering the
@sc{cdr}s of the cons cells in the list.  For example, here we delete
the second element, @code{b}, from the list @code{(a b c)}, by changing
the @sc{cdr} of the first cell:

@example
@group
(setq x1 '(a b c))
     @result{} (a b c)

@defun nreverse list
@cindex reversing a list
  This function reverses the order of the elements of @var{list}.
Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
the @sc{cdr}s in the cons cells forming the list.  The cons cell that
used to be the last one in @var{list} becomes the first cell of the
value.

  For example:

@example

     @result{} (1 2 3 4)
(nreverse x)
     @result{} (4 3 2 1)
@end group
@group
;; @r{The cell that was first is now last.}
x
     @result{} (1)
@end group
@end example

@cindex association list
@cindex alist

  An @dfn{association list}, or @dfn{alist} for short, records a mapping
from keys to values.  It is a list of cons cells called
@dfn{associations}: the @sc{car} of each cell is the @dfn{key}, and the
@sc{cdr} is the @dfn{associated value}.@footnote{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.}

22253:ed6b191416cf

@cindex lists and cons cells
@cindex @code{nil} and lists

  Lists in Lisp are not a primitive data type; they are built up from
@dfn{cons cells}.  A cons cell is a data object that represents an
ordered pair.  It holds, or ``points to,'' two Lisp objects, one labeled
as the @sc{car}, and the other labeled as the @sc{cdr}.  These names are
traditional; see @ref{Cons Cell Type}.  @sc{cdr} is pronounced
``could-er.''

  A list is a series of cons cells chained together, one cons cell per
element of the list.  By convention, the @sc{car}s of the cons cells are
the elements of the list, and the @sc{cdr}s are used to chain the list:
the @sc{cdr} of each cons cell is the following cons cell.  The @sc{cdr}

@end group
@end example

  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 describes the @sc{car} of the first
cons cell, contains the symbol @code{tulip}.  The arrow from the
@sc{cdr} box of the first cons cell to the second cons cell indicates
that the @sc{cdr} of the first cons cell is the second cons cell.

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

@example

used on a list, @code{setcar} replaces one element of a list with a
different element.

@defun setcar cons object
This function stores @var{object} as the new @sc{car} of @var{cons},
replacing its previous @sc{car}.  In other words, it changes the
@sc{car} slot of @var{cons} to point to @var{object}.  It returns the
value @var{object}.  For example:

@example
@group
(setq x '(1 2))
     @result{} (1 2)

  The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:

@defun setcdr cons object
This function stores @var{object} as the new @sc{cdr} of @var{cons},
replacing its previous @sc{cdr}.  In other words, it changes the
@sc{cdr} slot of @var{cons} to point to @var{object}.  It returns the
value @var{object}.
@end defun

  Here is an example of replacing the @sc{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

@end example

  You can delete elements from the middle of a list by altering the
@sc{cdr}s of the cons cells in the list.  For example, here we delete
the second element, @code{b}, from the list @code{(a b c)}, by changing
the @sc{cdr} of the first cons cell:

@example
@group
(setq x1 '(a b c))
     @result{} (a b c)

@defun nreverse list
@cindex reversing a list
  This function reverses the order of the elements of @var{list}.
Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
the @sc{cdr}s in the cons cells forming the list.  The cons cell that
used to be the last one in @var{list} becomes the first cons cell of the
value.

  For example:

@example

     @result{} (1 2 3 4)
(nreverse x)
     @result{} (4 3 2 1)
@end group
@group
;; @r{The cons cell that was first is now last.}
x
     @result{} (1)
@end group
@end example

@cindex association list
@cindex alist

  An @dfn{association list}, or @dfn{alist} for short, records a mapping
from keys to values.  It is a list of cons cells called
@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the
@sc{cdr} is the @dfn{associated value}.@footnote{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.}