1Hashtbl(3)                       OCaml library                      Hashtbl(3)
2
3
4

NAME

6       Hashtbl - Hash tables and hash functions.
7

Module

9       Module   Hashtbl
10

Documentation

12       Module Hashtbl
13        : sig end
14
15
16       Hash tables and hash functions.
17
18       Hash tables are hashed association tables, with in-place modification.
19
20
21
22
23
24
25
26
27       === Generic interface ===
28
29
30       type ('a, 'b) t
31
32
33       The type of hash tables from type 'a to type 'b .
34
35
36
37
38       val create : int -> ('a, 'b) t
39
40
41       Hashtbl.create n creates a new, empty hash table, with initial size n .
42       For best results, n should be on the order of the  expected  number  of
43       elements that will be in the table.  The table grows as needed, so n is
44       just an initial guess.
45
46
47
48
49       val clear : ('a, 'b) t -> unit
50
51       Empty a hash table.
52
53
54
55
56       val add : ('a, 'b) t -> 'a -> 'b -> unit
57
58
59       Hashtbl.add tbl x y adds a binding of x to y in table tbl  .   Previous
60       bindings  for x are not removed, but simply hidden. That is, after per‐
61       forming Hashtbl.remove tbl x , the previous binding for x , if any,  is
62       restored.  (Same behavior as with association lists.)
63
64
65
66
67       val copy : ('a, 'b) t -> ('a, 'b) t
68
69       Return a copy of the given hashtable.
70
71
72
73
74       val find : ('a, 'b) t -> 'a -> 'b
75
76
77       Hashtbl.find  tbl x returns the current binding of x in tbl , or raises
78       Not_found if no such binding exists.
79
80
81
82
83       val find_all : ('a, 'b) t -> 'a -> 'b list
84
85
86       Hashtbl.find_all tbl x returns the list of all data associated  with  x
87       in  tbl  .   The  current  binding is returned first, then the previous
88       bindings, in reverse order of introduction in the table.
89
90
91
92
93       val mem : ('a, 'b) t -> 'a -> bool
94
95
96       Hashtbl.mem tbl x checks if x is bound in tbl .
97
98
99
100
101       val remove : ('a, 'b) t -> 'a -> unit
102
103
104       Hashtbl.remove tbl x removes the current binding of x in tbl ,  restor‐
105       ing  the  previous  binding  if it exists.  It does nothing if x is not
106       bound in tbl .
107
108
109
110
111       val replace : ('a, 'b) t -> 'a -> 'b -> unit
112
113
114       Hashtbl.replace tbl x y replaces the current binding of x in tbl  by  a
115       binding  of  x  to y .  If x is unbound in tbl , a binding of x to y is
116       added to tbl .  This is functionally equivalent to Hashtbl.remove tbl x
117       followed by Hashtbl.add tbl x y .
118
119
120
121
122       val iter : ('a -> 'b -> unit) -> ('a, 'b) t -> unit
123
124
125       Hashtbl.iter f tbl applies f to all bindings in table tbl .  f receives
126       the key as first argument, and the associated value as second argument.
127       Each  binding  is presented exactly once to f .  The order in which the
128       bindings are passed to f is unspecified.  However, if  the  table  con‐
129       tains  several  bindings  for  the  same  key,  they are passed to f in
130       reverse order of introduction, that is,  the  most  recent  binding  is
131       passed first.
132
133
134
135
136       val fold : ('a -> 'b -> 'c -> 'c) -> ('a, 'b) t -> 'c -> 'c
137
138
139       Hashtbl.fold  f  tbl  init  computes (f kN dN ... (f k1 d1 init)...)  ,
140       where k1 ... kN are the keys of all bindings in tbl , and d1 ... dN are
141       the  associated  values.  Each binding is presented exactly once to f .
142       The order in which the bindings are passed to f is  unspecified.   How‐
143       ever, if the table contains several bindings for the same key, they are
144       passed to f in reverse order of introduction, that is, the most  recent
145       binding is passed first.
146
147
148
149
150       val length : ('a, 'b) t -> int
151
152
153       Hashtbl.length  tbl  returns  the number of bindings in tbl .  Multiple
154       bindings are counted multiply, so Hashtbl.length gives  the  number  of
155       times Hashtbl.iter calls its first argument.
156
157
158
159
160
161       === Functorial interface ===
162
163
164       module type HashedType = sig end
165
166
167       The input signature of the functor Hashtbl.Make .
168
169
170
171       module type S = sig end
172
173
174       The output signature of the functor Hashtbl.Make .
175
176
177
178       module Make : functor (H : HashedType) -> sig end
179
180
181       Functor  building  an  implementation  of the hashtable structure.  The
182       functor Hashtbl.Make returns a structure containing a type key of  keys
183       and  a  type 'a t of hash tables associating data of type 'a to keys of
184       type key .  The operations perform similarly to those  of  the  generic
185       interface,  but use the hashing and equality functions specified in the
186       functor argument H instead of generic equality and hashing.
187
188
189
190
191
192       === The polymorphic hash primitive ===
193
194
195       val hash : 'a -> int
196
197
198       Hashtbl.hash x associates a positive integer to any value of any  type.
199       It  is  guaranteed  that  if x = y or Pervasives.compare x y = 0 , then
200       hash x = hash y .  Moreover, hash always  terminates,  even  on  cyclic
201       structures.
202
203
204
205
206       val hash_param : int -> int -> 'a -> int
207
208
209       Hashtbl.hash_param  n  m  x computes a hash value for x , with the same
210       properties as for hash . The two extra parameters n  and  m  give  more
211       precise   control   over   hashing.  Hashing  performs  a  depth-first,
212       right-to-left traversal of the structure x , stopping after n  meaning‐
213       ful nodes were encountered, or m nodes, meaningful or not, were encoun‐
214       tered. Meaningful nodes are: integers; floating-point numbers; strings;
215       characters; booleans; and constant constructors. Larger values of m and
216       n means that more nodes are taken into account  to  compute  the  final
217       hash  value,  and therefore collisions are less likely to happen.  How‐
218       ever, hashing takes longer. The parameters m and n govern the  tradeoff
219       between accuracy and speed.
220
221
222
223
224
225
226OCamldoc                          2017-03-22                        Hashtbl(3)