X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/11fdef7d0cf3ef1ce30d1cd09ca9ca9a2b099d20..eceeb5fca618f3bc0743c2388148dd758229c7c9:/doc/lispref/lists.texi diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 064be89632..82a796c670 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1,8 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 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 @chapter Lists @cindex lists @@ -23,7 +22,6 @@ the whole list. * Modifying Lists:: Storing new pieces into an existing list. * Sets And Lists:: A list can represent a finite mathematical set. * Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. @end menu @node Cons Cells @@ -31,61 +29,56 @@ the whole list. @cindex lists and cons cells 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. 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.'' +@dfn{cons cells} (@pxref{Cons Cell Type}). A cons cell is a data +object that represents an 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. + 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 +(this asymmetry between @sc{car} and @sc{cdr} is entirely a matter of +convention; at the level of cons cells, the @sc{car} and @sc{cdr} +slots have similar properties). Hence, the @sc{cdr} slot of each cons +cell in a list refers to the following cons cell. @cindex true list - Since @code{nil} is the conventional value to put in the @sc{cdr} of -the last cons cell in the list, we call that case a @dfn{true list}. - - In Lisp, we consider the symbol @code{nil} a list as well as a -symbol; it is the list with no elements. For convenience, the symbol + Also by convention, the @sc{cdr} of the last cons cell in a list is +@code{nil}. We call such a @code{nil}-terminated structure a +@dfn{true list}. In Emacs Lisp, the symbol @code{nil} is both a +symbol and a list with no elements. For convenience, the symbol @code{nil} is considered to have @code{nil} as its @sc{cdr} (and also -as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a -true list. +as its @sc{car}). + + Hence, the @sc{cdr} of a true list is always a true list. The +@sc{cdr} of a nonempty true list is a true list containing all the +elements except the first. @cindex dotted list @cindex circular list - If the @sc{cdr} of a list's last cons cell is some other value, -neither @code{nil} nor another cons cell, we call the structure a -@dfn{dotted list}, since its printed representation would use -@samp{.}. There is one other possibility: some cons cell's @sc{cdr} -could point to one of the previous cons cells in the list. We call -that structure a @dfn{circular list}. + If the @sc{cdr} of a list's last cons cell is some value other than +@code{nil}, we call the structure a @dfn{dotted list}, since its +printed representation would use dotted pair notation (@pxref{Dotted +Pair Notation}). There is one other possibility: some cons cell's +@sc{cdr} could point to one of the previous cons cells in the list. +We call that structure a @dfn{circular list}. For some purposes, it does not matter whether a list is true, -circular or dotted. If the program doesn't look far enough down the +circular or dotted. If a program doesn't look far enough down the list to see the @sc{cdr} of the final cons cell, it won't care. However, some functions that operate on lists demand true lists and signal errors if given a dotted list. Most functions that try to find the end of a list enter infinite loops if given a circular list. @cindex list structure - Because most cons cells are used as part of lists, the phrase -@dfn{list structure} has come to mean any structure made out of cons -cells. - - The @sc{cdr} of any nonempty true list @var{l} is a list containing all the -elements of @var{l} except the first. - - @xref{Cons Cell Type}, for the read and print syntax of cons cells and -lists, and for ``box and arrow'' illustrations of lists. + Because most cons cells are used as part of lists, we refer to any +structure made out of cons cells as a @dfn{list structure}. @node List-related Predicates @section Predicates on Lists @@ -94,7 +87,7 @@ lists, and for ``box and arrow'' illustrations of lists. whether it is a cons cell or is a list, or whether it is the distinguished object @code{nil}. (Many of these predicates can be defined in terms of the others, but they are used so often that it is -worth having all of them.) +worth having them.) @defun consp object This function returns @code{t} if @var{object} is a cons cell, @code{nil} @@ -257,6 +250,10 @@ x x @result{} (b c) @end example + +@noindent +For the @code{pop} macro, which removes an element from a list, +@xref{List Variables}. @end defmac @defun nth n list @@ -462,7 +459,7 @@ element is @var{object}. Compare @code{make-list} with @result{} nil @end group @group -(setq l (make-list 3 '(a b)) +(setq l (make-list 3 '(a b))) @result{} ((a b) (a b) (a b)) (eq (car l) (cadr l)) @result{} t @@ -695,6 +692,10 @@ This macro provides an alternative way to write l @result{} (c a b) @end example + +@noindent +For the @code{pop} macro, which removes the first element from a list, +@xref{List Elements}. @end defmac Two functions modify lists that are the values of variables. @@ -762,8 +763,7 @@ if it already has one; otherwise, it is equivalent to @code{nil}. The argument @var{symbol} is not implicitly quoted; @code{add-to-ordered-list} is an ordinary function, like @code{set} -and unlike @code{setq}. Quote the argument yourself if that is what -you want. +and unlike @code{setq}. Quote the argument yourself if necessary. The ordering information is stored in a hash table on @var{symbol}'s @code{list-order} property. @@ -1268,7 +1268,7 @@ functions for sets include @code{memq} and @code{delq}, and their @b{Common Lisp note:} Common Lisp has functions @code{union} (which avoids duplicate elements) and @code{intersection} for set operations. Although standard GNU Emacs Lisp does not have them, the @file{cl} -library provides versions. @inforef{Top, Overview, cl}. +library provides versions. @xref{Top,, Overview, cl, Common Lisp Extensions}. @end quotation @defun memq object list @@ -1454,7 +1454,7 @@ For example: l @result{} ((2) (1)) ;; @r{If you want to change @code{l} reliably,} -;; @r{write @code{(setq l (delete elt l))}.} +;; @r{write @code{(setq l (delete '(2) l))}.} @end group @group (setq l '((2) (1) (2))) @@ -1631,7 +1631,7 @@ a @sc{cdr} @code{equal} to @var{value}. @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc},'' finding the key for a given value. +this as ``reverse @code{assoc}'', finding the key for a given value. @end defun @defun assq key alist @@ -1672,7 +1672,7 @@ a @sc{cdr} @code{eq} to @var{value}. @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq},'' finding the key for a given value. +this as ``reverse @code{assq}'', finding the key for a given value. For example: @@ -1800,90 +1800,3 @@ often modifies the original list structure of @var{alist}. compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. @end defun - -@node Rings -@section Managing a Fixed-Size Ring of Objects - -@cindex ring data structure - This section describes functions for operating on rings. A -@dfn{ring} is a fixed-size data structure that supports insertion, -deletion, rotation, and modulo-indexed reference and traversal. - -@defun make-ring size -This returns a new ring capable of holding @var{size} objects. -@var{size} should be an integer. -@end defun - -@defun ring-p object -This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. -@end defun - -@defun ring-size ring -This returns the maximum capacity of the @var{ring}. -@end defun - -@defun ring-length ring -This returns the number of objects that @var{ring} currently contains. -The value will never exceed that returned by @code{ring-size}. -@end defun - -@defun ring-elements ring -This returns a list of the objects in @var{ring}, in order, newest first. -@end defun - -@defun ring-copy ring -This returns a new ring which is a copy of @var{ring}. -The new ring contains the same (@code{eq}) objects as @var{ring}. -@end defun - -@defun ring-empty-p ring -This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. -@end defun - - The newest element in the ring always has index 0. Higher indices -correspond to older elements. Indices are computed modulo the ring -length. Index @minus{}1 corresponds to the oldest element, @minus{}2 -to the next-oldest, and so forth. - -@defun ring-ref ring index -This returns the object in @var{ring} found at index @var{index}. -@var{index} may be negative or greater than the ring length. If -@var{ring} is empty, @code{ring-ref} signals an error. -@end defun - -@defun ring-insert ring object -This inserts @var{object} into @var{ring}, making it the newest -element, and returns @var{object}. - -If the ring is full, insertion removes the oldest element to -make room for the new element. -@end defun - -@defun ring-remove ring &optional index -Remove an object from @var{ring}, and return that object. The -argument @var{index} specifies which item to remove; if it is -@code{nil}, that means to remove the oldest item. If @var{ring} is -empty, @code{ring-remove} signals an error. -@end defun - -@defun ring-insert-at-beginning ring object -This inserts @var{object} into @var{ring}, treating it as the oldest -element. The return value is not significant. - -If the ring is full, this function removes the newest element to make -room for the inserted element. -@end defun - -@cindex fifo data structure - If you are careful not to exceed the ring size, you can -use the ring as a first-in-first-out queue. For example: - -@lisp -(let ((fifo (make-ring 5))) - (mapc (lambda (obj) (ring-insert fifo obj)) - '(0 one "two")) - (list (ring-remove fifo) t - (ring-remove fifo) t - (ring-remove fifo))) - @result{} (0 t one t "two") -@end lisp