1MoreLabels.Map.S(3)              OCaml library             MoreLabels.Map.S(3)
2
3
4

NAME

6       MoreLabels.Map.S - Output signature of the functor MoreLabels.Map.Make.
7

Module type

9       Module type   MoreLabels.Map.S
10

Documentation

12       Module type S
13        = sig end
14
15
16       Output signature of the functor MoreLabels.Map.Make .
17
18
19
20
21
22       type key
23
24
25       The type of the map keys.
26
27
28       type +'a t
29
30
31       The type of maps from type key to type 'a .
32
33
34
35       val empty : 'a t
36
37       The empty map.
38
39
40
41       val is_empty : 'a t -> bool
42
43       Test whether a map is empty or not.
44
45
46
47       val mem : key -> 'a t -> bool
48
49
50       mem  x  m returns true if m contains a binding for x , and false other‐
51       wise.
52
53
54
55       val add : key:key -> data:'a -> 'a t -> 'a t
56
57
58       add ~key ~data m returns a map containing the same bindings as m , plus
59       a  binding  of  key  to data . If key was already bound in m to a value
60       that is physically equal to data , m is returned unchanged (the  result
61       of  the function is then physically equal to m ). Otherwise, the previ‐
62       ous binding of key in m disappears.
63
64
65       Before4.03 Physical equality was not ensured.
66
67
68
69
70       val update : key:key -> f:('a option -> 'a option) -> 'a t -> 'a t
71
72
73       update ~key ~f m returns a map containing the same bindings as m ,  ex‐
74       cept  for the binding of key . Depending on the value of y where y is f
75       (find_opt key m) , the binding of key is added, removed or updated.  If
76       y  is  None  ,  the binding is removed if it exists; otherwise, if y is
77       Some z then key is associated to z in the resulting map.   If  key  was
78       already  bound in m to a value that is physically equal to z , m is re‐
79       turned unchanged (the result of the function is then  physically  equal
80       to m ).
81
82
83       Since 4.06.0
84
85
86
87       val singleton : key -> 'a -> 'a t
88
89
90       singleton x y returns the one-element map that contains a binding y for
91       x .
92
93
94       Since 3.12.0
95
96
97
98       val remove : key -> 'a t -> 'a t
99
100
101       remove x m returns a map containing the same bindings as m , except for
102       x  which  is unbound in the returned map.  If x was not in m , m is re‐
103       turned unchanged (the result of the function is then  physically  equal
104       to m ).
105
106
107       Before4.03 Physical equality was not ensured.
108
109
110
111
112       val  merge  : f:(key -> 'a option -> 'b option -> 'c option) -> 'a t ->
113       'b t -> 'c t
114
115
116       merge ~f m1 m2 computes a map whose keys are a subset of the keys of m1
117       and  of  m2  . The presence of each such binding, and the corresponding
118       value, is determined with the function f .  In terms  of  the  find_opt
119       operation,  we  have  find_opt  x (merge f m1 m2) = f x (find_opt x m1)
120       (find_opt x m2) for any key x , provided that f x None None = None .
121
122
123       Since 3.12.0
124
125
126
127       val union : f:(key -> 'a -> 'a -> 'a option) -> 'a t -> 'a t -> 'a t
128
129
130       union ~f m1 m2 computes a map whose keys are a subset of the keys of m1
131       and  of  m2  .  When the same binding is defined in both arguments, the
132       function f is used to combine them.  This is a special case of merge  :
133       union f m1 m2 is equivalent to merge f' m1 m2 , where
134
135       - f' _key None None = None
136
137
138       - f' _key (Some v) None = Some v
139
140
141       - f' _key None (Some v) = Some v
142
143
144       - f' key (Some v1) (Some v2) = f key v1 v2
145
146
147
148
149       Since 4.03.0
150
151
152
153       val compare : cmp:('a -> 'a -> int) -> 'a t -> 'a t -> int
154
155       Total  ordering  between  maps.  The first argument is a total ordering
156       used to compare data associated with equal keys in the two maps.
157
158
159
160       val equal : cmp:('a -> 'a -> bool) -> 'a t -> 'a t -> bool
161
162
163       equal ~cmp m1 m2 tests whether the maps m1 and m2 are equal,  that  is,
164       contain  equal  keys  and  associate  them with equal data.  cmp is the
165       equality predicate used to compare the data associated with the keys.
166
167
168
169       val iter : f:(key:key -> data:'a -> unit) -> 'a t -> unit
170
171
172       iter ~f m applies f to all bindings in map m .  f receives the  key  as
173       first argument, and the associated value as second argument.  The bind‐
174       ings are passed to f in increasing order with respect to  the  ordering
175       over the type of the keys.
176
177
178
179       val fold : f:(key:key -> data:'a -> 'b -> 'b) -> 'a t -> init:'b -> 'b
180
181
182       fold  ~f  m  ~init computes (f kN dN ... (f k1 d1 init)...)  , where k1
183       ... kN are the keys of all bindings in m (in increasing order), and  d1
184       ... dN are the associated data.
185
186
187
188       val for_all : f:(key -> 'a -> bool) -> 'a t -> bool
189
190
191       for_all  ~f  m checks if all the bindings of the map satisfy the predi‐
192       cate f .
193
194
195       Since 3.12.0
196
197
198
199       val exists : f:(key -> 'a -> bool) -> 'a t -> bool
200
201
202       exists ~f m checks if at least one binding of  the  map  satisfies  the
203       predicate f .
204
205
206       Since 3.12.0
207
208
209
210       val filter : f:(key -> 'a -> bool) -> 'a t -> 'a t
211
212
213       filter  ~f  m  returns  the map with all the bindings in m that satisfy
214       predicate p . If every binding in m satisfies f ,  m  is  returned  un‐
215       changed (the result of the function is then physically equal to m )
216
217
218       Before4.03 Physical equality was not ensured.
219
220
221
222       Since 3.12.0
223
224
225
226       val filter_map : f:(key -> 'a -> 'b option) -> 'a t -> 'b t
227
228
229       filter_map  ~f  m  applies  the  function f to every binding of m , and
230       builds a map from the results. For each binding (k,  v)  in  the  input
231       map:
232
233       -if f k v is None then k is not in the result,
234
235       -if f k v is Some v' then the binding (k, v') is in the output map.
236
237       For example, the following function on maps whose values are lists
238                 filter_map
239                   (fun _k li -> match li with [] -> None | _::tl -> Some tl)
240                   m
241
242       drops  all  bindings  of  m  whose value is an empty list, and pops the
243       first element of each value that is non-empty.
244
245
246       Since 4.11.0
247
248
249
250       val partition : f:(key -> 'a -> bool) -> 'a t -> 'a t * 'a t
251
252
253       partition ~f m returns a pair of maps (m1, m2) , where m1 contains  all
254       the bindings of m that satisfy the predicate f , and m2 is the map with
255       all the bindings of m that do not satisfy f .
256
257
258       Since 3.12.0
259
260
261
262       val cardinal : 'a t -> int
263
264       Return the number of bindings of a map.
265
266
267       Since 3.12.0
268
269
270
271       val bindings : 'a t -> (key * 'a) list
272
273       Return the list of all bindings of the given map.  The returned list is
274       sorted  in  increasing  order  of  keys  with  respect  to the ordering
275       Ord.compare , where Ord is the argument given to MoreLabels.Map.Make .
276
277
278       Since 3.12.0
279
280
281
282       val min_binding : 'a t -> key * 'a
283
284       Return the binding with the smallest key in a given map  (with  respect
285       to the Ord.compare ordering), or raise Not_found if the map is empty.
286
287
288       Since 3.12.0
289
290
291
292       val min_binding_opt : 'a t -> (key * 'a) option
293
294       Return the binding with the smallest key in the given map (with respect
295       to the Ord.compare ordering), or None if the map is empty.
296
297
298       Since 4.05
299
300
301
302       val max_binding : 'a t -> key * 'a
303
304       Same as MoreLabels.Map.S.min_binding , but returns the binding with the
305       largest key in the given map.
306
307
308       Since 3.12.0
309
310
311
312       val max_binding_opt : 'a t -> (key * 'a) option
313
314       Same as MoreLabels.Map.S.min_binding_opt , but returns the binding with
315       the largest key in the given map.
316
317
318       Since 4.05
319
320
321
322       val choose : 'a t -> key * 'a
323
324       Return one binding of the given map, or raise Not_found if the  map  is
325       empty.  Which binding is chosen is unspecified, but equal bindings will
326       be chosen for equal maps.
327
328
329       Since 3.12.0
330
331
332
333       val choose_opt : 'a t -> (key * 'a) option
334
335       Return one binding of the given map, or None if the map is empty. Which
336       binding is chosen is unspecified, but equal bindings will be chosen for
337       equal maps.
338
339
340       Since 4.05
341
342
343
344       val split : key -> 'a t -> 'a t * 'a option * 'a t
345
346
347       split x m returns a triple (l, data, r) , where l is the map  with  all
348       the bindings of m whose key is strictly less than x ; r is the map with
349       all the bindings of m whose key is strictly greater than x  ;  data  is
350       None if m contains no binding for x , or Some v if m binds v to x .
351
352
353       Since 3.12.0
354
355
356
357       val find : key -> 'a t -> 'a
358
359
360       find  x  m returns the current value of x in m , or raises Not_found if
361       no binding for x exists.
362
363
364
365       val find_opt : key -> 'a t -> 'a option
366
367
368       find_opt x m returns Some v if the current value of x in m is  v  ,  or
369       None if no binding for x exists.
370
371
372       Since 4.05
373
374
375
376       val find_first : f:(key -> bool) -> 'a t -> key * 'a
377
378
379       find_first  ~f  m , where f is a monotonically increasing function, re‐
380       turns the binding of m with the lowest key k such that f k , or  raises
381       Not_found if no such key exists.
382
383       For  example,  find_first (fun k -> Ord.compare k x >= 0) m will return
384       the first binding k, v of m where Ord.compare k x >= 0 (intuitively:  k
385       >= x ), or raise Not_found if x is greater than any element of m .
386
387
388       Since 4.05
389
390
391
392       val find_first_opt : f:(key -> bool) -> 'a t -> (key * 'a) option
393
394
395       find_first_opt  ~f  m , where f is a monotonically increasing function,
396       returns an option containing the binding of m with  the  lowest  key  k
397       such that f k , or None if no such key exists.
398
399
400       Since 4.05
401
402
403
404       val find_last : f:(key -> bool) -> 'a t -> key * 'a
405
406
407       find_last  ~f  m  , where f is a monotonically decreasing function, re‐
408       turns the binding of m with the highest key k such that f k , or raises
409       Not_found if no such key exists.
410
411
412       Since 4.05
413
414
415
416       val find_last_opt : f:(key -> bool) -> 'a t -> (key * 'a) option
417
418
419       find_last_opt  ~f  m  , where f is a monotonically decreasing function,
420       returns an option containing the binding of m with the  highest  key  k
421       such that f k , or None if no such key exists.
422
423
424       Since 4.05
425
426
427
428       val map : f:('a -> 'b) -> 'a t -> 'b t
429
430
431       map  ~f  m  returns  a map with same domain as m , where the associated
432       value a of all bindings of m has been replaced by the result of the ap‐
433       plication of f to a .  The bindings are passed to f in increasing order
434       with respect to the ordering over the type of the keys.
435
436
437
438       val mapi : f:(key -> 'a -> 'b) -> 'a t -> 'b t
439
440       Same as MoreLabels.Map.S.map , but the function receives  as  arguments
441       both the key and the associated value for each binding of the map.
442
443
444
445
446   Iterators
447       val to_seq : 'a t -> (key * 'a) Seq.t
448
449       Iterate on the whole map, in ascending order of keys
450
451
452       Since 4.07
453
454
455
456       val to_rev_seq : 'a t -> (key * 'a) Seq.t
457
458       Iterate on the whole map, in descending order of keys
459
460
461       Since 4.12
462
463
464
465       val to_seq_from : key -> 'a t -> (key * 'a) Seq.t
466
467
468       to_seq_from  k m iterates on a subset of the bindings of m , in ascend‐
469       ing order of keys, from key k or above.
470
471
472       Since 4.07
473
474
475
476       val add_seq : (key * 'a) Seq.t -> 'a t -> 'a t
477
478       Add the given bindings to the map, in order.
479
480
481       Since 4.07
482
483
484
485       val of_seq : (key * 'a) Seq.t -> 'a t
486
487       Build a map from the given bindings
488
489
490       Since 4.07
491
492
493
494
495
496OCamldoc                          2021-07-22               MoreLabels.Map.S(3)
Impressum