Re: map.el documentation

[Arash Esbati]

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.

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

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

and from `map-put!':

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

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

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

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

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

Is this the intended behavior?

Best, Arash