Re: maphash: improve docstring

[Stefan Monnier <monnier@iro.umontreal.ca>]

> Docstring for `maphash' doesn't give any answer to the following
> question: is the callback FUNCTION allowed to access the hash
> table in read mode (I guess yes) and write mode?  About the
> latter I have no idea without studying internal implementation.

> E.g., is the following code going to work as a way to filter a
> hash table?

Yes, you are allowed to modify the table while iterating over it and the
resulting behavior should be sane.

And it should have the usual desired properties: The set of elements
passed to the function is a superset of all the elements that aren't
removed during the iteration, and a subset of all the elements that were
present at the beginning or added during the loop.  IOW if an entry is
untouched during the loop, then it will be passed (exactly once) to the
function.  If an entry is added or removed during the loop, then maybe
it will be passed to the function, but maybe not.  And if an entry is
modified during the loop, then it will be passed to the function
(exactly once) and the value passed will be the one that happens to be
current when the function is called.


        Stefan