matchkit 0.1.1

Vocabulary types for multi-pattern matching — Match struct, Matcher trait, shared errors
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

/// GPU-internal match representation — 4×u32, `bytemuck`-compatible.
///
/// This type maps directly to the GPU output buffer layout where each
/// match occupies exactly 16 bytes (4 × `u32`). The fields are:
///
/// - `[0]`: pattern_id
/// - `[1]`: start offset
/// - `[2]`: end offset
/// - `[3]`: reserved (padding / flags)
///
/// # Example
///
/// ```rust
/// use matchkit::{GpuMatch, Match};
///
/// let gpu_match = GpuMatch([1, 10, 20, 0]);
/// let m: Match = gpu_match.into();
/// assert_eq!(m.pattern_id, 1);
/// ```
#[repr(C)]
#[derive(Debug, Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
pub struct GpuMatch(
    /// Raw GPU match fields: `[pattern_id, start, end, padding]`.
    pub [u32; 4],
);

/// A match result from pattern scanning.
///
/// Uses `u32` offsets for GPU buffer compatibility. For inputs larger
/// than 4 GiB, scan in chunks and add the chunk base offset.
///
/// Uses `repr(C)` for GPU buffer compatibility. 16 bytes per match.
///
/// # Example
///
/// ```rust
/// use matchkit::Match;
///
/// let m = Match::from_parts(0, 5, 10);
/// assert_eq!(m.len(), 5);
/// assert!(m.contains(&Match::from_parts(0, 6, 8)));
/// ```
#[repr(C)]
#[derive(Debug, Clone, Copy, bytemuck::Pod, bytemuck::Zeroable, Default)]
pub struct Match {
    /// Index of the pattern that matched (0-based, in insertion order).
    pub pattern_id: u32,
    /// Byte offset where the match starts (inclusive).
    pub start: u32,
    /// Byte offset where the match ends (exclusive).
    pub end: u32,
    /// Padding for GPU alignment. Ignored in equality comparisons.
    pub padding: u32,
}

impl PartialEq for Match {
    fn eq(&self, other: &Self) -> bool {
        self.pattern_id == other.pattern_id && self.start == other.start && self.end == other.end
    }
}

impl Eq for Match {}

impl std::hash::Hash for Match {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.pattern_id.hash(state);
        self.start.hash(state);
        self.end.hash(state);
    }
}

impl PartialOrd for Match {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for Match {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.start
            .cmp(&other.start)
            .then(self.pattern_id.cmp(&other.pattern_id))
            .then(self.end.cmp(&other.end))
    }
}

impl Match {
    /// Construct a match from its public fields.
    #[must_use]
    pub const fn from_parts(pattern_id: u32, start: u32, end: u32) -> Self {
        Self {
            pattern_id,
            start,
            end,
            padding: 0,
        }
    }

    /// Returns the padding field (reserved for future use / GPU flags).
    #[must_use]
    pub const fn padding(&self) -> u32 {
        self.padding
    }

    /// Create a match with explicit padding value.
    ///
    /// Used internally by GPU backends that pack flags into the padding field.
    #[must_use]
    pub const fn from_parts_with_padding(
        pattern_id: u32,
        start: u32,
        end: u32,
        padding: u32,
    ) -> Self {
        Self {
            pattern_id,
            start,
            end,
            padding,
        }
    }

    /// Returns `true` if this match's byte range fully contains `other`.
    #[must_use]
    pub const fn contains(&self, other: &Match) -> bool {
        self.start <= other.start && self.end >= other.end
    }

    /// Returns `true` if this match's byte range overlaps with `other`.
    #[must_use]
    pub const fn overlaps(&self, other: &Match) -> bool {
        self.start < other.end && other.start < self.end
    }

    /// Byte length of the matched region.
    #[must_use]
    pub const fn len(&self) -> u32 {
        self.end.saturating_sub(self.start)
    }

    /// Returns `true` if the match has zero length.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.start == self.end
    }
}

impl From<GpuMatch> for Match {
    fn from(value: GpuMatch) -> Self {
        Self {
            pattern_id: value.0[0],
            start: value.0[1],
            end: value.0[2],
            padding: value.0[3],
        }
    }
}

impl From<Match> for GpuMatch {
    fn from(value: Match) -> Self {
        Self([value.pattern_id, value.start, value.end, value.padding])
    }
}