risingwave_common/types/macros.rs
1// Copyright 2025 RisingWave Labs
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15/// `for_all_variants` includes all variants of our type system. If you introduced a new array type
16/// (also known as scalar type or physical type), be sure to add a variant here.
17///
18/// It is used to simplify the boilerplate code of repeating all array types, while each type
19/// has exactly the same code.
20///
21/// Take `Utf8` as an example, the layout of the variant is:
22/// - `$data_type: Varchar` data type variant name, e.g. `DataType::Varchar`
23/// - `$variant_name: Utf8` array type variant name, e.g. `ArrayImpl::Utf8`, `ScalarImpl::Utf8`
24/// - `$suffix_name: utf8` the suffix of some functions, e.g. `ArrayImpl::as_utf8`
25/// - `$scalar: Box<str>` the scalar type, e.g. `ScalarImpl::Utf8(Box<str>)`
26/// - `$scalar_ref: &'scalar str` the scalar reference type, e.g. `ScalarRefImpl::Utf8(&'scalar
27/// str)`
28/// - `$array: Utf8Array` the array type, e.g. `ArrayImpl::Utf8(Utf8Array)`
29/// - `$builder: Utf8ArrayBuilder` the array builder type, e.g.
30/// `ArrayBuilderImpl::Utf8(Utf8ArrayBuilder)`
31///
32/// To use it, one need to provide another macro which accepts arguments in the layout described
33/// above. Refer to the following implementations as examples.
34///
35/// **Note**: See also `dispatch_xx_variants` and `dispatch_data_types` which doesn't require
36/// another macro for the implementation and can be easier to use in most cases.
37#[macro_export]
38macro_rules! for_all_variants {
39 ($macro:ident $(, $x:tt)*) => {
40 $macro! {
41 $($x, )*
42 //data_type variant_name suffix_name scalar scalar_ref array builder
43 { Int16, Int16, int16, i16, i16, $crate::array::I16Array, $crate::array::I16ArrayBuilder },
44 { Int32, Int32, int32, i32, i32, $crate::array::I32Array, $crate::array::I32ArrayBuilder },
45 { Int64, Int64, int64, i64, i64, $crate::array::I64Array, $crate::array::I64ArrayBuilder },
46 { Int256, Int256, int256, $crate::types::Int256, $crate::types::Int256Ref<'scalar>, $crate::array::Int256Array, $crate::array::Int256ArrayBuilder },
47 { Float32, Float32, float32, $crate::types::F32, $crate::types::F32, $crate::array::F32Array, $crate::array::F32ArrayBuilder },
48 { Float64, Float64, float64, $crate::types::F64, $crate::types::F64, $crate::array::F64Array, $crate::array::F64ArrayBuilder },
49 { Varchar, Utf8, utf8, Box<str>, &'scalar str, $crate::array::Utf8Array, $crate::array::Utf8ArrayBuilder },
50 { Boolean, Bool, bool, bool, bool, $crate::array::BoolArray, $crate::array::BoolArrayBuilder },
51 { Decimal, Decimal, decimal, $crate::types::Decimal, $crate::types::Decimal, $crate::array::DecimalArray, $crate::array::DecimalArrayBuilder },
52 { Interval, Interval, interval, $crate::types::Interval, $crate::types::Interval, $crate::array::IntervalArray, $crate::array::IntervalArrayBuilder },
53 { Date, Date, date, $crate::types::Date, $crate::types::Date, $crate::array::DateArray, $crate::array::DateArrayBuilder },
54 { Time, Time, time, $crate::types::Time, $crate::types::Time, $crate::array::TimeArray, $crate::array::TimeArrayBuilder },
55 { Timestamp, Timestamp, timestamp, $crate::types::Timestamp, $crate::types::Timestamp, $crate::array::TimestampArray, $crate::array::TimestampArrayBuilder },
56 { Timestamptz, Timestamptz, timestamptz, $crate::types::Timestamptz, $crate::types::Timestamptz, $crate::array::TimestamptzArray, $crate::array::TimestamptzArrayBuilder },
57 { Jsonb, Jsonb, jsonb, $crate::types::JsonbVal, $crate::types::JsonbRef<'scalar>, $crate::array::JsonbArray, $crate::array::JsonbArrayBuilder },
58 { Serial, Serial, serial, $crate::types::Serial, $crate::types::Serial, $crate::array::SerialArray, $crate::array::SerialArrayBuilder },
59 { Struct, Struct, struct, $crate::types::StructValue, $crate::types::StructRef<'scalar>, $crate::array::StructArray, $crate::array::StructArrayBuilder },
60 { List, List, list, $crate::types::ListValue, $crate::types::ListRef<'scalar>, $crate::array::ListArray, $crate::array::ListArrayBuilder },
61 { Map, Map, map, $crate::types::MapValue, $crate::types::MapRef<'scalar>, $crate::array::MapArray, $crate::array::MapArrayBuilder },
62 { Bytea, Bytea, bytea, Box<[u8]>, &'scalar [u8], $crate::array::BytesArray, $crate::array::BytesArrayBuilder }
63 }
64 };
65}
66
67/// Helper macro for expanding type aliases and constants. Internally used by `dispatch_` macros.
68#[macro_export]
69macro_rules! do_expand_alias {
70 ($array:ty, $variant_name:ident, (
71 $(Array, $array_alias:ident,)?
72 $(ArrayBuilder, $array_builder_alias:ident,)?
73 $(Scalar, $scalar_alias:ident,)?
74 $(ScalarRef, $scalar_ref_alias:ident,)?
75 $(VARIANT_NAME, $variant_name_alias:ident,)?
76 )) => {
77 $(type $array_alias = $array;)?
78 $(type $array_builder_alias = <$array as $crate::array::Array>::Builder;)?
79 $(type $scalar_alias = <$array as $crate::array::Array>::OwnedItem;)?
80 $(type $scalar_ref_alias<'scalar> = <$array as $crate::array::Array>::RefItem<'scalar>;)?
81 $(const $variant_name_alias: &'static str = stringify!($variant_name);)?
82 };
83}
84
85/// Helper macro for generating dispatching code. Internally used by `dispatch_xx_variants` macros.
86#[macro_export(local_inner_macros)]
87macro_rules! do_dispatch_variants {
88 // Use `tt` for `$alias` as a workaround of nested repetition.
89 ($impl:expr, $type:ident, $inner:pat, [$alias:tt], $body:tt, $( { $data_type:ident, $variant_name:ident, $suffix_name:ident, $scalar:ty, $scalar_ref:ty, $array:ty, $builder:ty } ),*) => {
90 match $impl {
91 $( $type::$variant_name($inner) => {
92 do_expand_alias!($array, $variant_name, $alias);
93 #[allow(unused_braces)]
94 $body
95 }, )*
96 }
97 };
98}
99
100/// Dispatch the code block to all variants of `ArrayImpl`.
101///
102/// # Usage
103///
104/// The basic usage to access the inner concrete `impl Array` value is:
105///
106/// ```ignore
107/// fn do_stuff<A: Array>(array: &A) { .. }
108///
109/// fn do_stuff_dispatch(array_impl: &ArrayImpl) {
110/// dispatch_array_variants!(array_impl, array, {
111/// do_stuff(array)
112/// })
113/// }
114/// ```
115///
116/// One can also bind the inner concrete `impl Array` type to an alias:
117///
118/// ```ignore
119/// fn do_stuff<A: Array>() { .. }
120///
121/// fn do_stuff_dispatch(array_impl: &ArrayImpl) {
122/// dispatch_array_variants!(array_impl, [A = Array], {
123/// do_stuff::<A>()
124/// })
125/// }
126/// ```
127///
128/// There're more to bind, including type aliases of associated `ArrayBuilder`, `Scalar`, and
129/// `ScalarRef`, or even the constant string of the variant name `VARIANT_NAME`. This can be
130/// achieved by writing one or more of them in the square brackets. Due to the limitation of macro,
131/// the order of the bindings matters.
132///
133/// ```ignore
134/// fn do_stuff_dispatch(array_impl: &ArrayImpl) {
135/// dispatch_array_variants!(
136/// array_impl,
137/// [A = Array, B = ArrayBuilder, S = Scalar, R = ScalarRef, N = VARIANT_NAME],
138/// { .. }
139/// )
140/// }
141/// ```
142///
143/// Alias bindings can also be used along with the inner value accessing:
144///
145/// ```ignore
146/// fn do_stuff<A: Array>(array: &A) { .. }
147///
148/// fn do_stuff_dispatch(array_impl: &ArrayImpl) {
149/// dispatch_array_variants!(array_impl, array, [A = Array], {
150/// do_stuff::<A>(array)
151/// })
152/// }
153/// ```
154#[macro_export(local_inner_macros)]
155macro_rules! dispatch_array_variants {
156 ($impl:expr, [$($k:ident = $v:ident),*], $body:tt) => {
157 dispatch_array_variants!($impl, _, [$($k = $v),*], $body)
158 };
159 ($impl:expr, $inner:pat, $body:tt) => {
160 dispatch_array_variants!($impl, $inner, [], $body)
161 };
162 // Switch the order of alias bindings to avoid ambiguousness.
163 ($impl:expr, $inner:pat, [$($k:ident = $v:ident),*], $body:tt) => {{
164 use $crate::array::ArrayImpl;
165 for_all_variants! { do_dispatch_variants, $impl, ArrayImpl, $inner, [($($v, $k,)*)], $body }
166 }};
167}
168
169/// Dispatch the code block to all variants of `ArrayBuilderImpl`.
170///
171/// Refer to [`dispatch_array_variants`] for usage.
172// TODO: avoid duplication by `macro_metavar_expr` feature
173#[macro_export(local_inner_macros)]
174macro_rules! dispatch_array_builder_variants {
175 ($impl:expr, [$($k:ident = $v:ident),*], $body:tt) => {
176 dispatch_array_builder_variants!($impl, _, [$($k = $v),*], $body)
177 };
178 ($impl:expr, $inner:pat, $body:tt) => {
179 dispatch_array_builder_variants!($impl, $inner, [], $body)
180 };
181 ($impl:expr, $inner:pat, [$($k:ident = $v:ident),*], $body:tt) => {{
182 use $crate::array::ArrayBuilderImpl;
183 for_all_variants! { do_dispatch_variants, $impl, ArrayBuilderImpl, $inner, [($($v, $k,)*)], $body }
184 }};
185}
186
187/// Dispatch the code block to all variants of `ScalarImpl`.
188///
189/// Refer to [`dispatch_array_variants`] for usage.
190// TODO: avoid duplication by `macro_metavar_expr` feature
191#[macro_export(local_inner_macros)]
192macro_rules! dispatch_scalar_variants {
193 ($impl:expr, [$($k:ident = $v:ident),*], $body:tt) => {
194 dispatch_scalar_variants!($impl, _, [$($k = $v),*], $body)
195 };
196 ($impl:expr, $inner:pat, $body:tt) => {
197 dispatch_scalar_variants!($impl, $inner, [], $body)
198 };
199 ($impl:expr, $inner:pat, [$($k:ident = $v:ident),*], $body:tt) => {{
200 use $crate::types::ScalarImpl;
201 for_all_variants! { do_dispatch_variants, $impl, ScalarImpl, $inner, [($($v, $k,)*)], $body }
202 }};
203}
204
205/// Dispatch the code block to all variants of `ScalarRefImpl`.
206///
207/// Refer to [`dispatch_array_variants`] for usage.
208// TODO: avoid duplication by `macro_metavar_expr` feature
209#[macro_export(local_inner_macros)]
210macro_rules! dispatch_scalar_ref_variants {
211 ($impl:expr, [$($k:ident = $v:ident),*], $body:tt) => {
212 dispatch_scalar_ref_variants!($impl, _, [$($k = $v),*], $body)
213 };
214 ($impl:expr, $inner:pat, $body:tt) => {
215 dispatch_scalar_ref_variants!($impl, $inner, [], $body)
216 };
217 ($impl:expr, $inner:pat, [$($k:ident = $v:ident),*], $body:tt) => {{
218 use $crate::types::ScalarRefImpl;
219 for_all_variants! { do_dispatch_variants, $impl, ScalarRefImpl, $inner, [($($v, $k,)*)], $body }
220 }};
221}
222
223/// Helper macro for generating dispatching code. Internally used by `dispatch_data_types` macros.
224#[macro_export(local_inner_macros)]
225macro_rules! do_dispatch_data_types {
226 ($impl:expr, [$alias:tt], $body:tt, $( { $data_type:ident, $variant_name:ident, $suffix_name:ident, $scalar:ty, $scalar_ref:ty, $array:ty, $builder:ty } ),*) => {
227 match $impl {
228 $( $crate::types::DataType::$data_type { .. } => {
229 do_expand_alias!($array, $variant_name, $alias);
230 #[allow(unused_braces)]
231 $body
232 }, )*
233 }
234 };
235}
236
237/// Dispatch the code block to all variants of `DataType`.
238///
239/// There's no inner value to access, so only alias bindings are supported. Refer to
240/// [`dispatch_array_variants`] for usage.
241#[macro_export(local_inner_macros)]
242macro_rules! dispatch_data_types {
243 ($impl:expr, [$($k:ident = $v:ident),*], $body:tt) => {
244 for_all_variants! { do_dispatch_data_types, $impl, [($($v, $k,)*)], $body }
245 };
246}