Re: map.el documentation

[Augusto Stoffel]

On Fri, 24 Jan 2025 at 16:09, Robert Pluim wrote:

>>>>>> On Fri, 24 Jan 2025 14:29:35 +0100, Augusto Stoffel 
>>>>>> <arstoffel@gmail.com> said:
>
>     Augusto> On Thu, 23 Jan 2025 at 11:33, Robert Pluim wrote:
>     >> I must admit, the semantics of `map-insert' feel more natural to me
>     >> than `map-put!', but I guess both are needed.
>
>     Augusto> I've argued in some previous bug that map-put! is misguided and 
> should
>     Augusto> be obsoleted.
>
>     Augusto> The right concept is a map-insert! function that _may_ act 
> destructively
>     Augusto> on the argument.  This is the bread and butter of Lisp semantics 
> and
>     Augusto> gets rid of the weird `map-not-inplace` error.
>
> We could change `map-insert' to do that.

By "that" you mean to actually replace an existing alist entry instead
of consing a repeated key at the beginning?  map-insert must remain
non-destructive, so it would become an O(N) operation in time and space.

At first I thought that would be a bad idea.  However, if one actually
cares about speed and is fine with consing a possibly repeated key, then
arguably one shouldn't use map.el -- there already is cons for that.  So
it makes sense to use map.el to supply an implementation of the
operation you want.

(BTW, I don't quite see an use for the polymorphism aspect of map.el and
the only reason I would use that library is for less common operations
on map-like things whose type I know for sure.  For example
map-nested-elt is a nice function.)

>     Augusto> (There are some other funny behaviors in map.el which IMHO 
> should be
>     Augusto> fixed while it's still not heavily used.)
>
> Do tell.

I'd have to search bug-gnu-emacs to remember.  It's all in there
somewhere.

> Itʼs not heavily used inside Emacs. Itʼs been around since emacs-25,
> so who knows what use packages make of it.
>
> If we fix `map-insert', it also fixes this:
>
> ELISP> (map-length (map-insert (map-insert nil 1 2) 1 4))
> 2

Well, ((1 . 2) (1 . 4)) is a perfectly valid alist with "effectively 1"
entry.  Even if map-insert doesn't generate this kind of data, the user
might do it by other means.

I'd argue map-length should compute the "length as alist" as opposed to
returning the list length.  Because if you want the list length or don't
care about the difference, you can just call `length`.

> (I know what the docstring says. I want a map that contains only
> unique key/val mappings).
>
> Robert