risingwave_common/types/
to_text.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
15use std::fmt::{Result, Write};
16use std::num::FpCategory;
17
18use super::{DataType, DatumRef, ScalarRefImpl};
19use crate::dispatch_scalar_ref_variants;
20
21/// Converts `ScalarRef` to pgwire "TEXT" format.
22///
23/// ## Relationship with casting to varchar
24///
25/// For most types, this is also the implementation for casting to varchar, but there are exceptions.
26/// e.g., The TEXT format for boolean is `t` / `f` while they cast to varchar `true` / `false`.
27/// - <https://github.com/postgres/postgres/blob/REL_16_3/src/include/catalog/pg_cast.dat#L438-L439>
28/// - <https://www.postgresql.org/docs/16/sql-createcast.html#:~:text=A%20small%20number%20of%20the%20built%2Din%20types%20do%20indeed%20have%20different%20behaviors%20for%20conversions%2C%20mostly%20because%20of%20requirements%20of%20the%20SQL%20standard>
29///
30/// ## Relationship with `ToString`/`Display`
31///
32/// For some types, the implementation diverge from Rust's standard `ToString`/`Display`,
33/// to match PostgreSQL's representation.
34///
35/// ---
36///
37/// FIXME: `ToText` should depend on a lot of other stuff
38/// but we have not implemented them yet: timezone, date style, interval style, bytea output, etc
39pub trait ToText {
40    /// Write the text to the writer *regardless* of its data type
41    ///
42    /// See `ToText::to_text` for more details.
43    fn write<W: Write>(&self, f: &mut W) -> Result;
44
45    /// Write the text to the writer according to its data type
46    fn write_with_type<W: Write>(&self, _ty: &DataType, f: &mut W) -> Result;
47
48    /// Convert to text according to its data type
49    fn to_text_with_type(&self, ty: &DataType) -> String {
50        let mut s = String::new();
51        self.write_with_type(ty, &mut s).unwrap();
52        s
53    }
54
55    /// `to_text` is a special version of `to_text_with_type`, it convert the scalar to default type
56    /// text. E.g. for Int64, it will convert to text as a Int64 type.
57    /// We should prefer to use `to_text_with_type` because it's more clear and readable.
58    ///
59    /// Note: currently the `DataType` param is actually unnecessary.
60    /// Previously, Timestamptz is also represented as int64, and we need the data type to distinguish them.
61    /// Now we have 1-1 mapping, and it happens to be the case that PostgreSQL default `ToText` format does
62    /// not need additional metadata like field names contained in `DataType`.
63    fn to_text(&self) -> String {
64        let mut s = String::new();
65        self.write(&mut s).unwrap();
66        s
67    }
68}
69
70macro_rules! implement_using_to_string {
71    ($({ $scalar_type:ty , $data_type:ident} ),*) => {
72        $(
73            impl ToText for $scalar_type {
74                fn write<W: Write>(&self, f: &mut W) -> Result {
75                    write!(f, "{self}")
76                }
77                fn write_with_type<W: Write>(&self, ty: &DataType, f: &mut W) -> Result {
78                    match ty {
79                        DataType::$data_type => self.write(f),
80                        _ => unreachable!(),
81                    }
82                }
83            }
84        )*
85    };
86}
87
88macro_rules! implement_using_itoa {
89    ($({ $scalar_type:ty , $data_type:ident} ),*) => {
90        $(
91            impl ToText for $scalar_type {
92                fn write<W: Write>(&self, f: &mut W) -> Result {
93                    write!(f, "{}", itoa::Buffer::new().format(*self))
94                }
95                fn write_with_type<W: Write>(&self, ty: &DataType, f: &mut W) -> Result {
96                    match ty {
97                        DataType::$data_type => self.write(f),
98                        _ => unreachable!(),
99                    }
100                }
101            }
102        )*
103    };
104}
105
106implement_using_to_string! {
107    { String ,Varchar },
108    { &str ,Varchar}
109}
110
111implement_using_itoa! {
112    { i16, Int16 },
113    { i32, Int32 },
114    { i64, Int64 }
115}
116
117macro_rules! implement_using_ryu {
118    ($({ $scalar_type:ty, $data_type:ident } ),*) => {
119            $(
120            impl ToText for $scalar_type {
121                fn write<W: Write>(&self, f: &mut W) -> Result {
122                    let inner = self.0;
123                    match inner.classify() {
124                        FpCategory::Infinite if inner.is_sign_negative() => write!(f, "-Infinity"),
125                        FpCategory::Infinite => write!(f, "Infinity"),
126                        FpCategory::Zero if inner.is_sign_negative() => write!(f, "-0"),
127                        FpCategory::Nan => write!(f, "NaN"),
128                        _ => {
129                            let mut buf = ryu::Buffer::new();
130                            let mut s = buf.format_finite(self.0);
131                            if let Some(trimmed) = s.strip_suffix(".0") {
132                                s = trimmed;
133                            }
134                            if let Some(mut idx) = s.as_bytes().iter().position(|x| *x == b'e') {
135                                idx += 1;
136                                write!(f, "{}", &s[..idx])?;
137                                if s.as_bytes()[idx] == b'-' {
138                                    write!(f, "-")?;
139                                    idx += 1;
140                                } else {
141                                    write!(f, "+")?;
142                                }
143                                if idx + 1 == s.len() {
144                                    write!(f, "0")?;
145                                }
146                                write!(f, "{}", &s[idx..])?;
147                            } else {
148                                write!(f, "{}", s)?;
149                            }
150                            Ok(())
151                        }
152                    }
153                }
154                fn write_with_type<W: Write>(&self, ty: &DataType, f: &mut W) -> Result {
155                    match ty {
156                        DataType::$data_type => self.write(f),
157                        _ => unreachable!(),
158                    }
159                }
160            }
161        )*
162    };
163}
164
165implement_using_ryu! {
166    { crate::types::F32, Float32 },
167    { crate::types::F64, Float64 }
168}
169
170impl ToText for bool {
171    fn write<W: Write>(&self, f: &mut W) -> Result {
172        if *self {
173            write!(f, "t")
174        } else {
175            write!(f, "f")
176        }
177    }
178
179    fn write_with_type<W: Write>(&self, ty: &DataType, f: &mut W) -> Result {
180        match ty {
181            DataType::Boolean => self.write(f),
182            _ => unreachable!(),
183        }
184    }
185}
186
187impl ToText for &[u8] {
188    fn write<W: Write>(&self, f: &mut W) -> Result {
189        write!(f, "\\x{}", hex::encode(self))
190    }
191
192    fn write_with_type<W: Write>(&self, ty: &DataType, f: &mut W) -> Result {
193        match ty {
194            DataType::Bytea => self.write(f),
195            _ => unreachable!(),
196        }
197    }
198}
199
200impl ToText for ScalarRefImpl<'_> {
201    fn write<W: Write>(&self, f: &mut W) -> Result {
202        dispatch_scalar_ref_variants!(self, v, { v.write(f) })
203    }
204
205    fn write_with_type<W: Write>(&self, ty: &DataType, f: &mut W) -> Result {
206        dispatch_scalar_ref_variants!(self, v, { v.write_with_type(ty, f) })
207    }
208}
209
210impl ToText for DatumRef<'_> {
211    fn write<W: Write>(&self, f: &mut W) -> Result {
212        match self {
213            Some(data) => data.write(f),
214            None => write!(f, "NULL"),
215        }
216    }
217
218    fn write_with_type<W: Write>(&self, ty: &DataType, f: &mut W) -> Result {
219        match self {
220            Some(data) => data.write_with_type(ty, f),
221            None => write!(f, "NULL"),
222        }
223    }
224}
225
226#[cfg(test)]
227mod tests {
228    use crate::types::ToText;
229    use crate::types::ordered_float::OrderedFloat;
230
231    #[test]
232    fn test_float_to_text() {
233        // f64 -> text.
234        let ret: OrderedFloat<f64> = OrderedFloat::<f64>::from(1.234567890123456);
235        tracing::info!("ret: {}", ret.to_text());
236        assert_eq!("1.234567890123456".to_owned(), ret.to_text());
237
238        // f32 -> text.
239        let ret: OrderedFloat<f32> = OrderedFloat::<f32>::from(1.234567);
240        assert_eq!("1.234567".to_owned(), ret.to_text());
241    }
242}
risingwave_common/types/to_text.rs

risingwave_common/types/
to_text.rs
