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

Last change on this file since 32311 was 32311, checked in by svnwiki, 3 years ago

Anonymous wiki edit for IP [195.37.234.237]: Less ambiguous description of "hash-table-size". See http://srfi.schemers.org/srfi-69/srfi-69.html#hsht11

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