@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Lists
@node List-related Predicates
@section Predicates on Lists
+@cindex predicates for lists
+@cindex list predicates
The following predicates test whether a Lisp object is an atom,
whether it is a cons cell or is a list, or whether it is the
element number zero. If the length of @var{list} is @var{n} or less,
the value is @code{nil}.
-If @var{n} is negative, @code{nth} returns the first element of
-@var{list}.
+@c Behavior for -ve n undefined since 2013/08; see bug#15059.
+@ignore
+If @var{n} is negative, @code{nth} returns the first element of @var{list}.
+@end ignore
@example
@group
@group
(nth 10 '(1 2 3 4))
@result{} nil
-@end group
-@group
-(nth -3 '(1 2 3 4))
- @result{} 1
(nth n x) @equiv{} (car (nthcdr n x))
@end group
words, it skips past the first @var{n} links of @var{list} and returns
what follows.
-If @var{n} is zero or negative, @code{nthcdr} returns all of
+@c "or negative" removed 2013/08; see bug#15059.
+If @var{n} is zero, @code{nthcdr} returns all of
@var{list}. If the length of @var{list} is @var{n} or less,
@code{nthcdr} returns @code{nil}.
@result{} nil
@end group
@group
-(nthcdr -3 '(1 2 3 4))
+(nthcdr 0 '(1 2 3 4))
@result{} (1 2 3 4)
@end group
@end example
resulting list. Instead, the sequence becomes the final @sc{cdr}, like
any other non-list final argument.
-@defun reverse list
-This function creates a new list whose elements are the elements of
-@var{list}, but in reverse order. The original argument @var{list} is
-@emph{not} altered.
-
-@example
-@group
-(setq x '(1 2 3 4))
- @result{} (1 2 3 4)
-@end group
-@group
-(reverse x)
- @result{} (4 3 2 1)
-x
- @result{} (1 2 3 4)
-@end group
-@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
numerically equal to @var{from}, @code{number-sequence} signals an
error, since those arguments specify an infinite sequence.
-All arguments can be integers or floating point numbers. However,
-floating point arguments can be tricky, because floating point
+All arguments are numbers.
+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
@node List Variables
@section Modifying List Variables
+@cindex modify a list
+@cindex list modification
These functions, and one macro, provide convenient ways
to modify a list which is stored in a variable.
@node Setcar
@subsection Altering List Elements with @code{setcar}
+@cindex replace list element
+@cindex list, replace element
Changing the @sc{car} of a cons cell is done with @code{setcar}. When
used on a list, @code{setcar} replaces one element of a list with a
@node Setcdr
@subsection Altering the CDR of a List
+@cindex replace part of list
The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}:
@node Rearrangement
@subsection Functions that Rearrange Lists
@cindex rearrangement of lists
+@cindex reordering, of elements in lists
@cindex modification of lists
Here are some functions that rearrange lists ``destructively'' by
@end smallexample
@end defun
-@defun nreverse list
-@cindex reversing a list
- This function reverses the order of the elements of @var{list}.
-Unlike @code{reverse}, @code{nreverse} alters its argument by reversing
-the @sc{cdr}s in the cons cells forming the list. The cons cell that
-used to be the last one in @var{list} becomes the first cons cell of the
-value.
-
- For example:
-
-@example
-@group
-(setq x '(a b c))
- @result{} (a b c)
-@end group
-@group
-x
- @result{} (a b c)
-(nreverse x)
- @result{} (c b a)
-@end group
-@group
-;; @r{The cons cell that was first is now last.}
-x
- @result{} (a)
-@end group
-@end example
-
- To avoid confusion, we usually store the result of @code{nreverse}
-back in the same variable which held the original list:
-
-@example
-(setq x (nreverse x))
-@end example
-
- Here is the @code{nreverse} of our favorite example, @code{(a b c)},
-presented graphically:
-
-@smallexample
-@group
-@r{Original list head:} @r{Reversed list:}
- ------------- ------------- ------------
-| car | cdr | | car | cdr | | car | cdr |
-| a | nil |<-- | b | o |<-- | c | o |
-| | | | | | | | | | | | |
- ------------- | --------- | - | -------- | -
- | | | |
- ------------- ------------
-@end group
-@end smallexample
-@end defun
-
-@defun sort list predicate
-@cindex stable sort
-@cindex sorting lists
-This function sorts @var{list} stably, though destructively, and
-returns the sorted list. It compares elements using @var{predicate}. A
-stable sort is one in which elements with equal sort keys maintain their
-relative order before and after the sort. Stability is important when
-successive sorts are used to order elements according to different
-criteria.
-
-The argument @var{predicate} must be a function that accepts two
-arguments. It is called with two elements of @var{list}. To get an
-increasing order sort, the @var{predicate} should return non-@code{nil} if the
-first element is ``less than'' the second, or @code{nil} if not.
-
-The comparison function @var{predicate} must give reliable results for
-any given pair of arguments, at least within a single call to
-@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
-less than @var{b}, @var{b} must not be less than @var{a}. It must be
-@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
-is less than @var{c}, then @var{a} must be less than @var{c}. If you
-use a comparison function which does not meet these requirements, the
-result of @code{sort} is unpredictable.
-
-The destructive aspect of @code{sort} is that it rearranges the cons
-cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort
-function would create new cons cells to store the elements in their
-sorted order. If you wish to make a sorted copy without destroying the
-original, copy it first with @code{copy-sequence} and then sort.
-
-Sorting does not change the @sc{car}s of the cons cells in @var{list};
-the cons cell that originally contained the element @code{a} in
-@var{list} still has @code{a} in its @sc{car} after sorting, but it now
-appears in a different position in the list due to the change of
-@sc{cdr}s. For example:
-
-@example
-@group
-(setq nums '(1 3 2 6 5 4 0))
- @result{} (1 3 2 6 5 4 0)
-@end group
-@group
-(sort nums '<)
- @result{} (0 1 2 3 4 5 6)
-@end group
-@group
-nums
- @result{} (1 2 3 4 5 6)
-@end group
-@end example
-
-@noindent
-@strong{Warning}: Note that the list in @code{nums} no longer contains
-0; this is the same cons cell that it was before, but it is no longer
-the first one in the list. Don't assume a variable that formerly held
-the argument now holds the entire sorted list! Instead, save the result
-of @code{sort} and use that. Most often we store the result back into
-the variable that held the original list:
-
-@example
-(setq nums (sort nums '<))
-@end example
-
-@xref{Sorting}, for more functions that perform sorting.
-See @code{documentation} in @ref{Accessing Documentation}, for a
-useful example of @code{sort}.
-@end defun
-
@node Sets And Lists
@section Using Lists as Sets
@cindex lists as sets
@defun memql object list
The function @code{memql} tests to see whether @var{object} is a member
of @var{list}, comparing members with @var{object} using @code{eql},
-so floating point elements are compared by value.
+so floating-point elements are compared by value.
If @var{object} is a member, @code{memql} returns a list starting with
its first occurrence in @var{list}. Otherwise, it returns @code{nil}.
@node Plist Access
@subsection Property Lists Outside Symbols
+@cindex plist access
+@cindex accessing plist properties
The following functions can be used to manipulate property lists.
They all compare property names using @code{eq}.