@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/lists
@node Lists, Sequences Arrays Vectors, Strings and Characters, Top
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 ``refers 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}
-of the last cons cell is @code{nil}. This asymmetry between the
-@sc{car} and the @sc{cdr} is entirely a matter of convention; at the
+ordered pair. That is, it has two slots, and each slot @dfn{holds}, or
+@dfn{refers to}, some Lisp object. One slot is known as the @sc{car},
+and the other is known as the @sc{cdr}. (These names are traditional;
+see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.''
+
+ We say that ``the @sc{car} of this cons cell is'' whatever object
+its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
+
+ A list is a series of cons cells ``chained together,'' so that each
+cell refers to the next one. There is one cons cell for each element of
+the list. By convention, the @sc{car}s of the cons cells hold the
+elements of the list, and the @sc{cdr}s are used to chain the list: the
+@sc{cdr} slot of each cons cell refers to the following cons cell. The
+@sc{cdr} of the last cons cell is @code{nil}. This asymmetry between
+the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
level of cons cells, the @sc{car} and @sc{cdr} slots have the same
characteristics.
@end example
@end defun
+@tindex pop
+@defmac pop listname
+This macro is a way of examining the @sc{car} of a list,
+and taking it off the list, all at once. It is new in Emacs 21.
+
+It operates on the list which is stored in the symbol @var{listname}.
+It removes this element from the list by setting @var{listname}
+to the @sc{cdr} of its old value---but it also returns the @sc{car}
+of that list, which is the element being removed.
+
+@example
+x
+ @result{} (a b c)
+(pop x)
+ @result{} a
+x
+ @result{} (b c)
+@end example
+@end defmac
+
@defun nth n list
This function returns the @var{n}th element of @var{list}. Elements
are numbered starting with zero, so the @sc{car} of @var{list} is
@end defun
@defun safe-length list
-@tindex safe-length
This function returns the length of @var{list}, with no risk
of either an error or an infinite loop.
Functions}.
@defun caar cons-cell
-@tindex caar
This is the same as @code{(car (car @var{cons-cell}))}.
@end defun
@defun cadr cons-cell
-@tindex cadr
This is the same as @code{(car (cdr @var{cons-cell}))}
or @code{(nth 1 @var{cons-cell})}.
@end defun
@defun cdar cons-cell
-@tindex cdar
This is the same as @code{(cdr (car @var{cons-cell}))}.
@end defun
@defun cddr cons-cell
-@tindex cddr
This is the same as @code{(cdr (cdr @var{cons-cell}))}
or @code{(nthcdr 2 @var{cons-cell})}.
@end defun
any symbol can serve both purposes.
@end defun
+@tindex push
+@defmac push newelt listname
+This macro provides an alternative way to write
+@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
+It is new in Emacs 21.
+@end defmac
+
@defun list &rest objects
This function creates a list with @var{objects} as its elements. The
resulting list is always @code{nil}-terminated. If no @var{objects}
to them as arguments, relinking their cons cells to form a new list that
is the returned value.
-@ifinfo
+@ifnottex
See @code{delq}, in @ref{Sets And Lists}, for another function
that modifies cons cells.
-@end ifinfo
+@end ifnottex
@iftex
The function @code{delq} in the following section is another example
of destructive list manipulation.
@end smallexample
@end defun
-@tindex assoc-default
@defun assoc-default key alist test default
This function searches @var{alist} for a match for @var{key}. For each
element of @var{alist}, it compares the element (if it is an atom) or
@end smallexample
@end defun
+@defun assoc-delete-all key alist
+@tindex assoc-delete-all
+This function deletes from @var{alist} all the elements whose @sc{car}
+is @var{key}. It returns the modified alist.
+@example
+(assoc-delete-all 'foo
+ '((foo 1) (bar 2) (foo 3) (lose 4)))
+ @result{} ((bar 2) (lose 4))
+@end example
+@end defun