@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-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Lists
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 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
@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}.