Skip to main content

uqa_sql/ast/types/
identity.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! OID identities of user-defined types. Stored syntax, routine signatures and bound casts name a user-defined type by identity, so a rename, a schema move or a different search path cannot change which type they mean; output spells the type's current name. `#` cannot occur in an unquoted type name, and quoted names keep their quotes, so an identity never collides with a name as written.
8
9use super::ColumnType;
10mod production;
11
12const ENUM_PREFIX: &str = "enum#";
13const DOMAIN_PREFIX: &str = "domain#";
14const COMPOSITE_PREFIX: &str = "composite#";
15const RANGE_PREFIX: &str = "range#";
16const MULTIRANGE_PREFIX: &str = "multirange#";
17
18pub(super) fn write_identity(ty: &ColumnType, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
19    match ty {
20        ColumnType::Enum(reference) => write!(f, "{ENUM_PREFIX}{}", reference.oid),
21        ColumnType::Composite(reference) => write!(f, "{COMPOSITE_PREFIX}{}", reference.oid),
22        ColumnType::DeclaredRange(reference) => write!(f, "{RANGE_PREFIX}{}", reference.oid),
23        ColumnType::DeclaredMultirange(reference) => {
24            write!(f, "{MULTIRANGE_PREFIX}{}", reference.oid)
25        }
26        ColumnType::Domain { oid, .. } => write!(f, "{DOMAIN_PREFIX}{oid}"),
27        _ => unreachable!("catalog identity formatter requires a user-defined scalar type"),
28    }
29}
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum UserTypeKind {
33    Enum,
34    Domain,
35    Composite,
36    Range,
37    Multirange,
38}
39
40/// A parsed identity: the type's kind and OID, and the number of array dimensions around it.
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub struct UserTypeIdentity {
43    pub kind: UserTypeKind,
44    pub oid: u32,
45    pub dimensions: usize,
46}
47
48impl UserTypeIdentity {
49    /// Parse `enum#<oid>`, `domain#<oid>` or `composite#<oid>` with any number of `[]` suffixes.
50    #[must_use]
51    pub fn parse(name: &str) -> Option<Self> {
52        let mut element = name.trim();
53        let mut dimensions = 0usize;
54        while let Some(inner) = element.strip_suffix("[]") {
55            element = inner;
56            dimensions += 1;
57        }
58        let (kind, oid) = if let Some(oid) = element.strip_prefix(ENUM_PREFIX) {
59            (UserTypeKind::Enum, oid)
60        } else if let Some(oid) = element.strip_prefix(COMPOSITE_PREFIX) {
61            (UserTypeKind::Composite, oid)
62        } else if let Some(oid) = element.strip_prefix(RANGE_PREFIX) {
63            (UserTypeKind::Range, oid)
64        } else if let Some(oid) = element.strip_prefix(MULTIRANGE_PREFIX) {
65            (UserTypeKind::Multirange, oid)
66        } else {
67            (UserTypeKind::Domain, element.strip_prefix(DOMAIN_PREFIX)?)
68        };
69        if oid.is_empty() || !oid.bytes().all(|byte| byte.is_ascii_digit()) {
70            return None;
71        }
72        Some(Self {
73            kind,
74            oid: oid.parse().ok()?,
75            dimensions,
76        })
77    }
78}
79
80impl ColumnType {
81    /// Whether a retained value of this type may name database-owned catalog identities. Anonymous records and polymorphic arrays may contain user-defined fields or elements, so their original database remains required even without a declared outer OID.
82    #[must_use]
83    pub fn is_catalog_dependent(&self) -> bool {
84        let mut ty = self;
85        while let Self::Array(element) = ty {
86            ty = element;
87        }
88        matches!(
89            ty,
90            Self::Named(_)
91                | Self::Enum(_)
92                | Self::Composite(_)
93                | Self::Domain { .. }
94                | Self::DeclaredRange(_)
95                | Self::DeclaredMultirange(_)
96                | Self::Record
97                | Self::AnyArray
98        )
99    }
100
101    /// The identity of a user-defined type or an array of one; built-in types have none.
102    #[must_use]
103    pub fn user_type_identity(&self) -> Option<String> {
104        self.user_type_identity_with_control(&uqa_core::memory::ProductionControl::uncontrolled())
105            .expect("ordinary catalog identity cannot be cancelled or limited")
106            .map(|value| {
107                value
108                    .into_uncontrolled()
109                    .expect("ordinary catalog identity")
110            })
111    }
112}
113
114#[cfg(test)]
115mod tests {
116    use super::{UserTypeIdentity, UserTypeKind};
117    use crate::ast::{ColumnType, EnumTypeReference};
118
119    #[test]
120    fn identities_round_trip_through_arrays() {
121        let mood = ColumnType::Enum(EnumTypeReference {
122            schema: "public".into(),
123            name: "mood".into(),
124            oid: 20_000,
125            array_oid: 20_001,
126        });
127        let array = ColumnType::Array(Box::new(ColumnType::Array(Box::new(mood))));
128        assert!(array.is_catalog_dependent());
129        assert!(ColumnType::Record.is_catalog_dependent());
130        assert!(!ColumnType::Array(Box::new(ColumnType::Integer)).is_catalog_dependent());
131        let identity = array.user_type_identity().unwrap();
132        assert_eq!(identity, "enum#20000[][]");
133        assert_eq!(
134            UserTypeIdentity::parse(&identity),
135            Some(UserTypeIdentity {
136                kind: UserTypeKind::Enum,
137                oid: 20_000,
138                dimensions: 2,
139            })
140        );
141        assert_eq!(
142            UserTypeIdentity::parse("composite#9[]"),
143            Some(UserTypeIdentity {
144                kind: UserTypeKind::Composite,
145                oid: 9,
146                dimensions: 1,
147            })
148        );
149        assert_eq!(
150            UserTypeIdentity::parse("domain#7"),
151            Some(UserTypeIdentity {
152                kind: UserTypeKind::Domain,
153                oid: 7,
154                dimensions: 0,
155            })
156        );
157        for name in ["\"enum#1\"", "enum#", "enum#x", "domain#-1", "integer"] {
158            assert_eq!(UserTypeIdentity::parse(name), None, "{name}");
159        }
160        assert_eq!(ColumnType::Integer.user_type_identity(), None);
161    }
162}