genz 0.4.0

Uniqueness of types via invariant lifetimes.
Documentation 
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

//! Anonymous lifetime markers.

use std::marker::PhantomData;

/// A covariant lifetime marker.
///
/// Because `f` is defined for an arbitrary lifetime `'c` and `Z` has a fixed lifetime, values referencing `'c` are 
/// prevented from escaping the closure:
///
/// ```compile_fail
/// # use genz::*;
///
/// struct Hidden<'c>(Scope<'c>);
///
/// let x = with_scope(|s| Hidden(s)); // lifetime may not live long enough
/// ```
///
/// The covariance of `Scope` with respect to its lifetime ensures that a subtyping relation between lifetimes 
/// implies a subtyping relation between `Scope` markers:
///
/// ``` 
/// # use genz::*;
///
/// fn same_scope<'c>(_: Scope<'c>, _: Scope<'c>)
/// {
///   assert!(true);
/// }
///
/// with_scope(|a| with_scope(|b| same_scope(a, b)));
/// ```
#[repr(transparent)]
#[derive(Copy, Clone)]
pub struct Scope<'c>(PhantomData<&'c ()>);

/// Invoke `f` with an covariant lifetime marker.
/// 
/// Because `f` is defined for an arbitrary lifetime `'c` and `Z` has a fixed lifetime, values referencing `'c` are 
/// prevented from escaping the closure:
///
/// ```compile_fail
/// # use genz::*;
///
/// struct Hidden<'c>(Scope<'c>);
///
/// let x = with_scope(|s| Hidden(s)); // lifetime may not live long enough
/// ```
///
/// The covariance of `Scope` with respect to its lifetime ensures that a subtyping relation between lifetimes 
/// implies a subtyping relation between `Scope` markers:
///
/// ``` 
/// # use genz::*;
///
/// fn same_scope<'c>(_: Scope<'c>, _: Scope<'c>)
/// {
///   assert!(true);
/// }
///
/// with_scope(|a| with_scope(|b| same_scope(a, b)));
/// ```
#[inline]
pub fn with_scope<F, Z>(f: F) -> Z 
  where 
    for<'c> F: FnOnce(Scope<'c>) -> Z 
{
  f(Scope(PhantomData))
}

/// An invariant lifetime marker.
///
/// Region markers are created via the `with_region` function. 
///
/// Because `f` is defined for an arbitrary lifetime `'c` and `Z` has a fixed lifetime, values referencing `'c` are 
/// prevented from escaping the closure:
///
/// ```compile_fail
/// # use genz::*;
///
/// struct Hidden<'c>(Region<'c>);
///
/// let x = with_region(|s| Hidden(s)); // lifetime may not live long enough
/// ```
///
/// The invariance of `Region` with respect to its lifetime ensures that there is no subtyping relation between the 
/// lifetimes of distinct `Region` markers:
///
/// ```compile_fail 
/// # use genz::*;
///
/// fn same_region<'c>(_: Region<'c>, _: Region<'c>)
/// {
/// }
///
/// with_region(|a| with_region(|b| same_region(a, b))); // fails to compile
/// ```
/// 
/// This property is passed through to any type referencing the region:
///
/// ```compile_fail
/// # use genz::*;
/// # use std::marker::PhantomData;
///
/// fn same_region<'c>(_: PhantomData<Region<'c>>, _: PhantomData<Region<'c>>)
/// {}
///
/// fn as_phantom<'c>(_: Region<'c>) -> PhantomData<Region<'c>>
/// { 
///   PhantomData
/// }
///
/// with_region(|a| with_region(|b| same_region(as_phantom(a), as_phantom(b))))
/// ```
#[repr(transparent)]
#[derive(Copy, Clone)]
pub struct Region<'c>(PhantomData<&'c mut &'c ()>);

/// The static region.
pub const STATIC_REGION: Region<'static> = Region(PhantomData);

/// Invoke `f` with an invariant lifetime marker.
/// 
/// Because `f` is defined for an arbitrary lifetime `'c` and `Z` has a fixed lifetime, values referencing `'c` are 
/// prevented from escaping the closure:
///
/// ```compile_fail
/// # use genz::*;
///
/// struct Hidden<'c>(Region<'c>);
///
/// let x = with_region(|s| Hidden(s)); // lifetime may not live long enough
/// ```
#[inline]
pub fn with_region<F, Z>(f: F) -> Z
  where 
    for<'c> F: FnOnce(Region<'c>) -> Z
{
  f(Region::<'static>(PhantomData))
}