devela 0.28.0

A development substrate of coherence.
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
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

// devela::geom::metric::distance
//
//! Defines [`Region`][S][1|2|3], [`RegionStrided`].
//
// TOC
// - struct Region, type aliases
// - struct RegionStrided
// - implementations

use crate::{Extent, Position, Stride};

#[doc = crate::_tags!(geom)]
/// A [`Position`]ed [`Extent`].
#[doc = crate::_doc_meta!{location("geom/metric")}]
///
/// See also: [`Region1`], [`Region2`], [`Region3`],
/// [`RegionS`], [`RegionS1`], [`RegionS2`], [`RegionS3`].
#[must_use]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Region<P, E, const D: usize> {
    ///
    pub pos: Position<P, D>,
    ///
    pub ext: Extent<E, D>,
}

#[doc = crate::_tags!(geom)]
/// A 1-dimensional [`Region`].
#[doc = crate::_doc_meta!{location("geom/metric")}]
pub type Region1<P, E> = Region<P, E, 1>;

#[doc = crate::_tags!(geom)]
/// A 2-dimensional [`Region`].
#[doc = crate::_doc_meta!{location("geom/metric")}]
pub type Region2<P, E> = Region<P, E, 2>;

#[doc = crate::_tags!(geom)]
/// A 3-dimensional [`Region`].
#[doc = crate::_doc_meta!{location("geom/metric")}]
pub type Region3<P, E> = Region<P, E, 3>;

#[doc = crate::_tags!(geom)]
/// A [`Position`]ed [`Extent`] sharing the **S**ame type.
#[doc = crate::_doc_meta!{location("geom/metric")}]
pub type RegionS<T, const D: usize> = Region<T, T, D>;

#[doc = crate::_tags!(geom)]
/// A 1-dimensional [`RegionS`].
#[doc = crate::_doc_meta!{location("geom/metric")}]
pub type RegionS1<T> = RegionS<T, 1>;

#[doc = crate::_tags!(geom)]
/// A 2-dimensional [`RegionS`].
#[doc = crate::_doc_meta!{location("geom/metric")}]
pub type RegionS2<T> = RegionS<T, 2>;

#[doc = crate::_tags!(geom)]
/// A 3-dimensional [`RegionS`].
#[doc = crate::_doc_meta!{location("geom/metric")}]
pub type RegionS3<T> = RegionS<T, 3>;

#[doc = crate::_tags!(geom)]
/// A [`Stride`]d [`Region`] defining structured traversal.
#[doc = crate::_doc_meta!{location("geom/metric")}]
///
/// `RegionStrided` extends `Region` by adding a stride, allowing
/// structured access to subregions or non-contiguous patterns.
///
/// - Used in **grids, datasets, and memory layouts**.
/// - Supports **efficient structured stepping** (e.g. row-major iteration).
#[must_use]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct RegionStrided<P, E, const D: usize> {
    /// The positioned extent.
    pub region: Region<P, E, D>,
    /// The step size per dimension.
    pub stride: Stride<E, D>,
}

/* impls: constructors */

#[rustfmt::skip]
impl<P, E, const D: usize> Region<P, E, D> {
    /// Returns a new `Region` from a `pos`ition and an `ext`ent.
    pub const fn new(pos: Position<P, D>, ext: Extent<E, D>) -> Self { Self { pos, ext } }

    /// Returns a new `Region` from values convertible into a position and an extent.
    pub fn from_parts<PI, EI>(pos: PI, ext: EI) -> Self
    where
        PI: Into<Position<P, D>>,
        EI: Into<Extent<E, D>>,
    {
        Self::new(pos.into(), ext.into())
    }
}
impl<P, E> From<((P, P), (E, E))> for Region<P, E, 2> {
    fn from(((x, y), (w, h)): ((P, P), (E, E))) -> Self {
        Self {
            pos: Position::from((x, y)),
            ext: Extent::from((w, h)),
        }
    }
}
impl<P, E> From<((P, P, P), (E, E, E))> for Region<P, E, 3> {
    fn from(((x, y, z), (w, h, d)): ((P, P, P), (E, E, E))) -> Self {
        Self {
            pos: Position::from((x, y, z)),
            ext: Extent::from((w, h, d)),
        }
    }
}
impl<P, E, const D: usize> From<(Position<P, D>, Extent<E, D>)> for Region<P, E, D> {
    fn from(from: (Position<P, D>, Extent<E, D>)) -> Self {
        Self::new(from.0, from.1)
    }
}
impl<P, E, const D: usize> From<(Extent<E, D>, Position<P, D>)> for Region<P, E, D> {
    fn from(from: (Extent<E, D>, Position<P, D>)) -> Self {
        Self::new(from.1, from.0)
    }
}

