Re: map.el documentation

[Robert Pluim]

>>>>> On Thu, 23 Jan 2025 12:40:32 +0100, Arash Esbati <arash@gnu.org> said:

    Arash> Eli Zaretskii <eliz@gnu.org> writes:
    >> The doc string never says map-insert should replace any existing alist
    >> elements.  Perhaps that is what you expected, based on some mental
    >> model of the internal implementation details, but it was not promised
    >> by the doc string.

    Arash> My expectation was fed by this part of `map-insert' docstring:

    Arash>   Return a new map like MAP except that it associates KEY with VALUE.
    Arash>   This does not modify MAP.
    Arash>   If you want to insert an element in place, use ‘map-put!’.

    Arash> and from `map-put!':

    Arash>   Associate KEY with VALUE in MAP.
    Arash>   If KEY is already present in MAP, replace the associated value
    Arash>   with VALUE.
    Arash>   This operates by modifying MAP in place.
    Arash>   If it cannot do that, it signals a ‘map-not-inplace’ error.
    Arash>   To insert an element without modifying MAP, use ‘map-insert’.

    Arash> My understanding was basically: `map-insert' and `map-put!' do the 
same
    Arash> thing, the former via a non-destructive, the latter in a destructive
    Arash> way, but this seems to be wrong.

Thatʼs how (setf (a/plist-get ....)) works, yes.

I could argue thatʼs a bug in the `list' method for `map-insert', it
conses the new key/value onto the map, when it could just use the
default method which does `map-put!' on a copy of the map.

The only in-house usage of `map-insert' is in ert.el. I donʼt think
making `map-insert' update an existing mapping would break anything
there, but itʼs probably too late to change it now.

    Arash> The return value of `map-insert' is different for alist and 
hash-tables
    Arash> (thanks to Robert P. for raising this):

    Arash> (map-insert '((y . 2) (x . 1)) 'x 3)
    Arash> => ((x . 3) (y . 2) (x . 1))

    Arash> (map-insert #s(hash-table data (y 2 x 1)) 'x 3)
    Arash> => #s(hash-table data (y 2 x 3))

In what way is it different? They both return a map where (map-elt map
'x) returns 3.

Robert
--