1\DOC delta_apply
2
3\TYPE {delta_apply : ('a -> 'a delta) -> 'a -> 'a}
4
5\SYNOPSIS
6Apply a function to an argument, re-using the argument if possible.
7
8\KEYWORDS
9sharing.
10
11\DESCRIBE
12An application {delta_apply f x} applies {f} to {x} and, if the
13result is {SAME}, returns {x}. If the result is {DIFF y}, then {y} is
14returned.
15
16\FAILURE
17If {f x} raises exception {e}, then {delta_apply f x} raises {e}.
18
19\EXAMPLE
20Suppose we want to write a function that replaces every even integer
21in a list of pairs of integers with an odd one. The most basic
22replacement function is therefore
23{
24   - fun ireplace i = if i mod 2 = 0 then DIFF (i+1) else SAME
25}
26Applying {ireplace} to an arbitrary integer would yield
27an element of the {int delta} type. It's not seemingly useful, but it
28becomes useful when used with similar functions for type operators.
29Then a delta function for pairs of integers is built by
30{delta_pair ireplace ireplace}, and a delta function for a list of
31pairs of integers is built by applying {delta_map}.
32{
33   - delta_map (delta_pair ireplace ireplace)
34               [(1,2), (3,5), (5,7), (4,8)];
35   > val it = DIFF [(1,3), (3,5), (5,7), (5,9)] : (int * int) list delta
36
37   - delta_map (delta_pair ireplace ireplace)
38               [(1,3), (3,5), (5,7), (7,9)];
39   > val it = SAME : (int * int) list delta
40}
41Finally, we can move the result from the {delta} type
42to the actual type we are interested in.
43{
44   - delta_apply (delta_map (delta_pair ireplace ireplace))
45               [(1,2), (3,5), (5,7), (4,8)];
46   > val it = [(1,3), (3,5), (5,7), (5,9)] : (int * int) list
47}
48
49
50\COMMENTS
51Used to change a function from one that returns an {'a delta} element to
52one that returns an {'a} element.
53
54\SEEALSO
55Lib.delta, Lib.delta_map, Lib.delta_pair.
56\ENDDOC
57