From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Paul Pogonyshev Newsgroups: gmane.emacs.devel Subject: Re: maphash: improve docstring Date: Tue, 29 Mar 2016 20:58:24 +0200 Message-ID: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: ger.gmane.org 1459277956 32429 80.91.229.3 (29 Mar 2016 18:59:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 29 Mar 2016 18:59:16 +0000 (UTC) To: emacs-devel@gnu.org, Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Mar 29 20:59:16 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1akyrE-00088k-61 for ged-emacs-devel@m.gmane.org; Tue, 29 Mar 2016 20:59:16 +0200 Original-Received: from localhost ([::1]:49305 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1akyrD-0002Cd-7L for ged-emacs-devel@m.gmane.org; Tue, 29 Mar 2016 14:59:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36663) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1akyr0-0002Aj-BU for emacs-devel@gnu.org; Tue, 29 Mar 2016 14:59:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1akyqz-0002rY-El for emacs-devel@gnu.org; Tue, 29 Mar 2016 14:59:02 -0400 Original-Received: from mail-ob0-x22a.google.com ([2607:f8b0:4003:c01::22a]:34001) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1akyqz-0002rO-B2 for emacs-devel@gnu.org; Tue, 29 Mar 2016 14:59:01 -0400 Original-Received: by mail-ob0-x22a.google.com with SMTP id kf9so22211049obc.1 for ; Tue, 29 Mar 2016 11:59:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:date:message-id:subject:from:to; bh=FHPmdZvOxtTBkafSiEuiS7Cy0tvelULbI1fWgfWE778=; b=dZ0C9PqmXIz5azz8Mx52jGYQ9WSL8MxyKxgpxHhUuq5rsICtnW0Dtc7PDIJE3p7Hrt 8YEKIMJMPUiliWd4vd8E84C9Rqmgry7R6ZGgPDgJUZuIvx07oOFWVg94YycwF8cXQOkz K2nmd/6v8KlnYdYUA/mfx5JkW7vL5RN3kzDXFwpXp2Rm21M1ZlVTUh/xcDVlEfiLsxm7 nF0oHOa46666vUse+9xeMKu6PKXRHQ1qEoCkLjWptAx9Y0v0qLI/2VKyFnDA5nHdy+sU 9XjY+vwlm7qVVJZg28H4Pwck/NLWc33qSFJ1ZqkBe9Ct3ZsooMeNAfEpTfDYI6LHNWUU 88cg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:date:message-id:subject:from:to; bh=FHPmdZvOxtTBkafSiEuiS7Cy0tvelULbI1fWgfWE778=; b=k1bX62obywIus4PV3Qr0sW/OaO9T7GSwQPrCKwItjcOZMJzS1r7nTXQgWqFtbt3lIr Y2WRba0kPdCMPoLteHFZO3TS55OG2tLrB7aAHPENconA6El+GKciK6SGVe2TZEVrL/Hj uF6pV+OPwiMWPMh5XFY9CvOuQLeg+PgVsZcBT88rjcYdQSbJAFDclPPLxUeA9BE7HD42 KoqtIpIMY1KEgdfFv+Y1B8HGLHtRtqjThUUvH4opXBNXqmqaujaiu9aKuQBhnizU4gPj CP+LeR6Dp2GPyKqxPMRt1YUhkit4PJBubiBEhmvpGtMbwiEIqW8x+JxhlNaSlibZOyXw S4Jg== X-Gm-Message-State: AD7BkJIMFvSTCfrX5U1c5SbEqPWzr9JVIjnokZr3NHk+2/1CiRHq47zKuKZPXa/wSe+77DcGmchlo7cCLv+ruA== X-Received: by 10.202.215.86 with SMTP id o83mr2144096oig.55.1459277904600; Tue, 29 Mar 2016 11:58:24 -0700 (PDT) Original-Received: by 10.202.197.148 with HTTP; Tue, 29 Mar 2016 11:58:24 -0700 (PDT) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:4003:c01::22a X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:202412 Archived-At: [I didn't receive the answer because I wasn't subscribed to the list, so the thread will be broken] > > 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. > > More specifically, you're guaranteed when entering the function that the > key you've received does currently exist in the table and is currently > associated with the value you just received. Could one expand documentation of `maphash' like this? I'm not sure it follows from what you wrote, but I understood it like this: Call FUNCTION for all entries in hash table TABLE. FUNCTION is called with two arguments, KEY and VALUE. `maphash' always returns nil. FUNCTION will usually just inspect its arguments, but may also alter TABLE and this will not cause `maphash' to malfunction. However, some effects are not fully defined, see below. If FUNCTION adds an entry to TABLE, it may or may not be called with the added key/value pair. If FUNCTION changes value already associated with a key and it has not been called with that key yet, it will be called with key and the new value during the iteration later. Otherwise it will not be called for that key again. If FUNCTION removes a key and it has not been called with it yet, it will not be called for the removed key in the future either. Note that if FUNCTION removes or changes value only for KEY it is called with, the behavior is completely defined. Another option is to add this (probably with more explanation) to the manual and add just a sentence to the tune of "see manual for details" to the docstring. Paul