From: Alexey Radul <axch@mit.edu>
Date: Tue, 24 May 2011 22:39:06 +0000 (+0100)
Subject: Documenting hash-table/modify! and hash-table/intern!.  Also slightly
X-Git-Tag: release-9.2.0~194^2~14
X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=2d66cdcf780c0276728fe62d8e52926516211911;p=mit-scheme.git

Documenting hash-table/modify! and hash-table/intern!.  Also slightly
reworded the introduction to hash-table/lookup, to make it more
positive.
---

diff --git a/doc/ref-manual/associations.texi b/doc/ref-manual/associations.texi
index 582a25013..1fc9ddc02 100644
--- a/doc/ref-manual/associations.texi
+++ b/doc/ref-manual/associations.texi
@@ -638,9 +638,9 @@ Returns an unspecified result.  @var{Procedure} must not modify
 @code{hash-table/remove!} to remove the association being processed.
 @end deffn
 
-The following procedure is an alternate form of @code{hash-table/get}
-that is useful in some situations.  Usually, @code{hash-table/get} is
-preferable because it is faster.
+The following procedure is a more general form of
+@code{hash-table/get}.  In circumstances where it is adequate,
+@code{hash-table/get} is usually preferable because it is faster.
 
 @deffn procedure hash-table/lookup hash-table key if-found if-not-found
 @var{If-found} must be a procedure of one argument, and
@@ -654,6 +654,31 @@ the invoked procedure, i.e.@: calls it tail-recursively).  The average
 time required by this operation is bounded by a constant.
 @end deffn
 
+The following procedures capture some common use patterns of hash
+tables that can be accelerated by dedicated operations.
+
+@deffn procedure hash-table/modify! hash-table key procedure default
+@var{Procedure} must be a procedure of one argument.  Calls
+@var{procedure} on the datum associated with @var{key} in
+@var{hash-table} (or on @var{default} if there is no association for
+@var{key}), associates the result with @var{key}, and returns that
+same result.  @var{Procedure} must not modify @var{hash-table}.  Note:
+if @var{hash-table} is address-hashed (@pxref{Address Hashing}) or
+holds keys weakly @var{procedure} must not access @var{hash-table}
+either, because in these circumstances an access can trigger a
+deferred modification.
+@end deffn
+
+@deffn procedure hash-table/intern! hash-table key get-default
+@var{Get-default} must be a procedure of no arguments.  Ensures that
+@var{hash-table} has an association for @var{key} and returns the
+associated datum.  If @var{hash-table} did not have an association for
+@var{key}, invokes @var{get-default} on no arguments, associates the
+result with @var{key} in @var{hash-table}, and returns it.  As with
+@code{hash-table/modify!}, @var{get-default} must not modify
+@var{hash-table}.
+@end deffn
+
 @node Resizing of Hash Tables, Address Hashing, Basic Hash Table Operations, Hash Tables
 @subsection Resizing of Hash Tables