Skip to main content

uqa_sql/ast/
assignment_target.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Ordered mutation targets shared by parsed and executable expressions.
8
9use serde::{Deserialize, Deserializer, Serialize, Serializer};
10
11/// The targets of one SET item. A multiple target consumes one positional subquery result.
12/// Single targets retain the predecessor's string or indirection-object encoding.
13#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
14#[serde(untagged)]
15pub enum AssignmentTargets<E = super::Expr> {
16    Single(AssignmentTarget<E>),
17    Multiple(MultipleAssignmentTargets<E>),
18}
19
20/// Native assignment operands are evaluated once and addressed by position while rebuilding their containers.
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22pub struct AssignmentBinding {
23    pub path: Vec<AssignmentPathStep>,
24    pub value_argument: usize,
25}
26
27#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
28pub enum AssignmentPathStep {
29    Field {
30        type_oid: u32,
31        number: i16,
32    },
33    Subscripts {
34        first_argument: usize,
35        dimensions: usize,
36        slice: bool,
37        bounds: super::ArraySliceBounds,
38    },
39}
40
41/// Positional outputs remain stable when a stored MERGE loses one of its target columns.
42#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
43pub struct MultipleAssignmentTargets<E> {
44    pub targets: Vec<AssignmentTarget<E>>,
45    pub source_positions: Vec<usize>,
46    pub source_width: usize,
47}
48
49impl<E> From<Vec<AssignmentTarget<E>>> for MultipleAssignmentTargets<E> {
50    fn from(targets: Vec<AssignmentTarget<E>>) -> Self {
51        Self {
52            source_positions: (0..targets.len()).collect(),
53            source_width: targets.len(),
54            targets,
55        }
56    }
57}
58
59impl<E> From<AssignmentTarget<E>> for AssignmentTargets<E> {
60    fn from(target: AssignmentTarget<E>) -> Self {
61        Self::Single(target)
62    }
63}
64
65impl<E> From<String> for AssignmentTargets<E> {
66    fn from(column: String) -> Self {
67        Self::Single(column.into())
68    }
69}
70
71impl<E> From<&str> for AssignmentTargets<E> {
72    fn from(column: &str) -> Self {
73        column.to_owned().into()
74    }
75}
76
77impl<E> AssignmentTargets<E> {
78    pub fn targets(&self) -> &[AssignmentTarget<E>] {
79        match self {
80            Self::Single(target) => std::slice::from_ref(target),
81            Self::Multiple(group) => &group.targets,
82        }
83    }
84
85    pub fn targets_mut(&mut self) -> &mut [AssignmentTarget<E>] {
86        match self {
87            Self::Single(target) => std::slice::from_mut(target),
88            Self::Multiple(group) => &mut group.targets,
89        }
90    }
91
92    pub fn source_position(&self, target: usize) -> usize {
93        match self {
94            Self::Single(_) => target,
95            Self::Multiple(group) => group.source_positions[target],
96        }
97    }
98
99    pub fn column_names(&self) -> impl Iterator<Item = &str> {
100        self.targets().iter().map(|target| target.column.as_str())
101    }
102
103    pub fn expressions(&self) -> impl Iterator<Item = &E> {
104        self.targets()
105            .iter()
106            .flat_map(AssignmentTarget::expressions)
107    }
108
109    pub fn expressions_mut(&mut self) -> impl Iterator<Item = &mut E> {
110        self.targets_mut()
111            .iter_mut()
112            .flat_map(AssignmentTarget::expressions_mut)
113    }
114
115    pub fn map<T>(self, mut map: impl FnMut(E) -> T) -> AssignmentTargets<T> {
116        match self {
117            Self::Single(target) => AssignmentTargets::Single(target.map(map)),
118            Self::Multiple(group) => AssignmentTargets::Multiple(MultipleAssignmentTargets {
119                targets: group
120                    .targets
121                    .into_iter()
122                    .map(|target| target.map(&mut map))
123                    .collect(),
124                source_positions: group.source_positions,
125                source_width: group.source_width,
126            }),
127        }
128    }
129}
130
131/// Target syntax is separate from the value expression. Every bound belongs to the original input row, even when repeated targets compose writes to one column.
132#[derive(Debug, Clone, PartialEq)]
133pub struct AssignmentTarget<E = super::Expr> {
134    pub column: String,
135    pub indirection: Vec<AssignmentStep<E>>,
136}
137
138#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
139pub enum AssignmentStep<E> {
140    Field(String),
141    Index(Box<E>),
142    Slice {
143        lower: Option<Box<E>>,
144        upper: Option<Box<E>>,
145    },
146}
147
148impl<E> From<String> for AssignmentTarget<E> {
149    fn from(column: String) -> Self {
150        Self {
151            column,
152            indirection: Vec::new(),
153        }
154    }
155}
156
157impl<E> From<&str> for AssignmentTarget<E> {
158    fn from(column: &str) -> Self {
159        column.to_owned().into()
160    }
161}
162
163impl<E> AssignmentTarget<E> {
164    pub fn is_whole_column(&self) -> bool {
165        self.indirection.is_empty()
166    }
167
168    pub fn expressions(&self) -> impl Iterator<Item = &E> {
169        self.indirection.iter().flat_map(|step| {
170            match step {
171                AssignmentStep::Field(_) => [None, None],
172                AssignmentStep::Index(index) => [Some(index.as_ref()), None],
173                AssignmentStep::Slice { lower, upper } => [lower.as_deref(), upper.as_deref()],
174            }
175            .into_iter()
176            .flatten()
177        })
178    }
179
180    pub fn expressions_mut(&mut self) -> impl Iterator<Item = &mut E> {
181        self.indirection.iter_mut().flat_map(|step| {
182            match step {
183                AssignmentStep::Field(_) => [None, None],
184                AssignmentStep::Index(index) => [Some(index.as_mut()), None],
185                AssignmentStep::Slice { lower, upper } => {
186                    [lower.as_deref_mut(), upper.as_deref_mut()]
187                }
188            }
189            .into_iter()
190            .flatten()
191        })
192    }
193
194    pub fn map<T>(self, mut map: impl FnMut(E) -> T) -> AssignmentTarget<T> {
195        AssignmentTarget {
196            column: self.column,
197            indirection: self
198                .indirection
199                .into_iter()
200                .map(|step| match step {
201                    AssignmentStep::Field(field) => AssignmentStep::Field(field),
202                    AssignmentStep::Index(index) => AssignmentStep::Index(Box::new(map(*index))),
203                    AssignmentStep::Slice { lower, upper } => AssignmentStep::Slice {
204                        lower: lower.map(|value| Box::new(map(*value))),
205                        upper: upper.map(|value| Box::new(map(*value))),
206                    },
207                })
208                .collect(),
209        }
210    }
211}
212
213impl<E: Serialize> Serialize for AssignmentTarget<E> {
214    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
215        #[derive(Serialize)]
216        #[serde(untagged)]
217        enum Target<'a, E> {
218            Column(&'a str),
219            Partial {
220                column: &'a str,
221                indirection: &'a [AssignmentStep<E>],
222            },
223        }
224        if self.is_whole_column() {
225            Target::<E>::Column(&self.column).serialize(serializer)
226        } else {
227            Target::Partial {
228                column: &self.column,
229                indirection: &self.indirection,
230            }
231            .serialize(serializer)
232        }
233    }
234}
235
236impl<'de, E: Deserialize<'de>> Deserialize<'de> for AssignmentTarget<E> {
237    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
238        #[derive(Deserialize)]
239        #[serde(untagged)]
240        enum Target<E> {
241            Column(String),
242            Partial {
243                column: String,
244                indirection: Vec<AssignmentStep<E>>,
245            },
246        }
247        Ok(match Target::deserialize(deserializer)? {
248            Target::Column(column) => column.into(),
249            Target::Partial {
250                column,
251                indirection,
252            } => Self {
253                column,
254                indirection,
255            },
256        })
257    }
258}
259
260#[cfg(test)]
261mod tests {
262    use super::*;
263
264    #[test]
265    fn ordinary_target_encoding_preserves_predecessor_definitions() {
266        let target: AssignmentTarget<i32> = serde_json::from_str("\"value\"").unwrap();
267        assert!(target.is_whole_column());
268        assert_eq!(target.column, "value");
269        assert_eq!(serde_json::to_string(&target).unwrap(), "\"value\"");
270        let group: AssignmentTargets<i32> = serde_json::from_str("\"value\"").unwrap();
271        assert!(matches!(group, AssignmentTargets::Single(_)));
272        assert_eq!(serde_json::to_string(&group).unwrap(), "\"value\"");
273        let grouped: AssignmentTargets<i32> =
274            AssignmentTargets::Multiple(vec!["a".into(), "b".into()].into());
275        let encoded = serde_json::to_string(&grouped).unwrap();
276        assert_eq!(
277            serde_json::from_str::<AssignmentTargets<i32>>(&encoded).unwrap(),
278            grouped
279        );
280    }
281
282    #[test]
283    fn partial_targets_keep_bound_omission_order_and_expression_rewrites() {
284        let mut target = AssignmentTarget {
285            column: "value".into(),
286            indirection: vec![
287                AssignmentStep::Index(Box::new(1)),
288                AssignmentStep::Field("items".into()),
289                AssignmentStep::Slice {
290                    lower: None,
291                    upper: Some(Box::new(2)),
292                },
293                AssignmentStep::Slice {
294                    lower: Some(Box::new(3)),
295                    upper: None,
296                },
297            ],
298        };
299        for value in target.expressions_mut() {
300            *value += 10;
301        }
302        assert_eq!(
303            target.expressions().copied().collect::<Vec<_>>(),
304            [11, 12, 13]
305        );
306        let rendered = serde_json::to_string(&target).unwrap();
307        assert_eq!(
308            serde_json::from_str::<AssignmentTarget<i32>>(&rendered).unwrap(),
309            target
310        );
311        let lowered = target.map(|value| value.to_string());
312        assert_eq!(
313            lowered
314                .expressions()
315                .map(String::as_str)
316                .collect::<Vec<_>>(),
317            ["11", "12", "13"]
318        );
319        assert!(matches!(
320            lowered.indirection[2],
321            AssignmentStep::Slice { lower: None, .. }
322        ));
323        assert!(matches!(
324            lowered.indirection[3],
325            AssignmentStep::Slice { upper: None, .. }
326        ));
327    }
328}