diff options
| author |  John Cowan
| 2021-10-04 18:08:24 -0400 |
|---|---|---|
| committer | John Cowan
| 2021-10-04 18:08:24 -0400 |
| commit | 87d1c10b3e7d20a2dc90965f9a9c3157e6a696e3 (patch) | |
| tree | 91bb277f9e05593abcdf9011d45ae381644748b4 | |
| parent | starting draft 3 (diff) | |
draft 4
| -rw-r--r-- | srfi-225.html | 410 |
1 files changed, 189 insertions, 221 deletions
diff --git a/srfi-225.html b/srfi-225.html index c2ebc0c..148bcc2 100644 --- a/srfi-225.html +++ b/srfi-225.html @@ -29,42 +29,32 @@ <p>The procedures of this SRFI allow callers to manipulate an object that maps keys to values without the caller needing to know exactly what the type -of the object is. Such an object is called a <em>dictionary</em> in this SRFI.</p> +of the object is. Such an object is called a <em>dict</em> in this SRFI.</p> <h2 id="issues">Issues</h2> -<p>dict=?, dict<?, etc. Compare dictionaries for equality, subset, etc. -A value comparator is passed in.</p> - -<p>dict-union(!), dict-intersection(!), dict-difference(!), dict-xor(!).</p> - -<p>dict-range=(!), dict-range<(!), etc. Return subsets whose keys are =, <, etc. -of a provided value.</p> - -<p>dict-open-mapping, dict-closed mapping, dict-open-closed-mapping, dict-closed-open-mapping. -Returns subsets whose keys are in a certain interval specified by upper and lower bounds.</p> - -<p>dict-min-key, dict-max-key: Returns the smallest and largest key in the dictionary.</p> - -<p>dict-key-successor, dict-key-predecessor: Return preceding and following key.</p> +<p>dict-key-successor, dict-key-predecessor: Return preceding and following key. +This is dependent on having easy access to these operations in ordered dictionaries: +it would be very expensive to provide dict-max-key on top of an ordered dictionary +that does not provide it, or either procedure on top of an unordered dictionary.</p> <h2 id="rationale">Rationale</h2> <p>Until recently there was only one universally available mechanism for managing key-value pairs: alists. Most Schemes also support hash tables, but until R6RS there was no standard interface to them, and many implementations do not provide that interface.</p> -<p>Now, however, the number of such mechanisms is growing. In addition to both R6RS and R7RS hash tables, there are persistent ordered and hashed mappings from SRFI 146 and ordered key-value stores (often on a disk or a remote machine) from SRFI 167.</p> +<p>Now, however, the number of such mechanisms is growing. In addition to both R6RS and R7RS hash tables, there are R7RS persistent ordered and hashed mappings from SRFI 146, ordered mappings with fixnum keys from SRFI 224, and ordered key-value stores (often on a disk or a remote machine) from SRFI 167.</p> <p>It’s inconvenient for users if SRFIs or other libraries have to insist on accepting only a specific type of dictionary. This SRFI exposes a number of accessors, mutators, and other procedures that can be called on any dictionary, provided that a <em>dictionary type descriptor</em> (DTD, with apologies to SGML and XML users) is available for it: either exported from this SRFI, or from other SRFIs or libraries, or created by the user. DTDs are of an unspecified type.</p> -<p>This in turn requires that the DTD provides a predicate that can recognize its dictionaries, plus at least these primitive operations: determine a dictionary’s current size; reference, update, or insert an element of the dictionary depending on its current contents; process all the elements using a procedure invoked for its side effects; and return the comparator of the dictionary or <code>#f</code> if none was provided when the dictionary was created.</p> +<p>This in turn requires that the DTD provides a predicate that can recognize its dictionaries, plus several primitive operations, such as determining a dictionary’s current size; referencing, updating, removing, or inserting an element of the dictionary depending on its current contents; processing all the elements using a procedure invoked for its side effects.</p> <p>By using the procedures of this SRFI, a procedure can take a DTD and a dictionary as an argument and make flexible use of the dictionary without knowing its exact type. For the purposes of this SRFI, such a procedure is called a <em>generic procedure</em>.</p> -<p>However, dictionaries need to be constructed using type-specific constructors, as the required and optional arguments differ in each case. In addition, the dictionary type provided by the caller of a generic procedure doesn't necessarily have the right performance characteristics needed by the generic procedure itself. Consequently there are no <code>make-dict</code>, <code>dict</code>, <code>dict-unfold</code>, <code>dict-copy</code> or similar procedures in this SRFI; by the same token, there are no <code>dict-map</code>, <code>dict-filter</code>, or <code>dict-remove</code> procedures either.</p> +<p>However, dictionaries need to be constructed using type-specific constructors, as the required and optional arguments differ in each case. In addition, the dictionary type provided by the caller of a generic procedure doesn't necessarily have the right performance characteristics needed by the generic procedure itself. Consequently there are no <code>make-dict</code>, <code>dict</code>, <code>dict-unfold</code>, <code>dict-copy</code> or similar procedures in this SRFI.</p> <h2 id="specification">Specification</h2> <p>We call a specific key-value combination an <em>association</em>. This is why an alist, or association list, is called that; it is a list of associations represented as pairs.</p> -<p>A <em>dictionary</em> is a collection of associations which may be ordered or unordered. In principle an <em>equality predicate</em> is enough, given a key, to find if an association with that key exists in the dictionary. However, for efficiency most dictionaries require an <em>ordering predicate</em> or a <em>hash function</em> as well. +<p>A <em>dict</em> is a collection of associations which may be ordered or unordered. In principle an <em>equality predicate</em> is enough, given a key, to find if an association with that key exists in the dictionary. However, for efficiency most dictionaries require an <em>ordering predicate</em> or a <em>hash function</em> as well. <p>When a key argument is said to be the same as some key of the dictionary, it means that they are the same in the sense of the dictionary’s implicit or explicit equality predicate. It is assumed that no dictionary contains two keys that are the same in this sense. Two dictionaries are <em>similar</em>g if they are of the same type and have the same equality predicate and the same ordering predicate and/or hash function.</p> <h3 id="lists-as-dictionaries">Lists as dictionaries</h3> <p>Lists are supported as dictionaries using the specification in this section. If two keys are the same (in the sense of the specified equality predicate), then all but the first are treated as if they did not exist.</p> <p>If <code>plist-dtd</code> (see below) is used with a list, then the list is assumed to be a property list, alternating symbol keys with values. Unlike the mutation operations provided by Common Lisp, plists are functionally updated. The equality predicate of this type of dictionary is <code>eq?</code>.</p> -<p>If a list is empty or its car is a pair, then the list can be treated as an alist. New values are added to the beginning of an alist and the new alist is returned; linear-update operations do not mutate the alist, but return an alist that may or may not share storage with the original alist. If an association has been updated, then both the new and the old association may be processed by the whole-dictionary procedures. The examples in this SRFI use alists.</p> +<p>If a list is empty or its car is a pair, then the list can be treated as an alist. New values are added to the beginning of the alist and the new alist is returned. If an association has been updated, then both the new and the old association may be processed by the whole-dictionary procedures. The examples in this SRFI use alists.</p> <p>However, an alist (unlike a hashtable or mapping) does not know which equality predicate its users intend to use on it. Therefore, rather than exporting a single DTD for all alists, this SRFI provides a procedure <code>make-alist-dtd</code> that takes an equality predicate and returns a DTD specialized for manipulation of alists using that predicate. For convenience, DTDs for <code>eqv?</code> and <code>equal?</code> are exported.</p> <p>In all other cases, lists cannot be treated as dictionaries unless a DTD has been written to handle them.</p> <h3>Procedures</h3> @@ -74,97 +64,123 @@ Two dictionaries are <em>similar</em>g if they are of the same type and have the </pre></blockquote> Consequently, previous examples don't affect later ones. <p>The <em>dtd</em> argument is not discussed in the individual procedure descriptions below, but it is an error if invoking <code>dictionary?</code> on <em>dtd</em> and <em>dict</em> returns <code>#f</code>.</p> -<h3 id="predicates">Predicates</h3> +<h4 id="predicates">Predicates</h4> <p><code>(dictionary?</code> <em>dtd obj</em><code>)</code></p> <p>Returns <code>#t</code> if <em>obj</em> answers <code>#t</code> to the type predicate stored in the DTD, and <code>#f</code> otherwise.</p> <blockquote><pre>(dictionary? aed dict) => #t</pre></blockquote> <p><code>(dict-empty?</code> <em>dtd dict</em><code>)</code></p> -<p>Returns <code>#t</code> if <em>dictionary</em> contains no associations and <code>#f</code> if it does contain associations.</p> +<p>Returns <code>#t</code> if <em>dict</em> contains no associations and <code>#f</code> if it does contain associations.</p> <blockquote><pre>(dict-empty? aed '()) => #t (dict-empty? aed dict) => #f</pre></blockquote> -<p><code>(dict-contains?</code> <em>dtd dictionary key</em><code>)</code></p> +<p><code>(dict-contains?</code> <em>dtd dict key</em><code>)</code></p> <blockquote><pre>(dict-contains? aed dict 1) => #t (dict-contains? aed dict 2) => #f</pre></blockquote> -<p>Returns <code>#t</code> if one of the keys of <em>dictionary</em> is the same as <em>key</em>, and <code>#f</code> otherwise.</p> -<p><code>(dictionary=?</code> <em>= dict1 dict2</em><code>)</code></p> -<p>Returns <code>#t</code> if the keys of <em>dict1</em> and <em>dict2</em> are the same, and the corresponding values are the same in the sense of the <em>=</em> argument.</p> +<p>Returns <code>#t</code> if one of the keys of <em>dict</em> is the same as <em>key</em>, and <code>#f</code> otherwise.</p> +<p><code>(dict=?</code> <em>dtd = dict1 dict2</em><code>)</code></p> +<p>Returns <code>#t</code> if the keys of <em>dtd dict1</em> and <em>dict2</em> are the same, and the corresponding values are the same in the sense of the <em>=</em> argument.</p> +<blockquote><pre> +(define dicta '((5 . 6) (3 . 4) (1 . 2)) +(define dictb '((1 . 2) (3 . 4)) +(dict=? aed dict dicta) => #t +(dict=? aed dict dictb) => #f</pre></blockquote> <p><code>(dict-mutable?</code> <em>dtd dict</em><code>)</code></p> -<p>Returns <code>#t</code> if the underlying dictionary type supports mutations and <code>#f</code> if it supports functional updates.</p> -<h3 id="lookup">Lookup</h3> -<p><code>(dict-ref</code> <em>dtd dictionary key</em> [<em>failure</em> [<em>success</em>] ]<code>)</code></p> -<p>If <em>key</em> is the same as some key of <em>dictionary</em>, then invokes <em>success</em> on the corresponding value and returns its result. If <em>key</em> is not a key of <em>dictionary</em>, then invokes the thunk <em>failure</em> and returns its result. The default value of <em>failure</em> signals an error; the default value of <em>success</em> is the identity procedure.</p> +<p>Returns <code>#t</code> if the dictionary type supports mutations and <code>#f</code> if it supports functional updates.</p> +<blockquote><pre> +(dict-mutable? hash-table-dtd (make-hash-table)) => #t +(dict-mutable? aed dict) =>#f +</pre></blockquote> +<h4 id="lookup">Lookup</h4> +<p><code>(dict-ref</code> <em>dtd dict key</em> [<em>failure</em> [<em>success</em>] ]<code>)</code></p> +<p>If <em>key</em> is the same as some key of <em>dict</em>, then invokes <em>success</em> on the corresponding value and returns its result. If <em>key</em> is not a key of <em>dict</em>, then invokes the thunk <em>failure</em> and returns its result. 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-ref aed dict 1 (lambda () '()) list) => (1) ; Success wraps value in a list (dict-ref aed dict 2 (lambda () '()) list) => () ; Failure returns empty list</pre></blockquote> -<p><code>(dict-ref/default</code> <em>dtd dictionary key default</em><code>)</code></p> -<p>If <em>key</em> is the same as some key of <em>dictionary</em> then returns the corresponding value. If not, then returns <em>default</em>.</p> +<p><code>(dict-ref/default</code> <em>dtd dict key default</em><code>)</code></p> +<p>If <em>key</em> is the same as some key of <em>dict</em> then returns the corresponding value. If not, then returns <em>default</em>.</p> <blockquote><pre>(dict-ref/default aed dict 1 #f) => 1 (dict-ref/default aed dict 1 #f) => #f</pre></blockquote> -<h3 id="mutation">Functional update and mutation</h3> +<p><code>dict-min-key</code> <em>dtd dict</em><code>)</code><br> +<code>dict-max-key</code> <em>dtd dict</em><code>)</code></p> +<p>Return the minimum/maximum key of <em>dict</em>.</p> +<blockquote><pre> +(dict-min-key aed dict) => 1 +(dict-max-key aed dict) => 5 +</pre></blockquote> +<h4 id="mutation">Functional update and mutation</h4> <p>All these procedures exist in pairs, with and without a final <code>!</code>. The ones without <code>!</code> are functional: they never side-effect their arguments, but the result may share structure with the <em>dict</em> argument. The ones with <code>!</code> are mutations: they they change the <em>dict</em> argument. However, only one set of procedures is supported in any dictionary: for example, SRFI 125 hash tables support only mutation, whereas SRFI 146 mappings support only functional update. The <code>dict-mutable?</code> procedure can be used to determine which set is usable.</p> -<p><code>(dict-set</code> <em>dtd dictionary obj</em> …<code>)</code><br> -<code>(dict-set!</code> <em>dtd dictionary obj</em> …<code>)</code></p> -<p>Returns a dictionary that contains all the associations of <em>dictionary</em> plus those specified by <em>objs</em>, which alternate between keys and values. If a key to be added already exists in <em>dictionary</em>, the new value prevails.</p> +<p><code>(dict-set</code> <em>dtd dict obj</em> …<code>)</code><br> +<code>(dict-set!</code> <em>dtd dict obj</em> …<code>)</code></p> +<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>; new values are prepended (dict-set aed dict 7 8) => ((7 . 8) (1 . 2) (3 . 4) (5 . 6)) (dict-set aed dict 3 5) => ((3 . 5) (1 . 2) (3 . 4) (5 . 6)</pre></blockquote> -<p><code>(dict-adjoin</code> <em>dtd dictionary objs</em><code>)</code><br> -<code>(dict-adjoin!</code> <em>dtd dictionary objs</em><code>)</code></p> -<p>Returns a dictionary that contains all the associations of <em>dictionary</em> plus those specified by <em>objs</em>, which alternate between keys and values. If a key to be added already exists in <em>dictionary</em>, the old value prevails.</p> +<p><code>(dict-adjoin</code> <em>dtd dict objs</em><code>)</code><br> +<code>(dict-adjoin!</code> <em>dtd dict objs</em><code>)</code></p> +<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>; new values are prepended to alists (dict-adjoin aed dict 7 8) => ((7 . 8) (1 . 2) (3 . 4) (5 . 6)) (dict-adjoin aed dict 3 5) => ((1 . 2) (3 . 4) (5 . 6)</pre></blockquote> -<p><code>(dict-delete</code> <em>dtd dictionary key</em> …<code>)</code><br> -<code>(dict-delete!</code> <em>dtd dictionary key</em> …<code>)</code></p> -<p>Returns a dictionary that contains all the associations of <em>dictionary</em> except those whose keys are the same as one of the <em>keys</em>.</p> +<p><code>(dict-delete</code> <em>dtd dict key</em> …<code>)</code><br> +<code>(dict-delete!</code> <em>dtd 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>.</p> <blockquote><pre>; new values are prepended (dict-delete aed dict 1 3) => ((5. 6)) ; may share (dict-delete aed dict 5) => ((1 . 2) (3 . 4)</pre></blockquote> -<p><code>(dict-delete-all</code> <em>dtd dictionary keylist</em><code>)</code><br> -<code>(dict-delete-all!</code> <em>dtd dictionary keylist</em><code>)</code></p> -<p>Returns a dictionary with all the associations of <em>dictionary</em> except those whose keys are the same as some member of <em>keylist</em>.</p> +<p><code>(dict-delete-all</code> <em>dtd dict keylist</em><code>)</code><br> +<code>(dict-delete-all!</code> <em>dtd dict keylist</em><code>)</code></p> +<p>Returns a dictionary with all the associations of <em>dict</em> except those whose keys are the same as some member of <em>keylist</em>.</p> <blockquote><pre>(dict-delete-all aed dict '(1 3)) => ((5 . 6))</pre></blockquote> -<p><code>(dict-replace</code> <em>dtd dictionary key value</em><code>)</code><br> -<code>(dict-replace!</code> <em>dtd dictionary key value</em><code>)</code></p> -<p>Returns a dictionary that contains all the associations of <em>dictionary</em> except as follows: If <em>key</em> is the same as a key of <em>dictionary</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>dictionary</em>, then dictionary is returned unchanged.</p> +<p><code>(dict-replace</code> <em>dtd dict key value</em><code>)</code><br> +<code>(dict-replace!</code> <em>dtd 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 aed dict 1 3) => ((1 . 3) (1 . 2) (3 . 4) (5 . 6)) </pre></blockquote> -<p><code>(dict-intern</code> <em>dtd dictionary key failure</em>)<br> -<code>(dict-intern!</code> <em>dtd dictionary key failure</em>)</p> -<p>If there is a key in <em>dictionary</em> that is the same as <em>key</em>, returns two values, <em>dictionary</em> and the value associated with <em>key</em>. -Otherwise, returns two values, a dictionary that contains all the associations of <em>dictionary</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> +<p><code>(dict-intern</code> <em>dtd dict key failure</em>)<br> +<code>(dict-intern!</code> <em>dtd 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 aed dict 1 (lambda () #f)) => ; 2 values ((1 . 2) (3 . 4) (5 . 6)) 3 (dict-intern aed dict 2 (lambda () #f)) => ; 2 values ((2 . #f) (1 . 2) (3 . 4) (5 . 6)) #f</pre></blockquote> -<p><code>(dict-update</code> <em>dtd dictionary key updater</em> [<em>failure</em> [<em>success</em>] ]<code>)</code><br> -<code>(dict-update!</code> <em>dtd dictionary key updater</em> [<em>failure</em> [<em>success</em>] ]<code>)</code></p> +<p><code>(dict-update</code> <em>dtd dict key updater</em> [<em>failure</em> [<em>success</em>] ]<code>)</code><br> +<code>(dict-update!</code> <em>dtd 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> -<code>(dict-update/default</code> <em>dtd dictionary key updater default</em><code>)</code><br> -<code>(dict-update/default!</code> <em>dtd dictionary key updater default</em><code>)</code></p> +<code>(dict-update/default</code> <em>dtd dict key updater default</em><code>)</code><br> +<code>(dict-update/default!</code> <em>dtd 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>, but may do so more efficiently. Returns the updated dictionary.</p> -<p><code>(dict-pop</code> <em>dtd dictionary</em><code>)</code><br> -<code>(dict-pop!</code> <em>dtd dictionary</em><code>)</code></p> -<p>Chooses an association from <em>dictionary</em> and returns three values: a dictionary that contains all associations of <em>dictionary</em> except the chosen one, and the key and the value of the association chosen. If the dictionary is ordered, the first association is chosen; otherwise the chosen association is arbitrary.</p> +<p><code>(dict-pop</code> <em>dtd dict</em><code>)</code><br> +<code>(dict-pop!</code> <em>dtd 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, and the key and the value of the association chosen. If the dictionary is ordered, the first association is chosen; otherwise the chosen association is arbitrary.</p> <p>If dictionary contains no associations, it is an error.</p> <blockquote><pre>(dict-pop aed dict) => # 3 values ((3 . 4) (5 . 6)) 1 2</pre></blockquote> -<p><code>(dict-alter</code> <em>dtd dictionary key failure success</em><code>)</code><br> -<code>(dict-alter!</code> <em>dtd dictionary key failure success</em><code>)</code></p> -<p>This procedure is a workhorse for dictionary lookup, insert, and delete. The dictionary <em>dictionary</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, <em>insert</em> and <em>ignore</em>.</p> +<p><code>(dict-map</code> <em>dtd proc dict</em><code>)</code><br> +<code>(dict-map!</code> <em>dtd proc dict</em><code>)</code></p> +<p>Returns a dictionary similar to <em>dict</em> that maps each key of <em>dict</em> to the value that results from invoking <em>proc</em> on the corresponding key and value of <em>dict</em>.</p> +<blockquote><pre>(dict-map (lambda (k v) (cons v k)) aed dict) => ((2 . 1) (4 . 3) (6 . 5))</pre></blockquote> +<blockquote><pre>(dict-map! (lambda (k v) (cons v k)) aed dict) => ((2 . 1) (4 . 3) (6 . 5))</pre></blockquote> +<p><code>(dict-filter</code> <em>dtd pred dict</em><code>)</code><br> +<code>(dict-filter!</code> <em>dtd pred dict</em><code>)</code><br> +<code>(dict-remove</code> <em>dtd pred dict</em><code>)</code><br> +<code>(dict-remove!</code> <em>dtd pred dict</em><code>)</code></p> +<p>Returns a dictionary similar to <em>dict</em> that contains just the associations of <em>dict</em> that satisfy / do not satisfy <em>pred</em> when it is invoked on the key and value of the association.</p> +<blockquote><pre>(dict-filter (lambda (k v) (= k 1)) aed dict) => ((1 . 2)) +(dict-remove (lambda (k) (= k 1)) aed dict) => ((3 . 4) (5 . 6))</pre></blockquote> +<p><code>(dict-alter</code> <em>dtd dict key failure success</em><code>)</code><br> +<code>(dict-alter!</code> <em>dtd 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, <em>insert</em> and <em>ignore</em>.</p> +<p>If such an association is found, then the <em>success</em> procedure is tail-called with the matching key of <em>dict</em>, the associated value, and two procedure arguments, <em>update</em> and <em>remove</em>.</p> <p>In either case, the values returned by <em>failure</em> or <em>success</em> are returned.</p> -<p>If such an association is found, then the <em>success</em> procedure is tail-called with the matching key of <em>dictionary</em>, the associated value, and two procedure arguments, <em>update</em> and <em>remove</em>.</p> -<p>It is an error if the procedure arguments are invoked other than in tail position in the <em>failure</em> and <em>success</em> procedures. It is also an error if the <em>failure</em> and <em>success</em> procedures return to their implicit continuation without invoking one of their arguments.</p> <p>The behaviors of the procedures are as follows (where <em>obj</em> is any Scheme object):</p> <ul> -<li><p>Invoking <code>(</code><em>insert value obj</em><code>)</code> returns a dictionary that contains all the associations of <em>dictionary</em>, and in addition a new association that maps <em>key</em> to <em>value</em>.</p></li> -<li><p>Invoking <code>(</code><em>ignore obj</em><code>)</code> has no effects and returns <em>dictionary</em> unchanged.</p></li> -<li><p>Invoking <code>(</code><em>update new-key new-value obj</em><code>)</code> returns a dictionary that contains all the associations of <em>dictionary</em>, except for the association whose key is the same as <em>key</em>, which is replaced or hidden by a new association that maps <em>new-key</em> to <em>new-value</em>. It is an error if <em>key</em> and <em>new-key</em> are not the same in the sense of the dictionary’s equality predicate.</p></li> -<li><p>Invoking <code>(</code><em>remove obj</em><code>)</code> returns a dictionary that contains all the associations of <em>dictionary</em>, except for the association with key key.</p></li> +<li><p>Invoking <code>(</code><em>insert value</em><code>)</code> returns a dictionary that contains all the associations of <em>dict</em>, and in addition a new association that maps <em>key</em> to <em>value</em>.</p></li> +<li><p>Invoking <code>(</code><em>ignore</em><code>)</code> has no effects and returns <em>dict</em> unchanged.</p></li> +<li><p>Invoking <code>(</code><em>update new-key new-value</em><code>)</code> returns a dictionary that contains all the associations of <em>dict</em>, except for the association whose key is the same as <em>key</em>, which is replaced or hidden by a new association that maps <em>new-key</em> to <em>new-value</em>. It is an error if <em>key</em> and <em>new-key</em> are not the same in the sense of the dictionary’s equality predicate.</p></li> +<li><p>Invoking <code>(</code><em>remove</em><code>)</code> returns a dictionary that contains all the associations of <em>dict</em>, except for the association with key key.</p></li> </ul> -<p>In all cases, <em>obj</em> is returned as a second value.</p> <p>Here are four examples of <code>dict-alter</code>, one for each of the four procedures: <blockquote><pre> @@ -173,23 +189,21 @@ one for each of the four procedures: (dict value) (dict-alter (alist->dict '((a . b))) 'c (lambda (insert ignore) - (ignore 'foo)) + (ignore)) (lambda args (error)))) (dict->alist aed dict)) => ((a . b)) - value => 'foo ;; insert (define-values (dict value) (dict-alter (alist->dict '((a . b))) 'c (lambda (insert ignore) - (insert 'd 'foo)) + (insert 'd)) (lambda args (error)))) (dict-ref aed dict 'a)) => b (dict-ref aed dict 'c)) => 'd - value => foo ;; update (define-values @@ -198,9 +212,8 @@ one for each of the four procedures: (lambda args (error)) (lambda (key value update delete) - (update 'a2 'b2 'foo)))) + (update 'a2 'b2)))) (dict->alist aed dict) => ((a2 . b2) - value => foo ;; delete (define-values @@ -209,177 +222,161 @@ one for each of the four procedures: (lambda args (error)) (lambda (key value update delete) - (delete 'foo)))) + (delete)))) (dict->alist aed dict)) => ((c . d)) - value => foo </pre></blockquote> -<h3 id="the-whole-dictionary">The whole dictionary</h3> -<p><code>(dict-size</code> <em>dtd dictionary</em><code>)</code></p> -<p>Returns an exact integer representing the number of associations in <em>dictionary</em>.</p> +<h4 id="the-whole-dictionary">The whole dictionary</h4> +<p><code>(dict-size</code> <em>dtd dict</em><code>)</code></p> +<p>Returns an exact integer representing the number of associations in <em>dict</em>.</p> <blockquote><pre>(dict-size aed dict) => 3</pre></blockquote> -<p><code>(dict-count</code> <em>dtd pred dictionary</em><code>)</code></p> +<p><code>(dict-count</code> <em>dtd pred dict</em><code>)</code></p> <p>Passes each association of dictionary as two arguments to <em>pred</em> and returns the number of times that <em>pred</em> returned true as an an exact integer.</p> <blockquote><pre>(dict-count aed dict (lambda (k v) (even? k))) => 0</pre></blockquote> -<p><code>(dict-any</code> <em>dtd pred dictionary</em><code>)</code></p> -<p>Passes each association of <em>dictionary</em> as two arguments to <em>pred</em> and returns the value of the first call to <em>pred</em> that returns true, after which no further calls are made. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. If all calls return false, <code>dict-any</code> returns false.</p> +<p><code>(dict-any</code> <em>dtd pred dict</em><code>)</code></p> +<p>Passes each association of <em>dict</em> as two arguments to <em>pred</em> and returns the value of the first call to <em>pred</em> that returns true, after which no further calls are made. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. If all calls return false, <code>dict-any</code> returns false.</p> <blockquote><pre>(define (both-even? k v) (and (even? k) (even? v))) (dict-any both-even? '((2 . 4) (3 . 5))) => #t (dict-any both-even? '((1 . 2) (3 . 4))) => #f</pre></blockquote> -<p><code>(dict-every</code> <em>dtd pred dictionary</em><code>)</code></p> -<p>Passes each association of <em>dictionary</em> as two arguments to <em>pred</em> and returns <code>#f</code> after the first call to <em>pred</em> that returns false, after which no further calls are made. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. If all calls return true, <code>dict-any</code> returns the value of the last call, or <code>#t</code> if no calls are made.</p> +<p><code>(dict-every</code> <em>dtd pred dict</em><code>)</code></p> +<p>Passes each association of <em>dict</em> as two arguments to <em>pred</em> and returns <code>#f</code> after the first call to <em>pred</em> that returns false, after which no further calls are made. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. If all calls return true, <code>dict-any</code> returns the value of the last call, or <code>#t</code> if no calls are made.</p> <blockquote><pre>(define (some-even? k v) (or (even? k) (even? v))) (dict-every some-even? '((2 . 3) (3 . 4))) => #t (dict-every some-even? '((1 . 3) (3 . 4))) => #f</pre></blockquote> -<p><code>(dict-keys</code> <em>dtd dictionary</em><code>)</code></p> -<p>Returns a list of the keys of <em>dictionary</em>. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. The order may change when new elements are added to <em>dictionary</em>.</p> +<p><code>(dict-keys</code> <em>dtd dict</em><code>)</code></p> +<p>Returns a list of the keys of <em>dict</em>. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. The order may change when new elements are added to <em>dict</em>.</p> <blockquote><pre>(dict-keys aed dict) => (1 3 5)</pre></blockquote> -<p><code>(dict-values</code> <em>dtd dictionary</em><code>)</code></p> -<p>Returns a list of the values of <em>dictionary</em>. The results returned by <code>dict-keys</code> and <code>dict-values</code> are not necessarily ordered consistently.</p> +<p><code>(dict-values</code> <em>dtd dict</em><code>)</code></p> +<p>Returns a list of the values of <em>dict</em>. The results returned by <code>dict-keys</code> and <code>dict-values</code> are not necessarily ordered consistently.</p> <blockquote><pre>(dict-values aed dict) => (2 4 6)</pre></blockquote> -<p><code>(dict-entries</code> <em>dtd dictionary</em><code>)</code></p> -<p>Returns two values, the results of calling <code>dict-keys</code> and the result of calling <code>dict-values</code> on <em>dictionary</em>.</p> +<p><code>(dict-entries</code> <em>dtd dict</em><code>)</code></p> +<p>Returns two values, the results of calling <code>dict-keys</code> and the result of calling <code>dict-values</code> on <em>dict</em>.</p> <blockquote><pre>(dict-entries aed dict) => ; 2 values (1 3 5) (2 4 6)</pre></blockquote> -<p><code>(dict-fold</code> <em>dtd proc knil dictionary</em><code>)</code></p> -<p>Invokes <em>proc</em> on each association of <em>dictionary</em> with three arguments: the key of the association, the value of the association, and an accumulated result of the previous invocation. For the first invocation, <em>knil</em> is used as the third argument. Returns the result of the last invocation, or <em>knil</em> if there was no invocation. Note that there is no guarantee of a consistent result if the dictionary does not have an inherent order.</p> +<p><code>(dict-fold</code> <em>dtd proc knil dict</em><code>)</code></p> +<p>Invokes <em>proc</em> on each association of <em>dict</em> with three arguments: the key of the association, the value of the association, and an accumulated result of the previous invocation. For the first invocation, <em>knil</em> is used as the third argument. Returns the result of the last invocation, or <em>knil</em> if there was no invocation. Note that there is no guarantee of a consistent result if the dictionary does not have an inherent order.</p> <blockquote><pre>(dict-fold + 0 '((1 . 2) (3 . 4))) => 10</pre></blockquote> -<p><code>(dict-map->list</code> <em>dtd proc dictionary</em><code>)</code></p> -<p>Returns a list of values that result from invoking <em>proc</em> on the keys and corresponding values of <em>dictionary</em>.</p> +<p><code>(dict-map->list</code> <em>dtd proc dict</em><code>)</code></p> +<p>Returns a list of values that result from invoking <em>proc</em> on the keys and corresponding values of <em>dict</em>.</p> <blockquote><pre> (dict-map->list (lambda (k v) v) dict) =>gt; (2 4 6), (dict-map->list - aed dict) => (-1 -1 -1) ; subtract value from key </pre></blockquote> -<p><code>(dict->alist</code> <em>dtd dictionary</em><code>)</code></p> -<p>Returns an alist whose keys and values are the keys and values of <em>dictionary</em>.</p> +<p><code>(dict->alist</code> <em>dtd dict</em><code>)</code></p> +<p>Returns an alist whose keys and values are the keys and values of <em>dict</em>.</p> <blockquote><pre>; plist to alist (dict->alist '(1 2 3 4 5 6)) => ((1 . 2) (3 . 4) (5 . 6))</pre></blockquote> <p>Add <code>dict-map</code>, <code>dict-filter</code>, <code>dict-remove</code>, and <code>dict-alter</code>. </p> -<p><code>(dict-comparator</code> <em>dtd dictionary</em><code>)</code></p> +<p><code>(dict-comparator</code> <em>dtd dict</em><code>)</code></p> <p>Return a comparator representing the type predicate, equality predicate, ordering predicate, and hash function of <em>dict</em>. The last two may be <code>#f</code> if the dictionary does not make use of these functions.</p> <p>If no comparator is relevant to the dictionary type, returns <code>#f</code>.</p> -<h3 id="iteration">Iteration</h3> -<p><code>(dict-for-each</code> <em>dtd proc dictionary</em><code>)</code></p> -<p>Invokes <em>proc</em> on each key of <em>dictionary</em> and its corresponding value in that order. This procedure is used for doing operations on the whole dictionary. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. Returns an unspecified value.</p> +<h4 id="iteration">Iteration</h4> +<p><code>(dict-for-each</code> <em>dtd proc dict</em><code>)</code></p> +<p>Invokes <em>proc</em> on each key of <em>dict</em> and its corresponding value in that order. This procedure is used for doing operations on the whole dictionary. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. Returns an unspecified value.</p> <blockquote><pre>(define (write-key key value) (write key)) (dict-for-each write-key aed dict) => unspecified ; writes "135" to current output</pre></blockquote> -<p><code>(dict-for-each<</code> <em>dtd proc dictionary key</em><code>)</code></p> -<p><code>(dict-for-each<=</code> <em>dtd proc dictionary key</em><code>)</code></p> -<p><code>(dict-for-each></code> <em>dtd proc dictionary key</em><code>)</code></p> -<p><code>(dict-for-each>=</code> <em>dtd proc dictionary key</em><code>)</code></p> -<p>Invokes <em>proc</em> on each key of <em>dictionary</em> that is less than / less than or equal to / greater than / greater than or equal to <em>key</em> and its corresponding value. This procedure is used for doing operations on part of the dictionary. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. Returns an unspecified value.</p> -<p><code>(dict-for-each-in-open-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code></p> -<p><code>(dict-for-each-in-closed-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code></p> -<p><code>(dict-for-each-in-open-closed-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code></p> -<p><code>(dict-for-each-in-closed-open-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code></p> -<p>Invokes <em>proc</em> on each key of <em>dictionary</em> that is that is within the specified interval between <em>key1</em> and <em>key2</em>, and its corresponding value. This procedure is used for doing operations on part of the dictionary. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. Returns an unspecified value.</p> -<h3 id="dictionary-type-descriptor-procedures">Dictionary type descriptor procedures</h3> +<p><code>(dict-for-each<</code> <em>dtd proc dictionary key</em><code>)</code><br> +<code>(dict-for-each<=</code> <em>dtd proc dictionary key</em><code>)</code><br> +<code>(dict-for-each></code> <em>dtd proc dictionary key</em><code>)</code><br> +<code>(dict-for-each>=</code> <em>dtd proc dictionary key</em><code>)</code></p> +<p>Invokes <em>proc</em> on each key of <em>dict</em> that is less than / less than or equal to / greater than / greater than or equal to <em>key</em> and its corresponding value. This procedure is used for doing operations on part of the dictionary. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. Returns an unspecified value.</p> +<p><code>(dict-for-each-in-open-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code><br> +<code>(dict-for-each-in-closed-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code><br> +<code>(dict-for-each-in-open-closed-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code><br> +<code>(dict-for-each-in-closed-open-interval</code> <em>dtd proc dictionary key1 key2</em><code>)</code></p> +<p>Invokes <em>proc</em> on each key of <em>dict</em> that is that is within the specified interval between <em>key1</em> and <em>key2</em>, and its corresponding value. This procedure is used for doing operations on part of the dictionary. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order. Returns an unspecified value.</p> +<h4 id="generator procedures">Generator procedures</h4> +<p><code>(make-dict-generator</code> <em>dtd dict</em><code>)</code></p> +<p>Returns a <a href="https://srfi.schemers.org/srfi-158/srfi-158.html">generator</a> that when invoked returns the associations of <em>dict</em> as pairs. When no associations are left, returns an end-of-file object. If the dictionary type is inherently ordered, associations are processed in the inherent order; otherwise in an arbitrary order.</p> +<p><code>(dict-set-accumulator</code> <em>dtd dict</em><code>)</code></p> +<p>Returns a procedure that when invoked with a pair adds the car and cdr of the pair as a key and value. If a key to be added already exists in dictionary, the new value prevails.</p> +<p><code>(dict-adjoin-accumulator</code> <em>dtd dict</em><code>)</code></p> +<p>Returns a procedure that when invoked with a pair adds the car and cdr of the pair as a key and value. If a key to be added already exists in dictionary, the old value prevails.</p> +<h4 id="dictionary-type-descriptor-procedures">Dictionary type descriptor procedures</h4> <p><code>(dtd?</code> <em>obj</em><code>)</code></p> <p>Returns <code>#t</code> if <em>obj</em> is a DTD, and <code>#f</code> otherwise.</p> -<p><code>(make-dtd</code> <em>comparator mutable arg</em> …<code>)</code><br> -<code>(dtd</code> <em>comparator mutable </em>(<em>proc-id proc</em>) …<code>)</code> [syntax]</p> -<p>Returns a new dictionary type providing procedures that allow manipulation of dictionaries of that type The <em>comparator</em> argument specifies the comparator of the underlying dictionary; the <em>mutable</em> argument is <code>#t</code> if the underlying dictionary is mutable and <code>#f</code> if not. The <em>args</em> are alternately <em>proc-ids</em> and corresponding <em>procs</em>.</p> +<p><code>(make-dtd</code> <em>arg</em> …<code>)</code><br> +<code>(dtd</code> <em></em>(<em>proc-id proc</em>) …<code>)</code> [syntax]</p> +<p>Returns a new dictionary type providing procedures that allow manipulation of dictionaries of that type. The <em>args</em> are alternately <em>proc-ids</em> and corresponding <em>procs</em>.</p> <p>A <em>proc-id</em> argument is the value of a variable whose name is the same as a procedure (except those in this section and the Exceptions section) suffixed with <code>-id</code>, and a <em>proc</em> argument is the specific procedure implementing it for this type. Note that there is only one proc-id for functional updaters and corresponding mutators. These procedures only need to handle a full-length argument list (except when defining <code>dict-ref</code> and <code>dict-update!</code>), as the other defaults have already been supplied by the framework.</p> <p><b>FIXME: Is the parenthesized part still true?</b></p> -<p> -Arguments for the five procedures <code>dictionary?</code>, <code>dict-size</code>, <code>dict-alter</code>, <code>dict-alter!</code>, and <code>dict-for-each</code> are needed to make a fully functional DTD, but it is not an error to omit them. The others are optional, but if provided can be more efficient than the versions automatically provided by the implementation of this SRFI.</p> -<p>The <code>dtd</code> macro behaves like a wrapper around <code>make-dtd</code>, but may also verify that the <em>proc-ids</em> are valid, that there are no duplicates, etc.</p> -<p>The following examples are from the file <code>plist-impl.scm</code> -in the sample implementation; the procedures referred to are also in -that file.<p> -<blockquote><pre> - (make-dtd - make-dictionary-id (lambda (comparator) '()) - dictionary?-id plist? - dict-alter-id plist-alter - dict-size-id plist-size - dict-for-each-id plist-foreach - dict->alist-id plist->alist)) => a DTD for plists - - (dtd - (make-dictionary-id (lambda (comparator) '())) - (dictionary?-id plist?) - (dict-alter-id plist-alter) - (dict-size-id plist-size) - (dict-for-each-id plist-foreach) - (dict->alist-id plist->alist)) => a DTD for plists -</pre></blockquote> -<p><code>(make-modified-dtd</code> <em>dtd obj</em> ...<code>)</code><br> -<code>(modified-dtd</code> <em>dtd</em> <code>(</code><em>proc-id proc</em><code>)</code> ...<code>)</code> [syntax]</p> -<p>Returns a DTD that is equivalent to <em>dtd</em> -except that the alternating <em>proc-ids</em> and <em>procs</em> -are used to replace the corresponding entries in <em>dtd</em>. -Caution should be used when replacing any procedure -other than the six listed in the definition of <code>make-dtd</code>.</p> -<p>A common use of this is to replace the -implementation of <code>make-dictionary</code> with one that provides specific -arguments to the underlying dictionary-type-specific constructor. -(<code>make-hash-table</code>, e.g.)</p> -<blockquote><pre> -(make-modified-dtd hash-table-dtd - make-dictionary-id - (lambda (dtd comparator) - (make-hash-table comparator 'weak-keys))) => - a DTD for weak hash tables</code></blockquote> -<blockquote><pre> -(modified-dtd hash-table-dtd - (make-dictionary-id - (lambda (dtd comparator) - (make-hash-table comparator 'weak-keys)))) => - a DTD for weak hash tables</code></blockquote> -<p><code>(make-alist-dtd</code> <em>equal</em><code>)</code></p> -<p>Returns a DTD for manipulating an alist using the equality predicate <em>equal</em>.</p> -<blockquote><code>(make-alist-dtd =) => a DTD for alists using numeric equality</code></blockquote> -<p><code>(dtd-ref</code> <em>dtd proc-id</em><code>)</code></p> -<p>Returns the procedure designated by <em>proc-id</em> from <em>dtd</em>. -This allows the ability to call a particular DTD procedure more efficiently multiple times.</p> -<h3 id="exceptions">Exceptions</h3> -<p><code>(dictionary-error</code> <em>message irritant</em> ... <code>)</code></p> -<p>Returns a dictionary error with the given <em>message</em> (a string) and -<em>irritants</em> (any objects). -If a particular procedure in a DTD cannot be implemented, it instead -should signal an appropriate dictionary exception that can be reliably caught. -<p><code>(dictionary-error?</code> <em>obj</em><code>)</code></p> -<p>Returns <code>#t</code> if <em>obj</em> is a dictionary error -and <code>#f</code> otherwise. -<p><code>(dictionary-message</code> <em>dictionary-error</em><code>)</code></p> -<p>Returns the message associated with <em>dictionary-error.</em></p> -<p><code>(dictionary-irritants</code> <em>dictionary-error</em><code>)</code></p> -<p>Returns a list of the irritants associated with <em>dictionary-error</em>.</p> -<h3 id="variables">Variables</h3> -<p>The following proc-id variables are exported from this DTD: -<code>make-dictionary-id</code>, -<code>dict-unfold</code>, +<p>The following proc-ids (and corresponding procedures) need to be provided in order to support the full set of dictionary procedures: <code>dictionary?-id</code>, +<code>dict-comparator-id</code>, +<code>dict-mutable?-id</code>, +<code>dict-map-id</code> (functional-update dictionaries), +<code>dict-filter-id</code> (functional-update dictionaries), +<code>dict-alter-id</code>, +<code>dict-size-id</code>. +Note that it is not an error to omit any of these, but some dictionary procedures may be unavailable.</p> +<p>These additional proc-ids (and corresponding procedures) may be provided in order to increase efficiency: <code>dict-empty?-id</code>, <code>dict-contains?-id</code>, -<code>dict-mutable?-id</code>, +<code>dict=?-id</code>, <code>dict-ref-id</code>, <code>dict-ref/default-id</code>, +<code>dict-min-key-id</code>, +<code>dict-max-key-id</code>, <code>dict-set-id</code>, <code>dict-adjoin-id</code>, <code>dict-delete-id</code>, <code>dict-delete-all-id</code>, <code>dict-replace-id</code>, +<code>dict-intern-id</code>, <code>dict-update-id</code>, <code>dict-update/default-id</code>, <code>dict-pop-id</code>, -<code>dict-alter-id</code>, -<code>dict-size-id</code>, +<code>dict-map-id</code>, +<code>dict-filter-id</code>, +<code>dict-remove-id</code>, <code>dict-count-id</code>, <code>dict-any-id</code>, <code>dict-every-id</code>, +<code>dict-keys-id</code>, <code>dict-values-id</code>, <code>dict-entries-id</code>, <code>dict-fold-id</code>, -<code>dict-map->list-id</code>, -<code>dict-dict->alist-id</code>, -<code>dict-comparator-id</code>. -<p>The following DTDs are also exported from this SRFI: +<code>dict-map->list-id</code>, +<code>dict->alist-id</code>, +<code>dict-for-each-id</code>, +<code>dict-for-each<-id</code>, +<code>dict-for-each<=-id</code>, +<code>dict-for-each>-id</code>, +<code>dict-for-each>=-id</code>, +<code>dict-for-each-in-open-interval-id</code>, +<code>dict-for-each-in-closed-interval-id</code>, +<code>dict-for-each-in-open-closed-interval-id</code>, +<code>dict-for-each-in-closed-open-interval-id</code>, +<code>make-dict-generator</code>, +<code>dict-set-accumulator</code>, +<code>dict-adjoin-accumulator</code>. + +<p>The <code>dtd</code> macro behaves like a wrapper around <code>make-dtd</code>, but may also verify that the <em>proc-ids</em> are valid, that there are no duplicates, etc.</p> +<p><code>(make-alist-dtd</code> <em>equal</em><code>)</code></p> +<p>Returns a DTD for manipulating an alist using the equality predicate <em>equal</em>.</p> +<blockquote><code>(make-alist-dtd =) => a DTD for alists using numeric equality</code></blockquote> +<p><code>(dtd-ref</code> <em>dtd proc-id</em><code>)</code></p> +<p>Returns the procedure designated by <em>proc-id</em> from <em>dtd</em>. +This allows the ability to call a particular DTD procedure multiple times more efficiently.</p> +<h4 id="exceptions">Exceptions</h4> +<p><code>(dictionary-error</code> <em>message irritant</em> ... <code>)</code></p> +<p>Returns a dictionary error with the given <em>message</em> (a string) and +<em>irritants</em> (any objects). +If a particular procedure in a DTD cannot be implemented, it instead +should signal an appropriate dictionary exception that can be reliably caught. +<p><code>(dictionary-error?</code> <em>obj</em><code>)</code></p> +<p>Returns <code>#t</code> if <em>obj</em> is a dictionary error +and <code>#f</code> otherwise. +<p><code>(dictionary-message</code> <em>dictionary-error</em><code>)</code></p> +<p>Returns the message associated with <em>dictionary-error.</em></p> +<p><code>(dictionary-irritants</code> <em>dictionary-error</em><code>)</code></p> +<p>Returns a list of the irritants associated with <em>dictionary-error</em>.</p> +<h4 id="exported-dtds">Exported DTDs</h4> +<p>The following DTDs are exported from this SRFI: <code>srfi-69-dtd</code>, <code>hash-table-dtd</code>, <code>srfi-126-dtd</code>, <code>mapping-dtd</code>, <code>hash-mapping-dtd</code>, <code>plist-dtd</code>, <code>alist-eqv-dtd</code>, and <code>alist-equal-dtd</code>. @@ -390,36 +387,7 @@ and <code>equal?</code> respectively.</p> <p>The sample implementation is found in the GitHub repository.</p> <p>The following list of dependencies is designed to ease registering new dictionary types that may not have complete dictionary APIs:</p> - -<ul> -<li><code>dict-empty?</code> depends on <code>dict-size</code></li> -<li><code>dict-contains?</code> depends on <code>dict-ref</code></li> -<li><code>dict-ref</code> depends on <code>dict-alter!</code></li> -<li><code>dict-ref/default</code> depends on <code>dict-ref</code></li> -<li><code>dict-set!</code> depends on <code>dict-alter!</code></li> -<li><code>dict-adjoin!</code> depends on <code>dict-alter!</code></li> -<li><code>dict-delete!</code> depends on <code>dict-delete-all!</code></li> -<li><code>dict-delete-all!</code> depends on <code>dict-alter!</code></li> -<li><code>dict-replace!</code> depends on <code>dict-alter!</code></li> -<li><code>dict-intern!</code> depends on <code>dict-alter!</code></li> -<li><code>dict-update!</code> depends on <code>dict-alter!</code></li> -<li><code>dict-update/default!</code> depends on <code>dict-update!</code></li> -<li><code>dict-pop!</code> depends on <code>dict-for-each</code>, <code>dict-delete!</code>, <code>dict-empty?</code></li> -<li><code>dict-remove!</code> depends on <code>dict-filter!</code></li> -<li><code>dict-count</code> depends on <code>dict-fold</code></li> -<li><code>dict-any</code> depends on <code>dict-for-each</code></li> -<li><code>dict-every</code> depends on <code>dict-for-each</code></li> -<li><code>dict-keys</code> depends on <code>dict-fold</code></li> -<li><code>dict-values</code> depends on <code>dict-fold</code></li> -<li><code>dict-entries</code> depends on <code>dict-fold</code></li> -<li><code>dict-fold</code> depends on <code>dict-for-each</code></li> -<li><code>dict-map->list</code> depends on <code>dict-fold</code></li> -<li><code>dict->alist</code> depends on <code>dict-map->list</code></li> - -<p>For example, the first dependency means that if a DTD -being created has something corresponding to <code>dict-ref</code> it need not -also supply <code>dict-contains?</code>, because its default implementation -uses <code>dict-ref</code>. This might not be true in other implementations.</p> +<b>FIXME</b> <h2 id="acknowledgements">Acknowledgements</h2> <p>Thanks to the participants on the mailing list.</p> |