icydb_core/db/query/builder/
text_projection.rs

1//! Module: query::builder::text_projection
2//! Responsibility: shared bounded text-function builder surface and function
3//! semantics used by fluent terminals and canonical SQL projection execution.
4//! Does not own: generic query planning, grouped semantics, or SQL parsing.
5//! Boundary: models the admitted text-function family on top of canonical
6//! planner expressions without reopening a generic function registry.
7
8use crate::{
9    db::{
10        QueryError,
11        executor::projection::eval_builder_expr_for_value_preview,
12        query::{
13            builder::{
14                ValueProjectionExpr, scalar_projection::render_scalar_projection_expr_sql_label,
15            },
16            plan::expr::{Expr, FieldId, Function},
17        },
18    },
19    value::{InputValue, Value},
20};
21
22///
23/// TextProjectionExpr
24///
25/// Shared bounded text-function projection over one source field.
26/// This stays intentionally narrow even though it now lowers through the same
27/// canonical `Expr` surface used by SQL projection planning.
28///
29
30#[derive(Clone, Debug, Eq, PartialEq)]
31pub struct TextProjectionExpr {
32    field: String,
33    expr: Expr,
34}
35
36impl TextProjectionExpr {
37    // Build one field-function projection carrying only the source field.
38    pub(in crate::db) fn unary(field: impl Into<String>, function: Function) -> Self {
39        let field = field.into();
40
41        Self {
42            expr: Expr::FunctionCall {
43                function,
44                args: vec![Expr::Field(FieldId::new(field.clone()))],
45            },
46            field,
47        }
48    }
49
50    // Build one field-function projection carrying one literal argument.
51    pub(in crate::db) fn with_literal(
52        field: impl Into<String>,
53        function: Function,
54        literal: impl Into<InputValue>,
55    ) -> Self {
56        let field = field.into();
57
58        Self {
59            expr: Expr::FunctionCall {
60                function,
61                args: vec![
62                    Expr::Field(FieldId::new(field.clone())),
63                    Expr::Literal(Value::from(literal.into())),
64                ],
65            },
66            field,
67        }
68    }
69
70    // Build one field-function projection carrying two literal arguments.
71    pub(in crate::db) fn with_two_literals(
72        field: impl Into<String>,
73        function: Function,
74        literal: impl Into<InputValue>,
75        literal2: impl Into<InputValue>,
76    ) -> Self {
77        let field = field.into();
78
79        Self {
80            expr: Expr::FunctionCall {
81                function,
82                args: vec![
83                    Expr::Field(FieldId::new(field.clone())),
84                    Expr::Literal(Value::from(literal.into())),
85                    Expr::Literal(Value::from(literal2.into())),
86                ],
87            },
88            field,
89        }
90    }
91
92    // Build one `POSITION(literal, field)` projection.
93    pub(in crate::db) fn position(
94        field: impl Into<String>,
95        literal: impl Into<InputValue>,
96    ) -> Self {
97        let field = field.into();
98
99        Self {
100            expr: Expr::FunctionCall {
101                function: Function::Position,
102                args: vec![
103                    Expr::Literal(Value::from(literal.into())),
104                    Expr::Field(FieldId::new(field.clone())),
105                ],
106            },
107            field,
108        }
109    }
110
111    /// Borrow the canonical planner expression carried by this helper.
112    #[must_use]
113    pub(in crate::db) const fn expr(&self) -> &Expr {
114        &self.expr
115    }
116}
117
118impl ValueProjectionExpr for TextProjectionExpr {
119    fn field(&self) -> &str {
120        self.field.as_str()
121    }
122
123    fn sql_label(&self) -> String {
124        render_scalar_projection_expr_sql_label(&self.expr)
125    }
126
127    fn apply_value(&self, value: crate::value::Value) -> Result<crate::value::Value, QueryError> {
128        eval_builder_expr_for_value_preview(&self.expr, self.field.as_str(), &value)
129    }
130}
131
132/// Build `TRIM(field)`.
133#[must_use]
134pub fn trim(field: impl AsRef<str>) -> TextProjectionExpr {
135    TextProjectionExpr::unary(field.as_ref().to_string(), Function::Trim)
136}
137
138/// Build `LTRIM(field)`.
139#[must_use]
140pub fn ltrim(field: impl AsRef<str>) -> TextProjectionExpr {
141    TextProjectionExpr::unary(field.as_ref().to_string(), Function::Ltrim)
142}
143
144/// Build `RTRIM(field)`.
145#[must_use]
146pub fn rtrim(field: impl AsRef<str>) -> TextProjectionExpr {
147    TextProjectionExpr::unary(field.as_ref().to_string(), Function::Rtrim)
148}
149
150/// Build `LOWER(field)`.
151#[must_use]
152pub fn lower(field: impl AsRef<str>) -> TextProjectionExpr {
153    TextProjectionExpr::unary(field.as_ref().to_string(), Function::Lower)
154}
155
156/// Build `UPPER(field)`.
157#[must_use]
158pub fn upper(field: impl AsRef<str>) -> TextProjectionExpr {
159    TextProjectionExpr::unary(field.as_ref().to_string(), Function::Upper)
160}
161
162/// Build `LENGTH(field)`.
163#[must_use]
164pub fn length(field: impl AsRef<str>) -> TextProjectionExpr {
165    TextProjectionExpr::unary(field.as_ref().to_string(), Function::Length)
166}
167
168/// Build `LEFT(field, length)`.
169#[must_use]
170pub fn left(field: impl AsRef<str>, length: impl Into<InputValue>) -> TextProjectionExpr {
171    TextProjectionExpr::with_literal(field.as_ref().to_string(), Function::Left, length)
172}
173
174/// Build `RIGHT(field, length)`.
175#[must_use]
176pub fn right(field: impl AsRef<str>, length: impl Into<InputValue>) -> TextProjectionExpr {
177    TextProjectionExpr::with_literal(field.as_ref().to_string(), Function::Right, length)
178}
179
180/// Build `STARTS_WITH(field, literal)`.
181#[must_use]
182pub fn starts_with(field: impl AsRef<str>, literal: impl Into<InputValue>) -> TextProjectionExpr {
183    TextProjectionExpr::with_literal(field.as_ref().to_string(), Function::StartsWith, literal)
184}
185
186/// Build `ENDS_WITH(field, literal)`.
187#[must_use]
188pub fn ends_with(field: impl AsRef<str>, literal: impl Into<InputValue>) -> TextProjectionExpr {
189    TextProjectionExpr::with_literal(field.as_ref().to_string(), Function::EndsWith, literal)
190}
191
192/// Build `CONTAINS(field, literal)`.
193#[must_use]
194pub fn contains(field: impl AsRef<str>, literal: impl Into<InputValue>) -> TextProjectionExpr {
195    TextProjectionExpr::with_literal(field.as_ref().to_string(), Function::Contains, literal)
196}
197
198/// Build `POSITION(literal, field)`.
199#[must_use]
200pub fn position(field: impl AsRef<str>, literal: impl Into<InputValue>) -> TextProjectionExpr {
201    TextProjectionExpr::position(field.as_ref().to_string(), literal)
202}
203
204/// Build `REPLACE(field, from, to)`.
205#[must_use]
206pub fn replace(
207    field: impl AsRef<str>,
208    from: impl Into<InputValue>,
209    to: impl Into<InputValue>,
210) -> TextProjectionExpr {
211    TextProjectionExpr::with_two_literals(field.as_ref().to_string(), Function::Replace, from, to)
212}
213
214/// Build `SUBSTRING(field, start)`.
215#[must_use]
216pub fn substring(field: impl AsRef<str>, start: impl Into<InputValue>) -> TextProjectionExpr {
217    TextProjectionExpr::with_literal(field.as_ref().to_string(), Function::Substring, start)
218}
219
220/// Build `SUBSTRING(field, start, length)`.
221#[must_use]
222pub fn substring_with_length(
223    field: impl AsRef<str>,
224    start: impl Into<InputValue>,
225    length: impl Into<InputValue>,
226) -> TextProjectionExpr {
227    TextProjectionExpr::with_two_literals(
228        field.as_ref().to_string(),
229        Function::Substring,
230        start,
231        length,
232    )
233}
234
235///
236/// TESTS
237///
238
239#[cfg(test)]
240mod tests {
241    use super::*;
242    use crate::value::Value;
243
244    #[test]
245    fn lower_text_projection_renders_sql_label() {
246        assert_eq!(lower("name").sql_label(), "LOWER(name)");
247    }
248
249    #[test]
250    fn replace_text_projection_applies_shared_transform() {
251        let value = replace("name", "Ada", "Eve")
252            .apply_value(Value::Text("Ada Ada".to_string()))
253            .expect("replace projection should apply");
254
255        assert_eq!(value, Value::Text("Eve Eve".to_string()));
256    }
257}
icydb_core/db/query/builder/text_projection.rs

icydb_core/db/query/builder/
text_projection.rs
