Source file invRelationSig.ml
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
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
(**
InvRelationSig - Signature of relations with access to inverse images.
*)
module type OrderedType = MapExtSig.OrderedType
module type S = sig
(** {2 Types} *)
type t
(** Represents a relation between a domain and a co-domain.
An element of [t] can be see as a set of bindings, i.e.,
a subset of [dom] * [codom], or as a function from [dom] to
subsets of [codom].
Relations are imutable, purely functional data-structures.
This data-type maintains both the relation and its inverse,
so that we can efficiently compute both the image of a domain
element and the inverse image of a codomain element, at the cost
of slower insersion and removal (to keep the maps consistent).
*)
type dom
(** An element of the domain. *)
type codom
(** An element of the codomain. *)
module DomSet : SetExtSig.S
(** Data-type for sets of domain elements. *)
module CoDomSet : SetExtSig.S
(** Data-type for sets of codomain elements. *)
type dom_set = DomSet.t
(** A set of elements of the domain. *)
type codom_set = CoDomSet.t
(** A set of elements of the codomain. *)
type binding = dom * codom
(** A binding. *)
(** {2 Construction and update} *)
val empty: t
(** The empty relation. *)
val image: dom -> t -> codom_set
(** [image x r] is the set of codomain elements associated to [x] in [r]
(possibly the empty set).
*)
val inverse: codom -> t -> dom_set
(** [inverse y r] is the set of domain elements associated to [y] in [r]
(possibly the empty set).
*)
val set_image: dom -> codom_set -> t -> t
(** [set_image x ys r] is a new relation where the image of [x]
has been updated to be [ys].
*)
val set_inverse: codom -> dom_set -> t -> t
(** [set_inverse y xs r] is a new relation where the inverse of [y]
has been updated to be [xs].
*)
val is_image_empty: dom -> t -> bool
(** [is_image_empty x r] returns true if there is a codomain element associated
to [x] in [r]
*)
val is_inverse_empty: codom -> t -> bool
(** [is_inverse_empty y r] returns true if there is a domain element associated
to [y] in [r].
*)
val is_empty: t -> bool
(** Whether the relation is empty. *)
val singleton: dom -> codom -> t
(** [singleton x y] is the relation with a unique binding ([x],[y]).
*)
val add: dom -> codom -> t -> t
(** [add x y r] returns [r] with a new binding ([x],[y]) added.
Previous bindings to [x] are preserved.
*)
val add_image_set: dom -> codom_set -> t -> t
(** [add_image_set x ys r] returns [r] with all the bindings ([x],[y]) for
[y] in the set [ys] added.
Others bindings are preserved.
*)
val add_inverse_set: codom -> dom_set -> t -> t
(** [add_inverse_set xs y r] returns [r] with all the bindings ([x],[y]) for
[x] in the set [xs] added.
Other bindings are preserved.
*)
val remove: dom -> codom -> t -> t
(** [remove x y r] returns [r] with the binding ([x],[y]) removed.
Other bindings are preserved.
*)
val remove_image_set: dom -> codom_set -> t -> t
(** [remove_image_set x ys r] returns [r] with a all bindings ([x],[y]) for
[y] in the set [ys] removed.
Other bindings are preserved.
*)
val remove_inverse_set: codom -> dom_set -> t -> t
(** [remove_inverse_set xs y r] returns [r] with a all bindings ([x],[y]) for
[x] in the set [xs] removed.
Other bindings are preserved.
*)
val remove_image: dom -> t -> t
(** [remove_image x r] returns [r] with all bindings ([x],[y]) removed.
*)
val remove_inverse: codom -> t -> t
(** [remove_inverse y r] returns [r] with all bindings ([x],[y]) removed.
*)
val mem: dom -> codom -> t -> bool
(** [mem x y r] returns [true] if the binding ([x],[y]) is present in [r].
*)
val mem_domain: dom -> t -> bool
(** [mem x r] returns [true] if a binding ([x],-) is present in [r].
*)
val mem_codomain: codom -> t -> bool
(** [mem x r] returns [true] if a binding (-,[-]) is present in [r].
*)
val of_list: binding list -> t
(** [of_list l] returns a relation constructed from the list of bindings. *)
val bindings: t -> binding list
(** [bindings r] lists the bindings in the relation. *)
val min_binding: t -> binding
(** [min_binding r] returns the smallest binding in [r], for the
lexicographic order of domain and codomain.
Raises [Not_found] if the relation is empty.
*)
val max_binding: t -> binding
(** [max_binding r] returns the largest binding in [r], for the
lexicographic order of domain and codomain.
Raises [Not_found] if the relation is empty.
*)
val choose: t -> binding
(** [choose r] returns an arbitrary binding in [r].
Raises [Not_found] if the relation is empty.
*)
val cardinal: t -> int
(** [cardinal r] returns the number of bindings in [r]. *)
(** {2 Global operations} *)
val iter: (dom -> codom -> unit) -> t -> unit
(** [iter f r] applies [f x y] to every binding ([x],[y]) of [r]. *)
val fold: (dom -> codom -> 'a -> 'a) -> t -> 'a -> 'a
(** [fold f r acc] folds [acc] through every binding ([x],[y]) in [r] through [f]. *)
val map: (dom -> codom -> binding) -> t -> t
(** [map f r] returns a relation where every binding ([x],[y]) is replaced
with ([x'],[y'])=[f x y].
The bindings are considered in increasing order for the lexicographic
order sorting through dom first, and then codom.
*)
val domain_map: (dom -> dom) -> t -> t
(** [domain_map f r] returns a relation where every binding ([x],[y]) is
replaced with ([f x],[y]).
The bindings are considered in increasing order for the lexicographic
order sorting through dom first, and then codom.
*)
val codomain_map: (codom -> codom) -> t -> t
(** [codomain_map f r] returns a relation where every binding ([x],[y])
is replaced with ([x],[f y]).
The bindings are considered in increasing order for the dual lexicographic
order sorting through codom first, and then dom.
*)
val for_all: (dom -> codom -> bool) -> t -> bool
(** [for_all f r] returns true if [f x y] is true for every binding
([x],[y]) in [r].
The bindings are considered in increasing order for the lexicographic
order sorting through dom first, and then codom.
*)
val exists: (dom -> codom -> bool) -> t -> bool
(** [exists f r] returns true if [f x y] is true for at leat one
binding ([x],[y]) in [r].
The bindings are considered in increasing order for the lexicographic
order sorting through dom first, and then codom.
*)
val filter: (dom -> codom -> bool) -> t -> t
(** [filter f r] returns a relation with only the bindings ([x],[y])
from [r] where [f x y] is true.
*)
(** {2 Set operations} *)
val compare: t -> t -> int
(** Total ordering function that returns -1, 0 or 1. *)
val equal: t -> t -> bool
(** Whether the two relations have the exact same set of bindings. *)
val subset: t -> t -> bool
(** [subset r1 r2] returns whether the set of bindings in [s1] is
included in the set of bindings in [s2].
*)
val union: t -> t -> t
(** [union r s] is the union of the bindings of [r] and [s]. *)
val inter: t -> t -> t
(** [inter r s] is the intersection of the bindings of [r] and [s]. *)
val diff: t -> t -> t
(** [diff r s] is the set difference of the bindings of [r] and [s]. *)
(** {2 Binary operations} *)
val iter2: (dom -> codom -> unit) -> (dom -> codom -> unit) -> (dom -> codom -> unit) -> t -> t -> unit
(** [iter2 f1 f2 f r1 r2] applies [f1] to the bindings only in [r1],
[f2] to the bindings only in [r2], and [f] to the bindings in both
[r1] and [r2].
The bindings are considered in increasing lexicographic order.
*)
val fold2: (dom -> codom -> 'a -> 'a) -> (dom -> codom -> 'a -> 'a) -> (dom -> codom -> 'a -> 'a) -> t -> t -> 'a -> 'a
(** [fold2 f1 f2 f r1 r2] applies [f1] to the bindings only in [r1],
[f2] to the bindings only in [r2], and [f] to the bindings in both
[r1] and [r2].
The bindings are considered in increasing lexicographic order.
*)
val for_all2: (dom -> codom -> bool) -> (dom -> codom -> bool) -> (dom -> codom -> bool) -> t -> t -> bool
(** [for_all2 f1 f2 f r1 r2] is true if [f1] is true on all the bindings
only in [r1], [f2] is true on all the bindings only in [r2], and [f]
is true on all the bindings both in [r1] and [r2].
The bindings are considered in increasing lexicographic order.
*)
val exists2: (dom -> codom -> bool) -> (dom -> codom -> bool) -> (dom -> codom -> bool) -> t -> t -> bool
(** [exists2 f1 f2 f r1 r2] is true if [f1] is true on one binding
only in [r1] or [f2] is true on one binding only in [r2], or [f]
is true on one binding both in [r1] and [r2].
The bindings are considered in increasing lexicographic order.
*)
val iter2_diff: (dom -> codom -> unit) -> (dom -> codom -> unit) -> t -> t -> unit
(** [iter2_diff f1 f2 r1 r2] applies [f1] to the bindings only in [r1]
and [f2] to the bindings only in [r2].
The bindings both in [r1] and [r2] are ignored.
The bindings are considered in increasing lexicographic order.
It is equivalent to calling [iter2] with [f = fun x y -> ()],
but more efficient.
*)
val fold2_diff: (dom -> codom -> 'a -> 'a) -> (dom -> codom -> 'a -> 'a) -> t -> t -> 'a -> 'a
(** [fold2_diff f1 f2 r1 r2] applies [f1] to the bindings only in [r1]
and [f2] to the bindings only in [r2].
The bindings both in [r1] and [r2] are ignored.
The bindings are considered in increasing lexicographic order.
It is equivalent to calling [fold2] with [f = fun x y acc -> acc],
but more efficient.
*)
val for_all2_diff: (dom -> codom -> bool) -> (dom -> codom -> bool) -> t -> t -> bool
(** [for_all2_diff f1 f2 f r1 r2] is true if [f1] is true on all the bindings
only in [r1] and [f2] is true on all the bindings only in [r2].
The bindings both in [r1] and [r2] are ignored.
The bindings are considered in increasing lexicographic order.
It is equivalent to calling [for_all2] with [f = fun x y -> true], but more efficient.
*)
val exists2_diff: (dom -> codom -> bool) -> (dom -> codom -> bool) -> t -> t -> bool
(** [exists2_diff f1 f2 f r1 r2] is true if [f1] is true on one binding
only in [r1] or [f2] is true on one binding only in [r2].
The bindings both in [r1] and [r2] are ignored.
The bindings are considered in increasing lexicographic order.
It is equivalent to calling [exists2] with [f = fun x y -> false], but more efficient.
*)
(** {2 Multi-map domain operations} *)
(** These functions consider the relation as a map from domain elements
to codomain sets.
*)
val iter_domain: (dom -> codom_set -> unit) -> t -> unit
(** [iter_domain f r] applies [f x ys] for every domain element [x] and
its image set [ys] in [r].
The domain elements are considered in increasing order.
*)
val fold_domain: (dom -> codom_set -> 'a -> 'a) -> t -> 'a -> 'a
(** [fold_domain f r acc] applies [f x ys acc] for every domain element
[x] and its image set [ys] in [r].
The domain elements are considered in increasing order.
*)
val map_domain: (dom -> codom_set -> codom_set) -> t -> t
(** [map_domain f r] returns a new relation where the image set [ys] of
[x] in [r] is replaced with [f x ys].
The domain elements are considered in increasing order.
*)
val map2_domain: (dom -> codom_set -> codom_set -> codom_set) -> t -> t -> t
(** [map2_domain f r1 r2] is similar to [map_domain] but applies [f]
to pairs of image sets [ys1] and [ys2] corresponding to the same
domain element [x] in [r1] and [r2] respectively.
[r1] and [r2] must have the same domain set.
The bindings are passed to [f] in increasing order of domain elements.
*)
val map2o_domain: (dom -> codom_set -> codom_set) -> (dom -> codom_set -> codom_set) -> (dom -> codom_set -> codom_set -> codom_set) -> t -> t -> t
(** [map2_domain f1 f2 f r1 r2] is similar to [map2_domain] but accepts
relations with different domain sets. To get a new binding, [f1]
is used for domain elements appearing only in [r1], [f2] for
domain elements appearing only in [r2] and [f] for common domain
elements.
The bindings are passed in increasing order of domain elements.
*)
val map2zo_domain: (dom -> codom_set -> codom_set) -> (dom -> codom_set -> codom_set) -> (dom -> codom_set -> codom_set -> codom_set) -> t -> t -> t
(** [map2zo_domain f1 f2 f r1 r2] is similar to [map2o_domain] but
[f] is not called on physically equal image sets.
The bindings are passed in increasing order of domain elements.
*)
(** [map_domain f r] returns a new relation where the image set [ys] of
[x] in [r] is replaced with [f x ys].
The domain elements are considered in increasing order.
*)
val for_all_domain: (dom -> codom_set -> bool) -> t -> bool
(** [for_all_domain f r] returns true if [f x ys] is true for every
domain element [x] and its image set [ys] in [r].
The domain elements are considered in increasing order.
*)
val exists_domain: (dom -> codom_set -> bool) -> t -> bool
(** [exists_domain f r] returns true if [f x ys] is true for at least
one domain element [x] and its image set [ys] in [r].
The domain elements are considered in increasing order.
*)
val filter_domain: (dom -> codom_set -> bool) -> t -> t
(** [filter_domain f r] returns a new relation restricted to the
domain elements [x] with their image [ys] from [r] such that
[f x ys] is true.
*)
val min_domain: t -> dom
(** [min_domain r] returns the smallest domain element in [r].
Raises [Not_found] if the relation is empty.
*)
val max_domain: t -> dom
(** [max_domain r] returns the greatest domain element in [r].
Raises [Not_found] if the relation is empty.
*)
val choose_domain: t -> dom
(** [choose_domain r] returns any domain element in [r].
Raises [Not_found] if the relation is empty.
*)
val cardinal_domain: t -> int
(** [cardinal r] returns the number of distinct domain elements used in [r]. *)
val elements_domain: t -> dom list
(** [elemets_domain r] returns the list of domain elements used in [r].
The elements are returned in increasing order.
*)
(** {2 Multi-map codomain operations} *)
(** These functions consider the relation as a map from codomain elements
to domain sets.
*)
val iter_codomain: (codom -> dom_set -> unit) -> t -> unit
(** [iter_codomain f r] applies [f y xs] for every codomain element [y] and
its inverse image set [xs] in [r].
The codomain elements are considered in increasing order.
*)
val fold_codomain: (codom -> dom_set -> 'a -> 'a) -> t -> 'a -> 'a
(** [fold_codomain f r acc] applies [f y xs acc] for every codomain element
[y] and its inverse image set [xs] in [r].
The codomain elements are considered in increasing order.
*)
val map_codomain: (codom -> dom_set -> dom_set) -> t -> t
(** [map_codomain f r] returns a new relation where the inverse image set [xs] of
[y] in [r] is replaced with [f y xs].
The codomain elements are considered in increasing order.
*)
val for_all_codomain: (codom -> dom_set -> bool) -> t -> bool
(** [for_all_codomain f r] returns true if [f y xs] is true for every
codomain element [y] and its inverse image set [xs] in [r].
The codomain elements are considered in increasing order.
*)
val exists_codomain: (codom -> dom_set -> bool) -> t -> bool
(** [exists_codomain f r] returns true if [f y xs] is true for at least
one codomain element [y] and its inverse image set [xs] in [r].
The codomain elements are considered in increasing order.
*)
val filter_codomain: (codom -> dom_set -> bool) -> t -> t
(** [filter_codomain f r] returns a new relation restricted to the
codomain elements [y] with their inverse image [xs] from [r] such that
[f y xs] is true.
*)
val min_codomain: t -> codom
(** [min_codomain r] returns the smallest codomain element in [r].
Raises [Not_found] if the relation is empty.
*)
val max_codomain: t -> codom
(** [max_codomain r] returns the greatest codomain element in [r].
Raises [Not_found] if the relation is empty.
*)
val choose_codomain: t -> codom
(** [choose_codomain r] returns any codomain element in [r].
Raises [Not_found] if the relation is empty.
*)
val cardinal_codomain: t -> int
(** [cardinal r] returns the number of distinct codomain elements used in [r]. *)
val elements_codomain: t -> codom list
(** [elemets_codomain r] returns the list of codomain elements used in [r].
The elements are returned in increasing order.
*)
(** {2 Printing} *)
type relation_printer = {
print_empty: string; (** Special text for empty relations *)
print_begin: string; (** Text before the first binding *)
print_open: string; (** Text before a domain element *)
print_comma: string; (** Text between a domain and a codomain element *)
print_close: string; (** Text after a codomain element *)
print_sep: string; (** Text between two bindings *)
print_end: string; (** Text after the last binding *)
}
(** Tells how to print a relation. *)
val printer_default: relation_printer
(** Print as set: {(dom1,codom1),...,(domN,codomN)} *)
val to_string: relation_printer -> (dom -> string) -> (codom -> string) -> t -> string
(** String representation. *)
val print: relation_printer -> (out_channel -> dom -> unit) -> (out_channel -> codom -> unit) -> out_channel -> t -> unit
(** Prints to an output_channel (for Printf.(f)printf). *)
val fprint: relation_printer -> (Format.formatter -> dom -> unit) -> (Format.formatter -> codom -> unit) -> Format.formatter -> t -> unit
(** Prints to a formatter (for Format.(f)printf). *)
val bprint: relation_printer -> (Buffer.t -> dom -> unit) -> (Buffer.t -> codom -> unit) -> Buffer.t -> t -> unit
(** Prints to a string buffer (for Printf.bprintf). *)
end