/* impls: accessors */

#[rustfmt::skip]
impl<P: Copy, E: Copy> Region2<P, E> {
    #[must_use]
    /// Returns a copy of the first position dimension `x`.
    pub const fn x(self) -> P { self.pos.x() }
    #[must_use]
    /// Returns a copy of the second position dimension `y`.
    pub const fn y(self) -> P { self.pos.y() }

    #[must_use]
    /// Returns a copy of the first extent dimension `w`idth.
    pub const fn w(self) -> E { self.ext.w() }
    #[must_use]
    /// Returns a copy of the second extent dimension `h`eight.
    pub const fn h(self) -> E { self.ext.h() }
}

#[rustfmt::skip]
impl<P: Copy, E: Copy> Region3<P, E> {
    #[must_use]
    /// Returns a copy of the first position dimension `x`.
    pub const fn x(self) -> P { self.pos.x() }
    #[must_use]
    /// Returns a copy of the second position dimension `y`.
    pub const fn y(self) -> P { self.pos.y() }
    #[must_use]
    /// Returns a copy of the third position dimension `z`.
    pub const fn z(self) -> P { self.pos.z() }

    #[must_use]
    /// Returns a copy of the first extent dimension `w`idth.
    pub const fn w(self) -> E { self.ext.w() }
    #[must_use]
    /// Returns a copy of the second extent dimension `h`eight.
    pub const fn h(self) -> E { self.ext.h() }
    #[must_use]
    /// Returns a copy of the third extent dimension `d`epth.
    pub const fn d(self) -> E { self.ext.d() }
}

/* impls: mapping */

impl<P, E, const D: usize> Region<P, E, D> {
    /// Returns a new region by applying `f` to each position component.
    pub fn map_pos<P2>(self, f: impl FnMut(P) -> P2) -> Region<P2, E, D> {
        Region::new(self.pos.map(f), self.ext)
    }

    /// Returns a new region by applying `f` to each extent component.
    pub fn map_ext<E2>(self, f: impl FnMut(E) -> E2) -> Region<P, E2, D> {
        Region::new(self.pos, self.ext.map(f))
    }

    /// Returns a new region by applying `fpos` to the position and `fext` to the extent.
    pub fn map<P2, E2>(
        self,
        fpos: impl FnMut(P) -> P2,
        fext: impl FnMut(E) -> E2,
    ) -> Region<P2, E2, D> {
        Region::new(self.pos.map(fpos), self.ext.map(fext))
    }

    /// Returns a new region by fallibly applying `f` to each position component.
    pub fn try_map_pos<P2, X>(
        self,
        f: impl FnMut(P) -> Result<P2, X>,
    ) -> Result<Region<P2, E, D>, X> {
        Ok(Region::new(self.pos.try_map(f)?, self.ext))
    }

    /// Returns a new region by fallibly applying `f` to each extent component.
    pub fn try_map_ext<E2, X>(
        self,
        f: impl FnMut(E) -> Result<E2, X>,
    ) -> Result<Region<P, E2, D>, X> {
        Ok(Region::new(self.pos, self.ext.try_map(f)?))
    }

    /// Returns a new region by fallibly applying `fpos` to the position and
    /// `fext` to the extent.
    ///
    /// Both conversions must use the same error type.
    pub fn try_map<P2, E2, X>(
        self,
        fpos: impl FnMut(P) -> Result<P2, X>,
        fext: impl FnMut(E) -> Result<E2, X>,
    ) -> Result<Region<P2, E2, D>, X> {
        Ok(Region::new(self.pos.try_map(fpos)?, self.ext.try_map(fext)?))
    }

    /// Converts the position and extent using `From`.
    pub fn map_into<P2, E2>(self) -> Region<P2, E2, D>
    where
        P2: From<P>,
        E2: From<E>,
    {
        self.map(P2::from, E2::from)
    }

    /// Converts the position and extent using `TryFrom`.
    ///
    /// Both conversions must use the same error type.
    pub fn try_map_into<P2, E2, X>(self) -> Result<Region<P2, E2, D>, X>
    where
        P2: TryFrom<P, Error = X>,
        E2: TryFrom<E, Error = X>,
    {
        self.try_map(P2::try_from, E2::try_from)
    }
}