Merge remote-tracking branch 'johnwcowan/master'

1 files changed, 72 insertions, 71 deletions

diff --git a/srfi-225.html b/srfi-225.html
index 9665e87..2d4f504 100644
--- a/srfi-225.html
+++ b/srfi-225.html
@@ -145,85 +145,86 @@ with other generic procedures, but it can have any value.</p>
 returns <code>#f</code>.</p>
 <h3 id="update-procedures">Update procedures</h3>
 <p>Note that the following procedures apply to both pure and impure
-dictionaries (see <a href="#dict-purep"><code>dict-pure?</code></a>).  The <code>!</code>
-convention is not used in this SRFI.</p>
+dictionaries (see <a href="#dict-purep"><code>dict-pure?</code></a>).
+Their names uniformly end in <code>!</code> even though
+it depends on the dictionary whether any mutation is done.</p>
 <p>Updates are not permitted while any generic procedure that takes a procedure argument is running.</p>
-<p><code>(dict-set</code>&nbsp;<em>dto dict obj</em> …<code>)</code><br>
+<p><code>(dict-set!</code>&nbsp;<em>dto dict obj</em> …<code>)</code><br>
 <p>Returns a dictionary that contains all the associations of <em>dict</em>
   plus those specified by <em>objs</em>, which alternate between keys and values.
   If a key to be added already exists in <em>dict</em>, the new value prevails.</p>
-<blockquote><pre> (dict-set dto dict 7 8) &rArr;
+<blockquote><pre> (dict-set! dto dict 7 8) &rArr;
    ((1 . 2) (3 . 4) (5 . 6) (7 . 8)))
-(dict-set dto dict 3 5) &rArr;
+(dict-set! dto dict 3 5) &rArr;
    ((3 . 5) (1 . 2) (5 . 6)))</pre></blockquote>
-<p><code>(dict-adjoin</code>&nbsp;<em>dto dict obj</em> ...<code>)</code><br>
+<p><code>(dict-adjoin!</code>&nbsp;<em>dto dict obj</em> ...<code>)</code><br>
 <p>Returns a dictionary that contains all the associations of <em>dict</em>
   plus those specified by <em>objs</em>, which alternate between keys and values.
   If a key to be added already exists in <em>dict</em>, the old value prevails.</p>
-<blockquote><pre> (dict-adjoin dto dict 7 8) &rArr;
+<blockquote><pre> (dict-adjoin! dto dict 7 8) &rArr;
   ((7 . 8) (1 . 2) (3 . 4) (5 . 6))
-(dict-adjoin dto dict 3 5) &rArr;
+(dict-adjoin! dto dict 3 5) &rArr;
   ((1 . 2) (3 . 4) (5 . 6))</pre></blockquote>
-<p><code>(dict-delete</code>&nbsp;<em>dto dict key</em> …<code>)</code></p>
+<p><code>(dict-delete!</code>&nbsp;<em>dto dict key</em> …<code>)</code></p>
 <p>Returns a dictionary that contains all the associations of <em>dict</em>
   except those whose keys are the same as one of the <em>keys</em>.
-<blockquote><pre>(dict-delete dto dict 1 3) &rArr;
+<blockquote><pre>(dict-delete! dto dict 1 3) &rArr;
   ((5 . 6))
-(dict-delete dto dict 5) &rArr;
+(dict-delete! dto dict 5) &rArr;
   ((1 . 2) (3 . 4))</pre></blockquote>
