Re: map.el documentation

[Robert Pluim]

>>>>> On Fri, 24 Jan 2025 17:08:34 +0100, Augusto Stoffel <arstoffel@gmail.com> 
>>>>> said:

    >> We could change `map-insert' to do that.

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

`map-insert' is non-destructive, it copies the map before adding the
entry. And if the map is a hash-table, it replaces the old
mapping. But consistency is the hobgoblin of small minds :-)

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

Yes. If we worry about backwards compatibility we can call it
`map-insert!'

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

I can see a use for it when dealing with both plists and alists and
not wanting to worry about the differences. hash-tables are a natural
extension, but arrays are not.

    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.

    Augusto> I'd have to search bug-gnu-emacs to remember.  It's all in there
    Augusto> 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

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

They might, but in my opinion `map-insert' should not.

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

Yes, as it currently works itʼs a bit useless.

Robert
--