Re: replacing a certain element in a list with another

[Roland Winkler]

Barry Margolin <barry.margolin@level3.com> writes:

> The verbose documentation of all the destructive list operations should
> mention that you must use the value to get the expected results all the
> time, rather than depending on everything to work due to the lists being
> modified in place.

The first part of your sentence is exactly my point. Unlike the
docstring of nreverse, the info node presently does not say
explicitely that it is the _return_ value that should be used. (It
is hidden only implicitely in the sentence: "To avoid confusion, we
usually store the result of `nreverse' back in the same variable
which held the original list.")


The info node Rearrangement in the elisp manual says:

 - Function: nreverse list
     This function reverses the order of the elements of LIST.  Unlike
     `reverse', `nreverse' alters its argument by reversing the CDRs in
     the cons cells forming the list.  The cons cell that used to be
     the last one in LIST becomes the first cons cell of the value.

     For example:

          (setq x '(a b c))
               => (a b c)
          x
               => (a b c)
          (nreverse x)
               => (c b a)
          ;; The cons cell that was first is now last.
          x
               => (a)

The last two lines I find confusing because they use the argument of
nreverse after it was passed to nreverse. (They gave rise to my
question whether the argument of nreverse could be used for anything
"useful" after it was passed to nreverse.) Instead, the info node
could use the same sentence that is used in the docstring of nreverse:

    Returns the beginning of the reversed list.