X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/b6954afd99c5dedeb4d473c885b78e5453ab5e8c..7d584ec4df993279ce28940188853eaa3b38ee53:/lispref/lists.texi diff --git a/lispref/lists.texi b/lispref/lists.texi index ca31023594..661c8c3530 100644 --- a/lispref/lists.texi +++ b/lispref/lists.texi @@ -1,6 +1,7 @@ @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 @@ -32,17 +33,21 @@ the whole list. 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. @@ -302,6 +307,26 @@ This is in contrast to @code{cdr}, which signals an error if @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 @@ -359,7 +384,6 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of @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. @@ -373,23 +397,19 @@ worried that it may be circular, is with @code{length}. @xref{Sequence 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 @@ -441,6 +461,13 @@ used in this example and the function named @code{list} described below; 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} @@ -880,10 +907,10 @@ functions ``destructive'' because they chew up the original lists passed 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. @@ -1438,7 +1465,6 @@ becomes clearer if the association is written in dotted pair notation: @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 @@ -1509,4 +1535,14 @@ the associations of one copy without affecting the other: @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