X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/61b23410328cce5b22b15d06b939dead453e2721..7238837d023af0b6461e905af99cad1a03931f9a:/lispref/lists.texi diff --git a/lispref/lists.texi b/lispref/lists.texi index 1f0199096f..d30dcb0c27 100644 --- a/lispref/lists.texi +++ b/lispref/lists.texi @@ -1,7 +1,8 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, +@c 2003, 2004 +@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 @@ -51,16 +52,37 @@ 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. +@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 +@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. + +@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}. + + 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 +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 symbol @code{nil} is considered a list as well as a symbol; it is -the 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}). - The @sc{cdr} of any nonempty list @var{l} is a list containing all the elements of @var{l} except the first. @@ -328,6 +350,7 @@ x @end defmac @defun nth n list +@anchor{Definition of nth} 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 element number zero. If the length of @var{list} is @var{n} or less, @@ -384,20 +407,22 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of @end defun @defun last list &optional n -This function reruns the last link of the given @var{list}. The -@code{car} of this link is the list's last element. If @var{list} is -null, @code{nil} is returned. If @var{n} is non-nil the -@var{n}-th-to-last link is returned instead, or the whole @var{list} if -@var{n} is bigger than @var{list}'s length. +This function returns the last link of @var{list}. The @code{car} of +this link is the list's last element. If @var{list} is null, +@code{nil} is returned. If @var{n} is non-@code{nil}, the +@var{n}th-to-last link is returned instead, or the whole of @var{list} +if @var{n} is bigger than @var{list}'s length. @end defun @defun safe-length list -This function returns the length of @var{list}, with no risk -of either an error or an infinite loop. - -If @var{list} is not really a list, @code{safe-length} returns 0. If -@var{list} is circular, it returns a finite value which is at least the -number of distinct elements. +@anchor{Definition of safe-length} +This function returns the length of @var{list}, with no risk of either +an error or an infinite loop. It generally returns the number of +distinct cons cells in the list. However, for circular lists, +the value is just an upper bound; it is often too large. + +If @var{list} is not @code{nil} or a cons cell, @code{safe-length} +returns 0. @end defun The most common way to compute the length of a list, when you are not @@ -448,11 +473,11 @@ interesting to note that @code{list} is used more times in the source code for Emacs than @code{cons}. @defun cons object1 object2 -This function is the fundamental function used to build new list +This function is the most basic function for building new list structure. It creates a new cons cell, making @var{object1} the -@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new cons -cell. The arguments @var{object1} and @var{object2} may be any Lisp -objects, but most often @var{object2} is a list. +@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new +cons cell. The arguments @var{object1} and @var{object2} may be any +Lisp objects, but most often @var{object2} is a list. @example @group @@ -496,6 +521,15 @@ any symbol can serve both purposes. This macro provides an alternative way to write @code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. It is new in Emacs 21. + +@example +(setq l '(a b)) + @result{} (a b) +(push 'c l) + @result{} (c a b) +l + @result{} (c a b) +@end example @end defmac @defun list &rest objects @@ -520,9 +554,9 @@ are given, the empty list is returned. @end defun @defun make-list length object -This function creates a list of length @var{length}, in which all the -elements have the identical value @var{object}. Compare -@code{make-list} with @code{make-string} (@pxref{Creating Strings}). +This function creates a list of @var{length} elements, in which each +element is @var{object}. Compare @code{make-list} with +@code{make-string} (@pxref{Creating Strings}). @example @group @@ -533,6 +567,12 @@ elements have the identical value @var{object}. Compare (make-list 0 'pigs) @result{} nil @end group +@group +(setq l (make-list 3 '(a b)) + @result{} ((a b) (a b) (a b)) +(eq (car l) (cadr l)) + @result{} t +@end group @end example @end defun @@ -550,17 +590,16 @@ object. The final argument is not copied or converted; it becomes the @sc{cdr} of the last cons cell in the new list. If the final argument is itself a list, then its elements become in effect elements of the result list. If the final element is not a list, the result is a -``dotted list'' since its final @sc{cdr} is not @code{nil} as required +dotted list since its final @sc{cdr} is not @code{nil} as required in a true list. -The @code{append} function also allows integers as arguments. It -converts them to strings of digits, making up the decimal print -representation of the integer, and then uses the strings instead of the -original integers. @strong{Don't use this feature; we plan to eliminate -it. If you already use this feature, change your programs now!} The -proper way to convert an integer to a decimal number in this way is with -@code{format} (@pxref{Formatting Strings}) or @code{number-to-string} -(@pxref{String Conversion}). +In Emacs 20 and before, the @code{append} function also allowed +integers as (non last) arguments. It converted them to strings of +digits, making up the decimal print representation of the integer, and +then used the strings instead of the original integers. This obsolete +usage no longer works. The proper way to convert an integer to a +decimal number in this way is with @code{format} (@pxref{Formatting +Strings}) or @code{number-to-string} (@pxref{String Conversion}). @end defun Here is an example of using @code{append}: @@ -693,29 +732,58 @@ x @end example @end defun -@defun remq object list -This function returns a copy of @var{list}, with all elements removed -which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} -says that it uses @code{eq} to compare @var{object} against the elements -of @code{list}. +@defun copy-tree tree &optional vecp +This function returns a copy of the tree @code{tree}. If @var{tree} is a +cons cell, this makes a new cons cell with the same @sc{car} and +@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the +same way. + +Normally, when @var{tree} is anything other than a cons cell, +@code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is +non-@code{nil}, it copies vectors too (and operates recursively on +their elements). +@end defun + +@defun number-sequence from &optional to separation +This returns a list of numbers starting with @var{from} and +incrementing by @var{separation}, and ending at or just before +@var{to}. @var{separation} can be positive or negative and defaults +to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, +the one element list @code{(from)} is returned. If @var{separation} +is 0 and @var{to} is neither @code{nil} nor numerically equal to +@var{from}, an error is signaled. + +All arguments can be integers or floating point numbers. However, +floating point arguments can be tricky, because floating point +arithmetic is inexact. For instance, depending on the machine, it may +quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns +the one element list @code{(0.4)}, whereas +@code{(number-sequence 0.4 0.8 0.2)} returns a list with three +elements. The @var{n}th element of the list is computed by the exact +formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if +one wants to make sure that @var{to} is included in the list, one can +pass an expression of this exact type for @var{to}. Alternatively, +one can replace @var{to} with a slightly larger value (or a slightly +more negative value if @var{separation} is negative). + +Some examples: @example -@group -(setq sample-list '(a b c a b c)) - @result{} (a b c a b c) -@end group -@group -(remq 'a sample-list) - @result{} (b c b c) -@end group -@group -sample-list - @result{} (a b c a b c) -@end group +(number-sequence 4 9) + @result{} (4 5 6 7 8 9) +(number-sequence 9 4 -1) + @result{} (9 8 7 6 5 4) +(number-sequence 9 4 -2) + @result{} (9 7 5) +(number-sequence 8) + @result{} (8) +(number-sequence 8 5) + @result{} nil +(number-sequence 5 8 -1) + @result{} nil +(number-sequence 1.5 6 2) + @result{} (1.5 3.5 5.5) @end example -@noindent -The function @code{delq} offers a way to perform this operation -destructively. See @ref{Sets And Lists}. @end defun @node Modifying Lists @@ -723,7 +791,7 @@ destructively. See @ref{Sets And Lists}. @cindex destructive list operations You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the -primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' +primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' operations because they change existing list structure. @cindex CL note---@code{rplaca} vrs @code{setcar} @@ -1064,19 +1132,19 @@ value. @example @group -(setq x '(1 2 3 4)) - @result{} (1 2 3 4) +(setq x '(a b c)) + @result{} (a b c) @end group @group x - @result{} (1 2 3 4) + @result{} (a b c) (nreverse x) - @result{} (4 3 2 1) + @result{} (c b a) @end group @group ;; @r{The cons cell that was first is now last.} x - @result{} (1) + @result{} (a) @end group @end example @@ -1180,7 +1248,8 @@ useful example of @code{sort}. A list can represent an unordered mathematical set---simply consider a value an element of a set if it appears in the list, and ignore the order of the list. To form the union of two sets, use @code{append} (as -long as you don't mind having duplicate elements). Other useful +long as you don't mind having duplicate elements). You can remove +@code{equal} duplicates using @code{delete-dups}. Other useful functions for sets include @code{memq} and @code{delq}, and their @code{equal} versions, @code{member} and @code{delete}. @@ -1278,9 +1347,34 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}: @end group @end example -The following two functions are like @code{memq} and @code{delq} but use -@code{equal} rather than @code{eq} to compare elements. @xref{Equality -Predicates}. +@defun remq object list +This function returns a copy of @var{list}, with all elements removed +which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} +says that it uses @code{eq} to compare @var{object} against the elements +of @code{list}. + +@example +@group +(setq sample-list '(a b c a b c)) + @result{} (a b c a b c) +@end group +@group +(remq 'a sample-list) + @result{} (b c b c) +@end group +@group +sample-list + @result{} (a b c a b c) +@end group +@end example +@noindent +The function @code{delq} offers a way to perform this operation +destructively. See @ref{Sets And Lists}. +@end defun + +The following three functions are like @code{memq}, @code{delq} and +@code{remq}, but use @code{equal} rather than @code{eq} to compare +elements. @xref{Equality Predicates}. @defun member object list The function @code{member} tests to see whether @var{object} is a member @@ -1357,6 +1451,21 @@ Lisp. The Common Lisp versions do not use @code{equal} to compare elements. @end quotation +@defun member-ignore-case object list +This function is like @code{member}, except that @var{object} should +be a string and that it ignores differences in letter-case and text +representation: upper-case and lower-case letters are treated as +equal, and unibyte strings are converted to multibyte prior to +comparison. +@end defun + +@defun delete-dups list +This function destructively removes all @code{equal} duplicates from +@var{list}, stores the result in @var{list} and returns it. Of +several @code{equal} occurrences of an element in @var{list}, +@code{delete-dups} keeps the first one. +@end defun + See also the function @code{add-to-list}, in @ref{Setting Variables}, for another way to add an element to a list stored in a variable. @@ -1379,9 +1488,9 @@ the value @code{cones}; the key @code{oak} is associated with @example @group -'((pine . cones) - (oak . acorns) - (maple . seeds)) +((pine . cones) + (oak . acorns) + (maple . seeds)) @end group @end example @@ -1397,10 +1506,10 @@ the alist element: Sometimes it is better to design an alist to store the associated value in the @sc{car} of the @sc{cdr} of the element. Here is an -example: +example of such an alist: @example -'((rose red) (lily white) (buttercup yellow)) +((rose red) (lily white) (buttercup yellow)) @end example @noindent @@ -1465,9 +1574,9 @@ Here is another example, in which the keys and values are not symbols: @end smallexample @end defun - The functions @code{assoc-ignore-representation} and -@code{assoc-ignore-case} are much like @code{assoc} except using -@code{compare-strings} to do the comparison. @xref{Text Comparison}. + The function @code{assoc-string} is much like @code{assoc} except +that it ignores certain differences between strings. @xref{Text +Comparison}. @defun rassoc value alist This function returns the first association with value @var{value} in @@ -1549,7 +1658,7 @@ becomes clearer if the association is written in dotted pair notation: @end smallexample @end defun -@defun assoc-default key alist test default +@defun assoc-default key alist &optional 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 the element's @sc{car} (if it is a cons) against @var{key}, by calling @@ -1622,11 +1731,22 @@ the associations of one copy without affecting the other: @defun assq-delete-all key alist @tindex assq-delete-all This function deletes from @var{alist} all the elements whose @sc{car} -is @code{eq} to @var{key}. It returns the modified alist. +is @code{eq} to @var{key}, much as if you used @code{delq} to delete +each such element one by one. It returns the shortened alist, and +often modifies the original list structure of @var{alist}. For +correct results, use the return value of @code{assq-delete-all} rather +than looking at the saved value of @var{alist}. @example -(assoc-delete-all 'foo - '((foo 1) (bar 2) (foo 3) (lose 4))) +(setq alist '((foo 1) (bar 2) (foo 3) (lose 4))) + @result{} ((foo 1) (bar 2) (foo 3) (lose 4)) +(assq-delete-all 'foo alist) @result{} ((bar 2) (lose 4)) +alist + @result{} ((foo 1) (bar 2) (lose 4)) @end example @end defun + +@ignore + arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4 +@end ignore