@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 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
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 one cons cell for each element of
+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
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.
@end example
@end defmac
+@anchor{Definition of nth}
@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 example
@end defun
+@defun last list &optional n
+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
+
+@anchor{Definition of safe-length}
@defun safe-length list
-This function returns the length of @var{list}, with no risk
-of either an error or an infinite loop.
+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 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.
+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
or @code{(nthcdr 2 @var{cons-cell})}.
@end defun
+@defun butlast x &optional n
+This function returns the list @var{x} with the last element,
+or the last @var{n} elements, removed. If @var{n} is greater
+than zero it makes a copy of the list so as not to damage the
+original list. In general, @code{(append (butlast @var{x} @var{n})
+(last @var{x} @var{n}))} will return a list equal to @var{x}.
+@end defun
+
+@defun nbutlast x &optional n
+This is a version of @code{butlast} that works by destructively
+modifying the @code{cdr} of the appropriate element, rather than
+making a copy of the list.
+@end defun
+
@node Building Lists
@comment node-name, next, previous, up
@section Building Cons Cells and Lists
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
@cindex consing
@code{cons} is often used to add a single element to the front of a
-list. This is called @dfn{consing the element onto the list}. For
-example:
+list. This is called @dfn{consing the element onto the list}.
+@footnote{There is no strictly equivalent way to add an element to
+the end of a list. You can use @code{(append @var{listname} (list
+@var{newelt}))}, which creates a whole new list by copying @var{listname}
+and adding @var{newelt} to its end. Or you can use @code{(nconc
+@var{listname} (list @var{newelt}))}, which modifies @var{listname}
+by following all the @sc{cdr}s and then replacing the terminating
+@code{nil}. Compare this to adding an element to the beginning of a
+list with @code{cons}, which neither copies nor modifies the list.}
+For example:
@example
(setq list (cons newelt list))
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
@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
(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
@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}:
@end example
@end defun
+@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
+(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
+@end defun
+
@node Modifying Lists
@section Modifying Existing List Structure
@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}
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.
@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
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}.
This function destructively removes all elements @code{eq} to
@var{object} from @var{list}. The letter @samp{q} in @code{delq} says
that it uses @code{eq} to compare @var{object} against the elements of
-the list, like @code{memq}.
+the list, like @code{memq} and @code{remq}.
@end defun
When @code{delq} deletes elements from the front of the list, it does so
@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
@end example
@end defun
-@defun delete object list
-This function destructively removes all elements @code{equal} to
-@var{object} from @var{list}. It is to @code{delq} as @code{member} is
-to @code{memq}: it uses @code{equal} to compare elements with
-@var{object}, like @code{member}; when it finds an element that matches,
-it removes the element just as @code{delq} would. For example:
+@defun delete object sequence
+If @code{sequence} is a list, this function destructively removes all
+elements @code{equal} to @var{object} from @var{sequence}. For lists,
+@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
+uses @code{equal} to compare elements with @var{object}, like
+@code{member}; when it finds an element that matches, it removes the
+element just as @code{delq} would.
+
+If @code{sequence} is a vector or string, @code{delete} returns a copy
+of @code{sequence} with all elements @code{equal} to @code{object}
+removed.
+
+For example:
@example
@group
(delete '(2) '((2) (1) (2)))
@result{} ((1))
@end group
+@group
+(delete '(2) [(2) (1) (2)])
+ @result{} [(1)]
+@end group
+@end example
+@end defun
+
+@defun remove object sequence
+This function is the non-destructive counterpart of @code{delete}. If
+returns a copy of @code{sequence}, a list, vector, or string, with
+elements @code{equal} to @code{object} removed. For example:
+
+@example
+@group
+(remove '(2) '((2) (1) (2)))
+ @result{} ((1))
+@end group
+@group
+(remove '(2) [(2) (1) (2)])
+ @result{} [(1)]
+@end group
@end example
@end defun
@quotation
-@b{Common Lisp note:} The functions @code{member} and @code{delete} in
-GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common
-Lisp versions do not use @code{equal} to compare elements.
+@b{Common Lisp note:} The functions @code{member}, @code{delete} and
+@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common
+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.
@example
@group
-'((pine . cones)
- (oak . acorns)
- (maple . seeds))
+((pine . cones)
+ (oak . acorns)
+ (maple . seeds))
@end group
@end example
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
@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
@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
@end smallexample
@end defun
-@defun assoc-delete-all key alist
-@tindex assoc-delete-all
+@defun assq-delete-all key alist
+@tindex assq-delete-all
This function deletes from @var{alist} all the elements whose @sc{car}
-is @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
HCoop / bpt / emacs.git / blobdiff