1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>SRFI 225: Dictionaries</title>
<link href="/favicon.png" rel="icon" sizes="192x192" type="image/png">
<link rel="stylesheet" href="https://srfi.schemers.org/srfi.css" type="text/css">
<meta name="viewport" content="width=device-width, initial-scale=1"></head>
<body>
<h1><a href="https://srfi.schemers.org/"><img class="srfi-logo" src="https://srfi.schemers.org/srfi-logo.svg" alt="SRFI surfboard logo" /></a>225: Dictionaries</h1>
<p>by John Cowan (spec) and Arvydas Silanskas (implementation)</p>
<h2 id="status">Status</h2>
<p>This SRFI is currently in <em>draft</em> status. Here is <a href="https://srfi.schemers.org/srfi-process.html">an explanation</a> of each status that a SRFI can hold. To provide input on this SRFI, please send email to <code><a href="mailto:srfi+minus+225+at+srfi+dotschemers+dot+org">srfi-225@<span class="antispam">nospam</span>srfi.schemers.org</a></code>. To subscribe to the list, follow <a href="https://srfi.schemers.org/srfi-list-subscribe.html">these instructions</a>. You can access previous messages via the mailing list <a href="https://srfi-email.schemers.org/srfi-225">archive</a>.</p>
<ul>
<li>Received: 2021-06-26</li>
<li>60-day deadline: 2021-09-16</li>
<li>Draft #1 published: 2021-07-18</li>
<li>Draft #2 published: 2021-07-26</li>
<li>John Cowan's <a href="https://github.com/pre-srfi/dictionaries">personal
Git repo for this SRFI</a> for reference while the SRFI is in
<em>draft</em> status (<a href="https://htmlpreview.github.io/?https://github.com/johnwcowan/srfi-225/blob/master/srfi-225.html">preview</a>)</li>
</ul>
<h2 id="abstract">Abstract</h2>
<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>
<h2 id="issues">Issues</h2>
<p>dict-unfold: as you would think.</p>
<p>dict=?, dict<?, etc. Compare dictionaries for equality, subset, etc.
A value comparator is passed in.</p>
<p>dict-union(!), dict-intersection(!), etc.
Functional and linear-update versions of these operations.</p>
<p>dict-range=(!), dict-range<(!), etc. Return subsets whose keys are =, <, etc.</p>
<p>-dict-fold/reverse (maybe)</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>
<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>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: create an empty dictionary from a comparator; determine a dictionary’s current size; reference, update, or insert an element of the dictionary depending on its current contents; and process 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.</p>
<p>Note that dictionaries must still be constructed using type-specific constructors, as the required and optional arguments differ in each case.</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>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 <i>similar</i> 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. The linear-update mutation operations actually mutate the property list whenever possible. 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>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 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.</p>
<p>In all other cases, lists cannot be treated as dictionaries unless a DTD exists.</p>
<h3>Procedures</h3>
<p>Each of the following examples is assumed to be prefixed by the following definitions:</p>
<blockquote><pre>(define dict (list '(1 . 2) '(3 . 4) '(5 . 6)))
(define aed alist-eqv-dtd)
</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 the <code>dictionary?</code> procedure that was used to make the DTD on <em>dictionary</em> returns <code>#f</code>.</p>
<h3 id="constructor">Constructor</h3>
<p><code>(make-dictionary</code> <em>dtd comparator</em><code>)</code></p>
<p>Returns an empty dictionary of the type described by the DTD using <em>comparator</em> to specify the dictionary's equality predicate and its ordering predicate and/or hash function.</p>
<p>If the contents of <em>comparator</em> are inconsistent with the dictionary type, it is an error.
If the dictionary type does not accept a comparator, <code>#f</code> should be passed instead.</p>
<h3 id="predicates">Predicates</h3>
<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>
<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>
<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>
<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>
<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>
<blockquote><pre>(dict-ref/default aed dict 1 #f) => 1
(dict-ref/default aed dict 1 #f) => #f</pre></blockquote>
<h3 id="mutation">Mutation</h3>
<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 may copy them. The ones with <code>!</code> are linear-update: they may return either a new dictionary object (which may or may not share storage with the <em>dictionary</em> argument), or the same dictionary object, mutated. In either case it is an error to access the dictionary later through any other reference to it, as that reference may have been invalidated. These procedures are defined as linear-update because the underlying type-specific operations may be functional, mutational, or themselves linear-update.</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>
<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>
<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>
<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>
<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>
<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>
<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>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>
<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>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-map</code> <em>dtd proc dictionary</em><code>)</code><br>
<code>(dict-map!</code> <em>dtd proc dictionary</em><code>)</code></p>
<p>Returns a dictionary similar to <em>dictionary</em> that maps each key of <em>dictionary</em> to the value that results from invoking <em>proc</em> on the corresponding key and value of <em>dictionary</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 dictionary</em><code>)</code><br>
<code>(dict-filter!</code> <em>dtd pred dictionary</em><code>)</code><br>
<code>(dict-remove</code> <em>dtd pred dictionary</em><code>)</code><br>
<code>(dict-remove!</code> <em>dtd pred dictionary</em><code>)</code></p>
<p>Returns a dictionary similar to <em>dictionary</em> that contains just the associations of <em>dictionary</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-search</code> <em>dtd dictionary key failure success</em><code>)</code><br>
<code>(dict-search!</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> in the sense of <em>dictionary</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>, and is expected to tail-call one of them.</p>
<p>However, 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>, and is expected to tail-call one of them.</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>
</ul>
<p>In all cases, <em>obj</em> is returned as a second value.</p>
<p>Here are four examples of <code>dict-search</code>,
one for each of the four procedures:
<blockquote><pre>
;; ignore
(define-values
(dict value)
(dict-search (alist->dict '((a . b))) 'c
(lambda (insert ignore)
(ignore 'foo))
(lambda args
(error))))
(dict->alist aed dict)) => ((a . b))
value => 'foo
;; insert
(define-values
(dict value)
(dict-search (alist->dict '((a . b))) 'c
(lambda (insert ignore)
(insert 'd 'foo))
(lambda args
(error))))
(dict-ref aed dict 'a)) => b
(dict-ref aed dict 'c)) => 'd
value => foo
;; update
(define-values
(dict value)
(dict-search (alist->dict '((a . b))) 'a
(lambda args
(error))
(lambda (key value update delete)
(update 'a2 'b2 'foo))))
(dict->alist aed dict) => ((a2 . b2)
value => foo
;; delete
(define-values
(dict value)
(dict-search (alist->dict '((a . b) (c . d))) 'a
(lambda args
(error))
(lambda (key value update delete)
(delete 'foo))))
(dict->alist aed dict)) => ((c . d))
value => foo
</pre></blockquote>
<h3 id="the-whole-dictionary">The whole dictionary</h3>
<p><code>(dict-copy</code> <em>dtd dictionary</em><code>)</code><p>
Returns a dictionary that is similar to <em>dictionary</em> and contains the same associations. Mutating the result of <code>dict-copy</code> does not affect <em>dictionary</em> or vice versa.</p>
<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>
<blockquote><pre>(dict-size aed dict) => 3</pre></blockquote>
<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>
<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-count</code> <em>dtd pred dictionary</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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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-search</code>.
</p>
<p><code>(dict-comparator</code> <em>dtd dictionary</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>
<h3 id="dictionary-type-descriptors">Dictionary type descriptors</h3>
<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>arg</em> …<code>)</code><br>
<code>(dtd</code> (<em>procindex 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>procindex</em> names and corresponding <em>procs</em>.</p>
<p>A <em>procindex</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>-index</code> is the same as one of the procedures defined in this SRFI (other than those in this section), and a <em>proc</em> argument is the specific procedure implementing it for this type. 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>
Arguments for the six procedures <code>make-dictionary</code>, <code>dictionary?</code>, <code>dict-size</code>, <code>dict-search</code>, <code>dict-search!</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>procindex</em> names 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-index '()
dictionary?-index plist?
dict-search-index plist-search
dict-search!-index plist-search!
dict-size-index plist-size
dict-for-each-index plist-foreach
dict->alist-index plist->alist)) => a DTD for plists
(dtd
(make-dictionary-index '())
(dictionary?-index plist?)
(dict-search-index plist-search)
(dict-search!-index plist-search!)
(dict-size-index plist-size)
(dict-for-each-index plist-foreach)
(dict->alist-index plist->alist)) => a DTD for plists
</pre></blockquote>
<p><code>(make-modified-dtd</code> <em>dtd obj</em> ...<code>)</code></p>
<p>Returns a DTD that is equivalent to <em>dtd</em>
except that the alternating <em>procindexes</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-index
(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 procindex</em><code>)</code></p>
<p>Returns the procedure designated by <em>procindex</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 procindex variables are exported from this DTD:
<code>make-dictionary-index</code>,
<code>dictionary?-index</code>,
<code>dict-empty?-index</code>,
<code>dict-contains?-index</code>,
<code>dict-ref-index</code>,
<code>dict-ref/default-index</code>,
<code>dict-set-index</code>,
<code>dict-adjoin-index</code>,
<code>dict-adjoin!-index</code>,
<code>dict-delete-index</code>,
<code>dict-delete!-index</code>,
<code>dict-delete-all-index</code>,
<code>dict-delete-all!-index</code>,
<code>dict-replace-index</code>,
<code>dict-replace!-index</code>,
<code>dict-update-index</code>,
<code>dict-update!-index</code>,
<code>dict-update/default-index</code>,
<code>dict-update/default!-index</code>,
<code>dict-pop-index</code>,
<code>dict-pop!-index</code>,
<code>dict-map-index</code>,
<code>dict-map!-index</code>,
<code>dict-filter-index</code>,
<code>dict-filter!-index</code>,
<code>dict-remove-index</code>,
<code>dict-remove!-index</code>,
<code>dict-search-index</code>,
<code>dict-search!-index</code>,
<code>dict-copy-index</code>,
<code>dict-size-index</code>,
<code>dict-count-index</code>,
<code>dict-any-index</code>,
<code>dict-every-index</code>,
<code>dict-keys-index</code>,
<code>dict-values-index</code>,
<code>dict-entries-index</code>,
<code>dict-fold-index</code>,
<code>dict-map->list-index</code>,
<code>dict-dict->alist-index</code>,
<code>dict-comparator-index</code>.
<p>The following DTDs are also 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>.
The last two provide DTDs for alists using <code>eqv?</code>
and <code>equal?</code> respectively.</p>
<h2 id="implementation">Implementation</h2>
<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-search!</code></li>
<li><code>dict-ref/default</code> depends on <code>dict-ref</code></li>
<li><code>dict-set!</code> depends on <code>dict-search!</code></li>
<li><code>dict-adjoin!</code> depends on <code>dict-search!</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-search!</code></li>
<li><code>dict-replace!</code> depends on <code>dict-search!</code></li>
<li><code>dict-intern!</code> depends on <code>dict-search!</code></li>
<li><code>dict-update!</code> depends on <code>dict-search!</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>
<h2 id="acknowledgements">Acknowledgements</h2>
<p>Thanks to the participants on the mailing list.</p>
<h2 id="copyright">Copyright</h2>
<p>© 2021 John Cowan, Arvydas Silanskas.</p>
<p>
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:</p>
<p>
The above copyright notice and this permission notice (including the
next paragraph) shall be included in all copies or substantial
portions of the Software.</p>
<p>
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.</p>
<hr>
<address>Editor: <a href="mailto:srfi-editors+at+srfi+dot+schemers+dot+org">Arthur A. Gleckler</a></address></body></html>
|
