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

[Drew Adams <drew.adams@oracle.com>]

> > Do we have a non-destructive `map-put'?
> 
> There's `map-insert'.

My point was that there is no need for a function
name to signal that the function so named is
"destructive".  The doc string should do that,
however.

The only case where we might need a function name
to signal this is when we have two functions with
exactly the same name otherwise, one "destructive"
and the other not.

There is macro `map-put', which is supposedly
obsolete now.  It would be fine (IMHO) to just
name the new, "destructive" function `map-put',
IOW replace the macro that is anyway obsolete.

If we did that we'd need to post a notice (in
NEWS and the doc string, for example) that we've
made such an incompatible change.  Probably not
a big deal.

> > Much more important than the function name, however, is
> > the real answer: Put the important info in the doc string.
> 
> The docstring, yes, of course, but the function name is IMHO the most
> important part of the documentation.

The function name should, yes, say what the function
does.  But it need not always say how it does it or
whether the action might change list structure etc.

Or if it does then that should be done systematically,
for the names of all "destructive" functions.  It is
misleading in Lisp to have some "destructive" functions
signal that fact in their names, and others not do so.

And as I said, if you use such a function in a function
you define, it can often be the case that your function
is, likewise, "destructive". Are you going to name your
function using such a name signal too?  And so on.  It's
a contagious virus, which we generally ignore, in terms
of propagating such a name convention.

Again, just one, no doubt minority, opinion.  I express
the opinion, but I don't expect that it will have much
effect.
 
> As I said, I like Stefan's approach, but if everybody else dislike it,
> and if you think it's not idiomatic Elisp, then let's change the name.
> 
> Stefan, would it be ok with you?

I don't think there is a standard idiom.  Some names
indicate (if a user knows the particular convention)
possible "destruction", but others do not.

An old user might recognize that `nreverse' is a
"destructive" `reverse' from the name, but a new user
might not.  The doc should be the place where we make
very clear what a function does and whether it is
"destructive".

If Emacs does want to follow a convention of naming
"destructive" functions then it should do so more
systematically, IMO.  (And IMO it should not bother
to do so.)  In that case, apply the convention all
over the place, even including renaming (but keeping
an old alias) functions such as `nreverse'.