-<p><code>(dict-delete-all</code>&nbsp;<em>dto dict keylist</em><code>)</code></p>
-<p>The same as <code>dict-delete</code>, except that the keys to be deleted are in the list <em>keylist</em>.</p>
-<blockquote><pre>(dict-delete-all dto dict '(1 3)) &rArr; ((5 . 6))</pre></blockquote>
-<p><code>(dict-replace</code>&nbsp;<em>dto dict key value</em><code>)</code></p>
+<p><code>(dict-delete!-all!</code>&nbsp;<em>dto dict keylist</em><code>)</code></p>
+<p>The same as <code>dict-delete!</code>, except that the keys to be deleted are in the list <em>keylist</em>.</p>
+<blockquote><pre>(dict-delete!-all! dto dict '(1 3)) &rArr; ((5 . 6))</pre></blockquote>
+<p><code>(dict-replace!</code>&nbsp;<em>dto dict key value</em><code>)</code></p>
 <p>Returns a dictionary that contains all the associations of <em>dict</em> except as follows:
 If <em>key</em> is the same as a key of <em>dict</em>,
   then the association for that key is omitted and replaced by the association
   defined by the pair <em>key</em> and <em>value</em>.
 If there is no such key in <em>dict</em>, then dictionary is returned unchanged.</p>
-<blockquote><pre>(dict-replace dto dict 1 3) &rArr;
+<blockquote><pre>(dict-replace! dto dict 1 3) &rArr;
   ((1 . 3) (3 . 4) (5 . 6))) </pre></blockquote>
-<p><code>(dict-intern</code>&nbsp;<em>dto dict key failure</em>)</p>
+<p><code>(dict-intern!</code>&nbsp;<em>dto dict key failure</em>)</p>
 <p>If there is a key in <em>dict</em> that is the same as <em>key</em>, returns two values,
   <em>dict</em> and the value associated with <em>key</em>.
 Otherwise, returns two values, a dictionary that contains
   all the associations of <em>dict</em> and in addition a new association that maps <em>key</em>
   to the result of invoking <em>failure</em>, and the result of invoking <em>failure</em>.<br>
-<blockquote><pre>(dict-intern dto dict 1 (lambda () #f)) &rArr; ; 2 values
+<blockquote><pre>(dict-intern! dto dict 1 (lambda () #f)) &rArr; ; 2 values
   ((1 . 2) (3 . 4) (5 . 6))
   2
-(dict-intern dto dict 2 (lambda () 0)) &rArr; ; 2 values
+(dict-intern! dto dict 2 (lambda () 0)) &rArr; ; 2 values
   ((1 . 2) (2 . 0) (3 . 4) (5 . 6))
   0</pre></blockquote>
-<p><code>(dict-update</code>&nbsp;<em>dto dict key updater</em> [<em>failure</em> [<em>success</em>] ]<code>)</code></p>
-<p>Retrieves the value of <em>key</em> as if by <code>dict-ref</code>, invokes <em>updater</em> on it, and sets the value of <em>key</em> to be the result of calling <em>updater</em> as if by <code>dict-set</code>, but may do so more efficiently. Returns the updated dictionary. The default value of <em>failure</em> signals an error; the default value of <em>success</em> is the identity procedure.</p>
+<p><code>(dict-update!</code>&nbsp;<em>dto dict key updater</em> [<em>failure</em> [<em>success</em>] ]<code>)</code></p>
+<p>Retrieves the value of <em>key</em> as if by <code>dict-ref</code>, invokes <em>updater</em> on it, and sets the value of <em>key</em> to be the result of calling <em>updater</em> as if by <code>dict-set!</code>, but may do so more efficiently. Returns the updated dictionary. The default value of <em>failure</em> signals an error; the default value of <em>success</em> is the identity procedure.</p>
 <blockquote><pre>
-(dict-update dto dict 1 (lambda (x) (+ 1 x))) &rArr;
+(dict-update! dto dict 1 (lambda (x) (+ 1 x))) &rArr;
   ((1 . 3) (3 . 4) (5 . 6))
-(dict-update dto dict 2 (lambda (x) (+ 1 x))) &rArr;
+(dict-update! dto dict 2 (lambda (x) (+ 1 x))) &rArr;
   <em>error</em>
 </pre></blockquote>
-<p><code>(dict-update/default</code>&nbsp;<em>dto dict key updater default</em><code>)</code></p>
+<p><code>(dict-update!/default!</code>&nbsp;<em>dto dict key updater default</em><code>)</code></p>
 <p>Retrieves the value of <em>key</em> as if by <code>dict-ref/default</code>, invokes <em>updater</em> on it,
-  and sets the value of <em>key</em> to be the result of calling <em>updater</em> as if by <code>dict-set</code>,
+  and sets the value of <em>key</em> to be the result of calling <em>updater</em> as if by <code>dict-set!</code>,
   but may do so more efficiently. Returns the updated dictionary.</p>
 <blockquote><pre>
-(dict-update/default dto dict 1 (lambda (x) (+ 1 x)) 0) &rArr;
+(dict-update!/default! dto dict 1 (lambda (x) (+ 1 x)) 0) &rArr;
   ((1 . 3) (3 . 4) (5 . 6))
-(dict-update/default dto dict 2 (lambda (x) (+ 1 x)) 0) &rArr;
+(dict-update!/default! dto dict 2 (lambda (x) (+ 1 x)) 0) &rArr;
   ((2 . 1) (3 . 4) (5 . 6))
 </pre></blockquote>
-<p><code>(dict-pop</code>&nbsp;<em>dto dict</em><code>)</code></p>
+<p><code>(dict-pop!</code>&nbsp;<em>dto dict</em><code>)</code></p>
 <p>Chooses an association from <em>dict</em> and returns three values:
   a dictionary that contains all associations of <em>dict</em> except the chosen one,
   the key, and the value of the association chosen.
   If the dictionary is inherently ordered, the first association is chosen;
   otherwise, the chosen association is arbitrary.</p>
 <p>If <em>dict</em> contains no associations, it is an error.</p>
-<blockquote><pre>(dict-pop dto dict) &rArr; ; 3 values
+<blockquote><pre>(dict-pop! dto dict) &rArr; ; 3 values
   ((3 . 4) (5 . 6))
   1
   2</pre></blockquote>
-<p><code>(dict-find-update</code>&nbsp;<em>dto dict key failure success</em><code>)</code></p>
+<p><code>(dict-find-update!</code>&nbsp;<em>dto dict key failure success</em><code>)</code></p>
 <p>This procedure is a workhorse for dictionary lookup, insert, and delete.
   The dictionary <em>dict</em> is searched for an association whose key is the same as <em>key</em>.
   If one is not found, then the <em>failure</em> procedure is tail-called with two procedure arguments,
@@ -348,12 +349,12 @@ key <em>key</em>.
   if the dictionary is ordered.</p>
   <p>It is an error to mutate <em>dict</em> until after the generator is exhausted.
   When all the associations have been processed, returns an end-of-file object.</p>
-  <p><code>(dict-set-accumulator</code>&nbsp;<em>dto dict</em><code>)</code></p>
+  <p><code>(dict-set!-accumulator</code>&nbsp;<em>dto dict</em><code>)</code></p>
 <p>Returns a SRFI 158 accumulator procedure that, when invoked on a pair, adds the <code>car</code> and <code>cdr</code> of the pair
-  as a key and value of <em>dict</em> as if by <code>dict-set</code>, eventually returning the new value of <em>dict</em>.
+  as a key and value of <em>dict</em> as if by <code>dict-set!</code>, eventually returning the new value of <em>dict</em>.
   If invoked on an end-of-file object, no action is taken and <em>dict</em> is returned.</p>
-<p><code>(dict-adjoin-accumulator</code>&nbsp;<em>dto dict</em><code>)</code></p>
-<p>The same as <code>dict-set-accumulator</code>, except using <code>dict-adjoin</code>. </p>
+<p><code>(dict-adjoin!-accumulator</code>&nbsp;<em>dto dict</em><code>)</code></p>
+<p>The same as <code>dict-set!-accumulator</code>, except using <code>dict-adjoin!</code>. </p>
 <h3 id="dictionary-type-object-procedures">Dictionary type object procedures (non-generic)</h3>
 <p><code>(dto?</code>&nbsp;<em>obj</em><code>)</code></p>
 <p>Returns <code>#t</code> if <em>obj</em> is a DTO, and <code>#f</code> otherwise.</p>
@@ -368,7 +369,7 @@ The following proc-id variables and associated procedures need to be provided
   in order for the DTO to support the full set of dictionary procedures:</p>
 <ul>
 <li><code>dictionary?-id</code></li>
-<li><code>dict-find-update-id</code></li>
+<li><code>dict-find-update!-id</code></li>
 <li><code>dict-comparator-id</code></li>
 <li><code>dict-map-id</code></li>
 <li><code>dict-pure?-id</code></li>
@@ -381,38 +382,38 @@ The following proc-id variables and associated procedures need to be provided
 <p>There are additional proc-id variables that may be provided with corresponding procedures
   in order to increase efficiency.
   For example, it is not necessary to provide a <code>dict-ref</code> procedure,
-  because the default version is built on top of <code>dict-find-update</code>.
+  because the default version is built on top of <code>dict-find-update!</code>.
   But if the underlying dictionary provides its own <code>-ref</code> procedure,
   it may be more efficient to specify it to <code>make-dto</code> using <code>dict-ref-id</code>.
   Here is the list of additional proc-id variables:</p>
 <ul>
 <li><code>dict-&gt;alist-id</code></li>
-<li><code>dict-adjoin-accumulator-id</code></li>
-<li><code>dict-adjoin-id</code></li>
+<li><code>dict-adjoin!-accumulator-id</code></li>
+<li><code>dict-adjoin!-id</code></li>
 <li><code>dict-any-id</code></li>
 <li><code>dict-contains?-id</code></li>
 <li><code>dict-count-id</code></li>
-<li><code>dict-delete-all-id</code></li>
-<li><code>dict-delete-id</code></li>
+<li><code>dict-delete!-all!-id</code></li>
+<li><code>dict-delete!-id</code></li>
 <li><code>dict-empty?-id</code></li>
 <li><code>dict-entries-id</code></li>
 <li><code>dict-every-id</code></li>
 <li><code>dict-filter-id</code></li>
 <li><code>dict-fold-id</code></li>
 <li><code>dict-for-each-id</code></li>
-<li><code>dict-intern-id</code></li>
+<li><code>dict-intern!-id</code></li>
 <li><code>dict-keys-id</code></li>
 <li><code>dict-map-&gt;list-id</code></li>
 <li><code>dict-map-id</code></li>
-<li><code>dict-pop-id</code></li>
+<li><code>dict-pop!-id</code></li>
 <li><code>dict-ref-id</code></li>
 <li><code>dict-ref/default-id</code></li>
 <li><code>dict-remove-id</code></li>
-<li><code>dict-replace-id</code></li>
-<li><code>dict-set-accumulator-id</code></li>
-<li><code>dict-set-id</code></li>
-<li><code>dict-update-id</code></li>
-<li><code>dict-update/default-id</code></li>
+<li><code>dict-replace!-id</code></li>
+<li><code>dict-set!-accumulator-id</code></li>
+<li><code>dict-set!-id</code></li>
+<li><code>dict-update!-id</code></li>
+<li><code>dict-update!/default!-id</code></li>
 <li><code>dict-values-id</code></li>
 <li><code>dict=?-id</code></li>
 <li><code>dict-&gt;generator-id</code></li>
@@ -462,44 +463,44 @@ new dictionary types that may not have complete dictionary APIs:</p>
 
     <dt><code>dict-ref</code></dt>
     <dd><code>dict-pure?</code></dd>
-    <dd><code>dict-find-update</code></dd>
+    <dd><code>dict-find-update!</code></dd>
 
     <dt><code>dict-ref/default</code></dt>
     <dd><code>dict-ref</code></dd>
 
-    <dt><code>dict-set</code></dt>
-    <dd><code>dict-find-update</code></dd>
+    <dt><code>dict-set!</code></dt>
+    <dd><code>dict-find-update!</code></dd>
 
-    <dt><code>dict-adjoin</code></dt>
-    <dd><code>dict-find-update</code></dd>
+    <dt><code>dict-adjoin!</code></dt>
+    <dd><code>dict-find-update!</code></dd>
 
-    <dt><code>dict-delete</code></dt>
-    <dd><code>dict-delete-all</code></dd>
+    <dt><code>dict-delete!</code></dt>
+    <dd><code>dict-delete!-all!</code></dd>
 
-    <dt><code>dict-delete-all</code></dt>
-    <dd><code>dict-find-update</code></dd>
+    <dt><code>dict-delete!-all!</code></dt>
+    <dd><code>dict-find-update!</code></dd>
 
-    <dt><code>dict-replace</code></dt>
-    <dd><code>dict-find-update</code></dd>
+    <dt><code>dict-replace!</code></dt>
+    <dd><code>dict-find-update!</code></dd>
 
-    <dt><code>dict-intern</code></dt>
-    <dd><code>dict-find-update</code></dd>
+    <dt><code>dict-intern!</code></dt>
+    <dd><code>dict-find-update!</code></dd>
 
-    <dt><code>dict-update</code></dt>
-    <dd><code>dict-find-update</code></dd>
+    <dt><code>dict-update!</code></dt>
+    <dd><code>dict-find-update!</code></dd>
 
-    <dt><code>dict-update/default</code></dt>
-    <dd><code>dict-update</code></dd>
+    <dt><code>dict-update!/default!</code></dt>
+    <dd><code>dict-update!</code></dd>
 
-    <dt><code>dict-pop</code></dt>
+    <dt><code>dict-pop!</code></dt>
     <dd><code>dict-for-each</code></dd>
-    <dd><code>dict-delete-all</code></dd>
+    <dd><code>dict-delete!-all!</code></dd>
     <dd><code>dict-empty?</code></dd>
 
     <dt><code>dict-filter</code></dt>
     <dd><code>dict-keys</code></dd>
     <dd><code>dict-ref</code></dd>
-    <dd><code>dict-delete-all</code></dd>
+    <dd><code>dict-delete!-all!</code></dd>
 
     <dt><code>dict-remove</code></dt>
     <dd><code>dict-filter</code></dd>
@@ -534,11 +535,11 @@ new dictionary types that may not have complete dictionary APIs:</p>
     <dt><code>dict-&gt;generator</code></dt>
     <dd><code>dict-for-each</code></dd>
 
-    <dt><code>dict-set-accumulator</code></dt>
-    <dd><code>dict-set</code></dd>
+    <dt><code>dict-set!-accumulator</code></dt>
+    <dd><code>dict-set!</code></dd>
 
-    <dt><code>dict-adjoin-accumulator</code></dt>
-    <dd><code>dict-set</code></dd>
+    <dt><code>dict-adjoin!-accumulator</code></dt>
+    <dd><code>dict-set!</code></dd>
 </dl>
 
 <h2 id="acknowledgements">Acknowledgements</h2>