RE: map-put! and (setf (map-elt ...) ..) on lists

[Drew Adams]

> >> So really than complain, please provide constructive alternatives.
> >
> > Or just go and rename it directly.
> 
> Given that seq.el is completely free of side-effects (IIRC, there might
> be exceptions but I don't think so), and that map.el was done mimicking
> seq.el but for key/value collections, I like the idea of stating
> clearly when a function of map.el mutates the argument.

Only when the same function exists in both "destructive"
and non-destructive versions - such as `reverse' and
`nreverse', should we bother to reflect that difference
in the function names - somehow.  And AFAIK we do not
have a convention for doing that.  (Some old Lisp functions
use prefix `n', but that's not great.)

Do we have a non-destructive `map-put'?  I see that there
is a macro `map-put', so I guess that would qualify.  But
no - that macro is now obsolete - replaced by `map-put!'.

Much more important than the function name, however, is
the real answer: Put the important info in the doc string.

That's what should have been done at the outset, and
AFAICT it still hasn't been done, here.  I see these doc
strings for the obsolete `map-put' and the new `map-put!',
respectively:

map-put:

 Associate KEY with VALUE in MAP and return VALUE.
 If KEY is already present in MAP, replace the associated value
 with VALUE.
 When MAP is a list, test equality with TESTFN if non-nil, otherwise use `eql'.

 MAP can be a list, hash-table or array.

map-put!:

 Associate KEY with VALUE in MAP and return VALUE.
 If KEY is already present in MAP, replace the associated value
 with VALUE.

The only change was to get rid of the last two lines (the
first of which is too long, BTW).

Whoa!  Nothing anywhere there that says whether a copy is
returned or the original value is mutated.  That's a bug,
IMO.

If you really want clarity about whether a function is
destructive, put it in the doc string.  That's the real
answer to Stefan's quandary, "Don't use "!" as a suffix"
doesn't say what to do instead."

That's the place to start.  And unless there is also to
be a non-destructive version, and we _need_ to have two
different names, there is no need to have any name
indication that a given function is "destructive".

(Just one opinion.)