devela 0.27.0

A development layer 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

// devela::text::unit
//
//! Defines [`TextUnit`], [`TextIndex`], [`TextCursor`], [`TextRange`].
//!
//! > Low-level scalar and addressing types.
//

use crate::_impl_init;

#[doc = crate::_tags!(text)]
/// Primitive text-domain unit.
#[doc = crate::_doc_location!("text")]
///
/// `TextUnit` is the base primitive quantity used by text-related abstractions.
///
/// Depending on context, it may represent:
/// - positional magnitude in a text sequence
/// - inline extent or consumed space during layout
/// - other caller-defined text quantities
///
/// It has no inherent physical meaning and does not correspond directly to pixels,
/// glyphs, or characters unless a downstream layer defines that interpretation.
///
/// More specific wrappers such as [`TextIndex`] refine this primitive into a stricter role.
pub type TextUnit = u32;

#[must_use]
#[doc = crate::_tags!(text layout)]
/// Position within a caller-defined text-oriented sequence.
#[doc = crate::_doc_location!("text")]
///
/// The sequence may represent bytes, Unicode scalars, graphemes, layout symbols,
/// or other text-derived units chosen by the caller.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct TextIndex(pub u32);
_impl_init![ConstInit: Self(0) => TextIndex];

// pub struct TextOffset(pub i32); // MAYBE

#[rustfmt::skip]
impl TextIndex {
    /// Creates a new text index.
    pub const fn new(value: u32) -> Self { Self(value) }

    /// Returns the next index.
    /// # Panics
    /// Panics on overflow.
    pub const fn next(self) -> Self { Self(self.0 + 1) }

    /// Returns the next index, or `None` on overflow.
    pub const fn checked_next(self) -> Option<Self> {
        match self.0.checked_add(1) {
            Some(v) => Some(Self(v)),
            None => None,
        }
    }

    /// Converts to `usize` for indexing slices.
    pub const fn as_usize(self) -> usize { self.0 as usize }
}

#[must_use]
#[doc = crate::_tags!(text)]
/// Continuation point within a caller-defined text traversal.
#[doc = crate::_doc_location!("text")]
///
/// A `TextCursor` marks where a text-oriented process should resume.
///
/// The underlying sequence may represent bytes, Unicode scalars, graphemes,
/// layout symbols, or other caller-defined text units.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub struct TextCursor {
    /// Index of the next element in the traversal sequence.
    pub index: TextIndex,
}
_impl_init![ConstInit: Self::new_prim(0) => TextCursor];

impl TextCursor {
    /// Creates a new cursor at the given index.
    pub const fn new(index: TextIndex) -> Self {
        Self { index }
    }
    /// Creates a new cursor at the given primitive index.
    pub const fn new_prim(index: TextUnit) -> Self {
        Self { index: TextIndex(index) }
    }
}

#[must_use]
#[doc = crate::_tags!(text)]
/// A half-open range within a caller-defined text-oriented sequence.
#[doc = crate::_doc_location!("text")]
///
/// `TextRange` covers the interval `[start, end)`,
/// including `start` and excluding `end`.
///
/// The underlying sequence may represent bytes, Unicode scalars, graphemes,
/// layout symbols, or other caller-defined text units.
///
/// Empty ranges are valid and satisfy `start == end`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct TextRange {
    /// The first index included in the range.
    pub start: TextIndex,
    /// The first index excluded from the range.
    pub end: TextIndex,
}
_impl_init![ConstInit: Self::from_prim(0, 0) => TextRange];
impl TextRange {
    /// Creates a new half-open range from text indices.
    /// # Panics
    /// Panics if `start > end`.
    pub const fn new(start: TextIndex, end: TextIndex) -> Self {
        assert!(start.0 <= end.0, "TextRange requires start <= end");
        Self { start, end }
    }

    /// Creates a range from primitive indices.
    /// # Panics
    /// Panics if `start > end`.
    pub const fn from_prim(start: TextUnit, end: TextUnit) -> Self {
        Self::new(TextIndex(start), TextIndex(end))
    }

    /// Creates some range from a start index and a length, or `None` on overflow.
    pub const fn from_start_len(start: TextIndex, len: TextUnit) -> Option<Self> {
        match start.0.checked_add(len) {
            Some(end) => Some(Self { start, end: TextIndex(end) }),
            None => None,
        }
    }

    /// Returns `true` if the range is empty.
    pub const fn is_empty(self) -> bool {
        self.start.0 == self.end.0
    }
    /// Returns the range length in sequence units.
    pub const fn len(self) -> TextUnit {
        self.end.0 - self.start.0
    }
}