Skip to main content

uqa_sql/ast/
reference_name.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! SQL reference names with transient parser origins, independent of name identity.
8
9use std::{
10    borrow::Borrow,
11    cmp::Ordering,
12    fmt,
13    hash::{Hash, Hasher},
14    ops::{Deref, DerefMut},
15};
16
17/// A reference's name and optional one-based character position. Identity, ordering, hashing, debug rendering and serialization depend only on the name; serialized expressions never retain an earlier client's SQL position.
18#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]
19#[serde(transparent)]
20pub struct ReferenceName {
21    name: String,
22    #[serde(skip)]
23    position: Option<u32>,
24}
25
26impl ReferenceName {
27    #[must_use]
28    pub fn with_position(mut self, position: Option<u32>) -> Self {
29        self.position = position.filter(|position| *position != 0);
30        self
31    }
32
33    pub(crate) fn set_position(&mut self, position: Option<u32>) {
34        self.position = position.filter(|position| *position != 0);
35    }
36
37    #[must_use]
38    pub const fn position(&self) -> Option<u32> {
39        self.position
40    }
41
42    #[must_use]
43    pub fn as_str(&self) -> &str {
44        &self.name
45    }
46
47    /// Replace a bound name while preserving the reference's original source position.
48    pub fn rename(&mut self, name: &str) {
49        name.clone_into(&mut self.name);
50    }
51}
52
53impl From<String> for ReferenceName {
54    fn from(name: String) -> Self {
55        Self {
56            name,
57            position: None,
58        }
59    }
60}
61impl From<&str> for ReferenceName {
62    fn from(name: &str) -> Self {
63        name.to_owned().into()
64    }
65}
66impl From<&String> for ReferenceName {
67    fn from(name: &String) -> Self {
68        name.clone().into()
69    }
70}
71impl From<&ReferenceName> for ReferenceName {
72    fn from(name: &ReferenceName) -> Self {
73        name.clone()
74    }
75}
76impl From<ReferenceName> for String {
77    fn from(name: ReferenceName) -> Self {
78        name.name
79    }
80}
81impl From<&ReferenceName> for String {
82    fn from(name: &ReferenceName) -> Self {
83        name.name.clone()
84    }
85}
86impl Deref for ReferenceName {
87    type Target = String;
88    fn deref(&self) -> &String {
89        &self.name
90    }
91}
92impl DerefMut for ReferenceName {
93    fn deref_mut(&mut self) -> &mut String {
94        &mut self.name
95    }
96}
97impl AsRef<str> for ReferenceName {
98    fn as_ref(&self) -> &str {
99        &self.name
100    }
101}
102impl Borrow<str> for ReferenceName {
103    fn borrow(&self) -> &str {
104        &self.name
105    }
106}
107impl fmt::Display for ReferenceName {
108    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
109        self.name.fmt(formatter)
110    }
111}
112impl fmt::Debug for ReferenceName {
113    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
114        fmt::Debug::fmt(&self.name, formatter)
115    }
116}
117impl PartialEq for ReferenceName {
118    fn eq(&self, other: &Self) -> bool {
119        self.name == other.name
120    }
121}
122impl Eq for ReferenceName {}
123impl PartialOrd for ReferenceName {
124    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
125        Some(self.cmp(other))
126    }
127}
128impl Ord for ReferenceName {
129    fn cmp(&self, other: &Self) -> Ordering {
130        self.name.cmp(&other.name)
131    }
132}
133impl Hash for ReferenceName {
134    fn hash<H: Hasher>(&self, state: &mut H) {
135        self.name.hash(state);
136    }
137}
138impl PartialEq<String> for ReferenceName {
139    fn eq(&self, other: &String) -> bool {
140        self.name == *other
141    }
142}
143impl PartialEq<ReferenceName> for String {
144    fn eq(&self, other: &ReferenceName) -> bool {
145        *self == other.name
146    }
147}
148impl PartialEq<str> for ReferenceName {
149    fn eq(&self, other: &str) -> bool {
150        self.name == other
151    }
152}
153impl PartialEq<&str> for ReferenceName {
154    fn eq(&self, other: &&str) -> bool {
155        self.name == *other
156    }
157}
158impl PartialEq<ReferenceName> for str {
159    fn eq(&self, other: &ReferenceName) -> bool {
160        self == other.name
161    }
162}
163
164impl uqa_core::memory::ObserveAllocations for ReferenceName {
165    fn observe_allocations<'a>(
166        &'a self,
167        observer: &mut uqa_core::memory::AllocationObserver<'a, '_>,
168    ) -> Result<(), uqa_core::ValueRetentionError> {
169        let Self { name, position: _ } = self;
170        observer.child(name)?;
171        Ok(())
172    }
173}
174
175#[cfg(test)]
176mod tests {
177    use super::ReferenceName;
178    use std::collections::{BTreeSet, HashSet};
179
180    #[test]
181    fn diagnostic_origin_is_not_name_identity_or_persistent_state() {
182        let first = ReferenceName::from("Column").with_position(Some(12));
183        let second = ReferenceName::from("Column").with_position(Some(41));
184        assert_eq!(first, second);
185        assert_eq!(HashSet::from([first.clone(), second.clone()]).len(), 1);
186        assert_eq!(BTreeSet::from([first.clone(), second]).len(), 1);
187        assert_eq!(format!("{first:?}"), format!("{:?}", "Column"));
188        let encoded = serde_json::to_string(&first).unwrap();
189        assert_eq!(encoded, serde_json::to_string("Column").unwrap());
190        let restored: ReferenceName = serde_json::from_str(&encoded).unwrap();
191        assert_eq!(restored, first);
192        assert_eq!(restored.position(), None);
193        let mut renamed = first;
194        renamed.rename("bound_column");
195        assert_eq!(renamed, "bound_column");
196        assert_eq!(renamed.position(), Some(12));
197    }
198}