source: project/wiki/man/4/Unit srfi-69 @ 34689

Last change on this file since 34689 was 34689, checked in by evhan, 6 weeks ago

srfi-69: Apply sjamaan's documentation updates from core (e311b617)

File size: 9.6 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit srfi-69
5
6CHICKEN implements SRFI 69 with SRFI 90 extensions. For more information, see
7[[http://srfi.schemers.org/srfi-69/srfi-69.html|SRFI-69]] and
8[[http://srfi.schemers.org/srfi-90/srfi-90.html|SRFI-90]].
9
10
11=== Hash Table Procedures
12
13
14==== make-hash-table
15
16<procedure>(make-hash-table [TEST HASH SIZE] [#:test TEST] [#:hash HASH] [#:size SIZE] [#:initial INITIAL] [#:min-load MIN-LOAD] [#:max-load MAX-LOAD] [#:weak-keys WEAK-KEYS] [#:weak-values WEAK-VALUES])</procedure>
17
18Returns a new {{HASH-TABLE}} with the supplied configuration.
19
20; {{TEST}} : The equivalence function.
21; {{HASH}} : The hash function.
22; {{SIZE}} : The expected number of table elements.
23; {{INITIAL}} : The default initial value.
24; {{MIN-LOAD}} : The minimum load factor. A {{flonum}} in (0.0 1.0).
25; {{MAX-LOAD}} : The maximum load factor. A {{flonum}} in (0.0 1.0).
26; {{WEAK-KEYS}} : Use weak references for keys. (Ignored)
27; {{WEAK-VALUES}} : Use weak references for values. (Ignored)
28
29Please note that hash tables are ''not'' guaranteed to compare {{equal?}}
30to each other, even if they contain exactly the same key/value pairs.
31
32
33==== alist->hash-table
34
35<procedure>(alist->hash-table A-LIST [#:test TEST] [#:hash HASH] [#:size SIZE] [#:initial INITIAL] [#:min-load MIN-LOAD] [#:max-load MAX-LOAD] [#:weak-keys WEAK-KEYS] [#:weak-values WEAK-VALUES])</procedure>
36
37Returns a new {{HASH-TABLE}}. The {{HASH-TABLE}} is populated from the
38{{A-LIST}}. The keyword arguments are per {{make-hash-table}}.
39
40If a key occurs multiple times in {{A-LIST}}, the first occurrence
41will be used in the hash table.
42
43
44==== hash-table?
45
46<procedure>(hash-table? OBJECT)</procedure>
47
48Is the {{OBJECT}} a {{hash-table}}?
49
50
51==== hash-table-size
52
53<procedure>(hash-table-size HASH-TABLE)</procedure>
54
55Returns the number of associations in {{HASH-TABLE}}.
56
57
58==== hash-table-equivalence-function
59
60<procedure>(hash-table-equivalence-function HASH-TABLE)</procedure>
61
62The {{HASH-TABLE}} {{equivalence-function}}.
63
64
65==== hash-table-hash-function
66
67<procedure>(hash-table-hash-function HASH-TABLE)</procedure>
68
69The {{HASH-TABLE}} {{hash-function}}.
70
71
72==== hash-table-min-load
73
74<procedure>(hash-table-min-load HASH-TABLE)</procedure>
75
76The {{HASH-TABLE}} minimum load factor.
77
78
79==== hash-table-max-load
80
81<procedure>(hash-table-max-load HASH-TABLE)</procedure>
82
83The {{HASH-TABLE}} maximum load factor.
84
85
86==== hash-table-weak-keys
87
88<procedure>(hash-table-weak-keys HASH-TABLE)</procedure>
89
90Does the {{HASH-TABLE}} use weak references for keys?
91
92
93==== hash-table-weak-values
94
95<procedure>(hash-table-weak-values HASH-TABLE)</procedure>
96
97Does the {{HASH-TABLE}} use weak references for values?
98
99
100==== hash-table-has-initial?
101
102<procedure>(hash-table-has-initial? HASH-TABLE)</procedure>
103
104Does the {{HASH-TABLE}} have a default initial value?
105
106
107==== hash-table-initial
108
109<procedure>(hash-table-initial HASH-TABLE)</procedure>
110
111The {{HASH-TABLE}} default initial value.
112
113
114==== hash-table-keys
115
116<procedure>(hash-table-keys HASH-TABLE)</procedure>
117
118Returns a list of the keys in the {{HASH-TABLE}} population.
119
120
121==== hash-table-values
122
123<procedure>(hash-table-values HASH-TABLE)</procedure>
124
125Returns a list of the values in the {{HASH-TABLE}} population.
126
127
128==== hash-table->alist
129
130<procedure>(hash-table->alist HASH-TABLE)</procedure>
131
132Returns the population of the {{HASH-TABLE}} as an {{a-list}}.
133
134
135
136==== hash-table-ref
137
138<procedure>(hash-table-ref HASH-TABLE KEY)</procedure>
139
140Returns the {{VALUE}} for the {{KEY}} in the {{HASH-TABLE}}.
141
142Aborts with an exception when the {{KEY}} is missing.
143
144
145==== hash-table-ref/default
146
147<procedure>(hash-table-ref/default HASH-TABLE KEY DEFAULT)</procedure>
148
149Returns the {{VALUE}} for the {{KEY}} in the {{HASH-TABLE}}, or the {{DEFAULT}}
150when the {{KEY}} is missing.
151
152
153==== hash-table-exists?
154
155<procedure>(hash-table-exists? HASH-TABLE KEY)</procedure>
156
157Does the {{KEY}} exist in the {{HASH-TABLE}}?
158
159
160==== hash-table-set!
161
162<procedure>(hash-table-set! HASH-TABLE KEY VALUE)</procedure>
163
164Set the {{VALUE}} for the {{KEY}} in the {{HASH-TABLE}}.
165
166A setter for {{hash-table-ref}} is defined, so
167
168<enscript highlight=scheme>
169(set! (hash-table-ref HASH-TABLE KEY) VALUE)
170</enscript>
171
172is equivalent to
173
174<enscript highlight=scheme>
175(hash-table-set! HASH-TABLE KEY VALUE)
176</enscript>
177
178
179==== hash-table-update!
180
181<procedure>(hash-table-update! HASH-TABLE KEY [UPDATE-FUNCTION [DEFAULT-VALUE-FUNCTION]])</procedure>
182
183Sets or replaces the {{VALUE}} for {{KEY}} in the {{HASH-TABLE}}.
184
185The {{UPDATE-FUNCTION}} takes the existing {{VALUE}} for {{KEY}} and returns
186the new {{VALUE}}. The default is {{identity}}
187
188The {{DEFAULT-VALUE-FUNCTION}} is called when the entry for {{KEY}} is missing.
189The default uses the {{(hash-table-initial-value)}}, if provided. Otherwise
190aborts with an exception.
191
192Returns the new {{VALUE}}.
193
194
195==== hash-table-update!/default
196
197<procedure>(hash-table-update!/default HASH-TABLE KEY UPDATE-FUNCTION DEFAULT-VALUE)</procedure>
198
199Sets or replaces the {{VALUE}} for {{KEY}} in the {{HASH-TABLE}}.
200
201The {{UPDATE-FUNCTION}} takes the existing {{VALUE}} for {{KEY}} and returns
202the new {{VALUE}}.
203
204The {{DEFAULT-VALUE}} is used when the entry for {{KEY}} is missing.
205
206Returns the new {{VALUE}}.
207
208
209==== hash-table-copy
210
211<procedure>(hash-table-copy HASH-TABLE)</procedure>
212
213Returns a shallow copy of the {{HASH-TABLE}}.
214
215
216==== hash-table-delete!
217
218<procedure>(hash-table-delete! HASH-TABLE KEY)</procedure>
219
220Deletes the entry for {{KEY}} in the {{HASH-TABLE}}.
221
222
223==== hash-table-remove!
224
225<procedure>(hash-table-remove! HASH-TABLE PROC)</procedure>
226
227Calls {{PROC}} for all entries in {{HASH-TABLE}} with the key and value of each
228entry. If {{PROC}} returns true, then that entry is removed.
229
230
231==== hash-table-clear!
232
233<procedure>(hash-table-clear! HASH-TABLE)</procedure>
234
235Deletes all entries in {{HASH-TABLE}}.
236
237
238==== hash-table-merge
239
240<procedure>(hash-table-merge HASH-TABLE-1 HASH-TABLE-2)</procedure>
241
242Returns a new {{HASH-TABLE}} with the union of {{HASH-TABLE-1}} and
243{{HASH-TABLE-2}}. Keys that exist in both tables will be taken from
244{{HASH-TABLE-1}}.
245
246
247==== hash-table-merge!
248
249<procedure>(hash-table-merge! HASH-TABLE-1 HASH-TABLE-2)</procedure>
250
251Returns {{HASH-TABLE-1}} as the union of {{HASH-TABLE-1}} and
252{{HASH-TABLE-2}}. Keys that exist in both tables will be taken from
253{{HASH-TABLE-1}}.
254
255
256==== hash-table-map
257
258<procedure>(hash-table-map HASH-TABLE FUNC)</procedure>
259
260Calls {{FUNC}} for all entries in {{HASH-TABLE}} with the key and value of each
261entry.
262
263Returns a list of the results of each call.
264
265
266==== hash-table-fold
267
268<procedure>(hash-table-fold HASH-TABLE FUNC INIT)</procedure>
269
270Calls {{FUNC}} for all entries in {{HASH-TABLE}} with the key and value of each
271entry, and the current folded value. The initial folded value is {{INIT}}.
272
273Returns the final folded value.
274
275
276==== hash-table-for-each
277
278<procedure>(hash-table-for-each HASH-TABLE PROC)</procedure>
279
280Calls {{PROC}} for all entries in {{HASH-TABLE}} with the key and value of each
281entry.
282
283
284==== hash-table-walk
285
286<procedure>(hash-table-walk HASH-TABLE PROC)</procedure>
287
288Calls {{PROC}} for all entries in {{HASH-TABLE}} with the key and value of each
289entry.
290
291
292=== Hashing Functions
293
294All hash functions return a {{fixnum}} in the range [0 {{BOUND}}).
295
296When given the fixnum RANDOMIZATION, these functions will use this
297to perturb the value; if not specified, the value will differ for
298each invocation of your program. This is for security reasons; an
299attacker who knows what a value hashes to can deliberately try to
300cause collisions, thereby flattening your hash table, effectively
301reducing it to a list.  Always make sure you don't expose any
302hashed value to an attacker.
303
304
305==== number-hash
306
307<procedure>(number-hash NUMBER [BOUND RANDOMIZATION])</procedure>
308
309For use with {{=}} as a {{hash-table-equivalence-function}}.
310
311
312==== object-uid-hash
313
314<procedure>(object-uid-hash OBJECT [BOUND RANDOMIZATION])</procedure>
315
316Currently a synonym for {{equal?-hash}}.
317
318
319==== symbol-hash
320
321<procedure>(symbol-hash SYMBOL [BOUND RANDOMIZATION])</procedure>
322
323For use with {{eq?}} as a {{hash-table-equivalence-function}}.
324
325
326==== keyword-hash
327
328<procedure>(keyword-hash KEYWORD [BOUND RANDOMIZATION])</procedure>
329
330For use with {{eq?}} as a {{hash-table-equivalence-function}}.
331
332
333==== string-hash
334
335<procedure>(string-hash STRING [BOUND START END RANDOMIZATION])</procedure>
336
337For use with {{string=?}} as a {{hash-table-equivalence-function}}.
338The optional {{START}} and {{END}} arguments may be given to limit
339the hash calculation to a specific sub-section of {{STRING}}.
340
341
342==== string-ci-hash
343
344<procedure>(string-hash-ci STRING [BOUND START END RANDOMIZATION])</procedure><br>
345<procedure>(string-ci-hash STRING [BOUND START END RANDOMIZATION])</procedure>
346
347For use with {{string-ci=?}} as a {{hash-table-equivalence-function}}.
348
349
350==== eq?-hash
351
352<procedure>(eq?-hash OBJECT [BOUND RANDOMIZATION])</procedure>
353
354For use with {{eq?}} as a {{hash-table-equivalence-function}}.
355
356
357==== eqv?-hash
358
359<procedure>(eqv?-hash OBJECT [BOUND RANDOMIZATION])</procedure>
360
361For use with {{eqv?}} as a {{hash-table-equivalence-function}}.
362
363
364==== equal?-hash
365
366<procedure>(equal?-hash OBJECT [BOUND RANDOMIZATION])</procedure>
367
368For use with {{equal?}} as a {{hash-table-equivalence-function}}.
369
370
371==== hash
372
373<procedure>(hash OBJECT [BOUND RANDOMIZATION])</procedure>
374
375Synonym for {{equal?-hash}}.
376
377
378==== hash-by-identity
379
380<procedure>(hash-by-identity OBJECT [BOUND RANDOMIZATION])</procedure>
381
382Synonym for {{eq?-hash}}.
383
384
385=== recursive-hash-max-depth
386
387<parameter>(recursive-hash-max-depth)</parameter>
388
389The maximum structure depth to follow when computing a hash value. The default is {{4}}.
390
391
392=== recursive-hash-max-length
393
394<parameter>(recursive-hash-max-length)</parameter>
395
396The maximum vector length to follow when computing a hash value. The default is {{4}}.
397
398Previous: [[Unit srfi-18]]
399Next: [[Unit posix]]
400
Note: See TracBrowser for help on using the repository browser.