Skip to main content

uqa_sql/expr/
variadic_any.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Built-ins declared `VARIADIC "any"`: an explicit `VARIADIC array` argument supplies the variadic values element by element, flattening every dimension, as `PostgreSQL`'s `extract_variadic_args` does.
8
9use uqa_core::Value;
10
11use super::{Result, SQLError};
12
13/// A call's evaluated arguments after an explicit `VARIADIC` array has been expanded.
14pub enum VariadicAnyArguments {
15    Arguments(Vec<(Option<String>, Value)>),
16    /// A NULL `VARIADIC` array makes the function return NULL without reading any value.
17    NullResult,
18}
19
20fn local_name(name: &str) -> std::borrow::Cow<'_, str> {
21    let local = match name.split_once('.') {
22        Some((schema, local)) if schema.eq_ignore_ascii_case("pg_catalog") => local,
23        _ => name,
24    };
25    crate::semantics::lowercase_function_name(local)
26}
27
28/// The number of fixed parameters before the `VARIADIC "any"` parameter, or `None` for any other routine.
29fn fixed_parameters(name: &str) -> Option<usize> {
30    Some(match local_name(name).as_ref() {
31        "concat" | "json_build_object" | "json_build_array" | "jsonb_build_object"
32        | "jsonb_build_array" | "num_nulls" | "num_nonnulls" => 0,
33        "concat_ws" | "format" => 1,
34        _ => return None,
35    })
36}
37
38/// Minimum arity across the variadic and nonvariadic overloads. A variadic `"any"` signature requires an argument; JSON builders have zero-argument overloads and `format(text)` omits the variadic tail.
39pub(crate) fn minimum_arguments(name: &str) -> Option<usize> {
40    let fixed = fixed_parameters(name)?;
41    Some(match local_name(name).as_ref() {
42        "json_build_object" | "json_build_array" | "jsonb_build_object" | "jsonb_build_array" => 0,
43        "format" => 1,
44        _ => fixed + 1,
45    })
46}
47
48/// Whether a built-in declares a `VARIADIC "any"` parameter.
49#[must_use]
50pub fn is_variadic_any(name: &str) -> bool {
51    fixed_parameters(name).is_some()
52}
53
54pub(crate) fn not_an_array() -> SQLError {
55    SQLError::Routine {
56        sqlstate: "42804".into(),
57        message: "VARIADIC argument must be an array".into(),
58    }
59}
60
61fn flatten(values: &[Value], output: &mut Vec<(Option<String>, Value)>) {
62    for value in values {
63        match value {
64            Value::List(values) => flatten(values, output),
65            value => output.push((None, value.clone())),
66        }
67    }
68}
69
70/// Expand the final explicit `VARIADIC` argument of a `VARIADIC "any"` built-in. Other calls keep their arguments.
71pub fn expand_variadic_any(
72    name: &str,
73    mut arguments: Vec<(Option<String>, Value)>,
74) -> Result<VariadicAnyArguments> {
75    let Some(fixed) = fixed_parameters(name) else {
76        return Ok(VariadicAnyArguments::Arguments(arguments));
77    };
78    if arguments.len() != fixed + 1 {
79        return Ok(VariadicAnyArguments::Arguments(arguments));
80    }
81    let Some((_, variadic)) = arguments.pop() else {
82        return Ok(VariadicAnyArguments::Arguments(arguments));
83    };
84    match variadic {
85        // `format` treats a NULL array as zero values; the other functions return NULL.
86        Value::Null if local_name(name) == "format" => {
87            Ok(VariadicAnyArguments::Arguments(arguments))
88        }
89        Value::Null => Ok(VariadicAnyArguments::NullResult),
90        Value::Array(array) => {
91            flatten(array.elements(), &mut arguments);
92            Ok(VariadicAnyArguments::Arguments(arguments))
93        }
94        Value::List(values) => {
95            flatten(&values, &mut arguments);
96            Ok(VariadicAnyArguments::Arguments(arguments))
97        }
98        _ => Err(not_an_array()),
99    }
100}