Re: replacing a certain element in a list with another

[Kevin Rodgers]

Stefan Monnier wrote:
>Roland Winkler wrote:

> > It might be helpful to add a comment to the docstring or info page
> > for nreverse saying that its argument is modified such that
> > afterwards it is a 1-element list containing the last element of the
> > reversed list.
>
> I don't think this particular aspect of the behavior should be documented.
> Maybe we should add a note saying "the argument should not be used
> afterwards", but even that would not be very convincing.
> I think the only reasonable thing to put is a "don't use this unless you
> know what you're doing".

Why not document all the destructive list operations like delq, whose
doc string says:

If the first member of LIST is ELT, there is no way to remove it by side
effect; therefore, write `(setq foo (delq element foo))' to be sure of
changing the value of `foo'.

For nreverse, it would be:

Because the first cons cell of LIST is the last cons cell of the
returned list, write `(setq foo (nreverse foo))' to set `foo' to its
reversed value.

--
Kevin Rodgers