datafusion_functions/string/
to_hex.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18use std::any::Any;
19use std::fmt::Write;
20use std::sync::Arc;
21
22use crate::utils::make_scalar_function;
23use arrow::array::{ArrayRef, GenericStringBuilder};
24use arrow::datatypes::DataType::{
25    Int16, Int32, Int64, Int8, UInt16, UInt32, UInt64, UInt8, Utf8,
26};
27use arrow::datatypes::{
28    ArrowNativeType, ArrowPrimitiveType, DataType, Int16Type, Int32Type, Int64Type,
29    Int8Type, UInt16Type, UInt32Type, UInt64Type, UInt8Type,
30};
31use datafusion_common::cast::as_primitive_array;
32use datafusion_common::Result;
33use datafusion_common::{exec_err, plan_err};
34
35use datafusion_expr::{ColumnarValue, Documentation};
36use datafusion_expr::{ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility};
37use datafusion_expr_common::signature::TypeSignature::Exact;
38use datafusion_macros::user_doc;
39
40/// Converts the number to its equivalent hexadecimal representation.
41/// to_hex(2147483647) = '7fffffff'
42pub fn to_hex<T: ArrowPrimitiveType>(args: &[ArrayRef]) -> Result<ArrayRef>
43where
44    T::Native: std::fmt::LowerHex,
45{
46    let integer_array = as_primitive_array::<T>(&args[0])?;
47
48    let mut result = GenericStringBuilder::<i32>::with_capacity(
49        integer_array.len(),
50        // * 8 to convert to bits, / 4 bits per hex char
51        integer_array.len() * (T::Native::get_byte_width() * 8 / 4),
52    );
53
54    for integer in integer_array {
55        if let Some(value) = integer {
56            if let Some(value_usize) = value.to_usize() {
57                write!(result, "{value_usize:x}")?;
58            } else if let Some(value_isize) = value.to_isize() {
59                write!(result, "{value_isize:x}")?;
60            } else {
61                return exec_err!(
62                    "Unsupported data type {integer:?} for function to_hex"
63                );
64            }
65            result.append_value("");
66        } else {
67            result.append_null();
68        }
69    }
70
71    let result = result.finish();
72
73    Ok(Arc::new(result) as ArrayRef)
74}
75
76#[user_doc(
77    doc_section(label = "String Functions"),
78    description = "Converts an integer to a hexadecimal string.",
79    syntax_example = "to_hex(int)",
80    sql_example = r#"```sql
81> select to_hex(12345689);
82+-------------------------+
83| to_hex(Int64(12345689)) |
84+-------------------------+
85| bc6159                  |
86+-------------------------+
87```"#,
88    standard_argument(name = "int", prefix = "Integer")
89)]
90#[derive(Debug)]
91pub struct ToHexFunc {
92    signature: Signature,
93}
94
95impl Default for ToHexFunc {
96    fn default() -> Self {
97        Self::new()
98    }
99}
100
101impl ToHexFunc {
102    pub fn new() -> Self {
103        Self {
104            signature: Signature::one_of(
105                vec![
106                    Exact(vec![Int8]),
107                    Exact(vec![Int16]),
108                    Exact(vec![Int32]),
109                    Exact(vec![Int64]),
110                    Exact(vec![UInt8]),
111                    Exact(vec![UInt16]),
112                    Exact(vec![UInt32]),
113                    Exact(vec![UInt64]),
114                ],
115                Volatility::Immutable,
116            ),
117        }
118    }
119}
120
121impl ScalarUDFImpl for ToHexFunc {
122    fn as_any(&self) -> &dyn Any {
123        self
124    }
125
126    fn name(&self) -> &str {
127        "to_hex"
128    }
129
130    fn signature(&self) -> &Signature {
131        &self.signature
132    }
133
134    fn return_type(&self, arg_types: &[DataType]) -> Result<DataType> {
135        Ok(match arg_types[0] {
136            Int8 | Int16 | Int32 | Int64 | UInt8 | UInt16 | UInt32 | UInt64 => Utf8,
137            _ => {
138                return plan_err!("The to_hex function can only accept integers.");
139            }
140        })
141    }
142
143    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
144        match args.args[0].data_type() {
145            Int64 => make_scalar_function(to_hex::<Int64Type>, vec![])(&args.args),
146            UInt64 => make_scalar_function(to_hex::<UInt64Type>, vec![])(&args.args),
147            Int32 => make_scalar_function(to_hex::<Int32Type>, vec![])(&args.args),
148            UInt32 => make_scalar_function(to_hex::<UInt32Type>, vec![])(&args.args),
149            Int16 => make_scalar_function(to_hex::<Int16Type>, vec![])(&args.args),
150            UInt16 => make_scalar_function(to_hex::<UInt16Type>, vec![])(&args.args),
151            Int8 => make_scalar_function(to_hex::<Int8Type>, vec![])(&args.args),
152            UInt8 => make_scalar_function(to_hex::<UInt8Type>, vec![])(&args.args),
153            other => exec_err!("Unsupported data type {other:?} for function to_hex"),
154        }
155    }
156
157    fn documentation(&self) -> Option<&Documentation> {
158        self.doc()
159    }
160}
161
162#[cfg(test)]
163mod tests {
164    use arrow::array::{
165        Int16Array, Int32Array, Int64Array, Int8Array, StringArray, UInt16Array,
166        UInt32Array, UInt64Array, UInt8Array,
167    };
168    use datafusion_common::cast::as_string_array;
169
170    use super::*;
171
172    macro_rules! test_to_hex_type {
173        // Default test with standard input/output
174        ($name:ident, $arrow_type:ty, $array_type:ty) => {
175            test_to_hex_type!(
176                $name,
177                $arrow_type,
178                $array_type,
179                vec![Some(100), Some(0), None],
180                vec![Some("64"), Some("0"), None]
181            );
182        };
183
184        // Custom test with custom input/output (eg: positive number)
185        ($name:ident, $arrow_type:ty, $array_type:ty, $input:expr, $expected:expr) => {
186            #[test]
187            fn $name() -> Result<()> {
188                let input = $input;
189                let expected = $expected;
190
191                let array = <$array_type>::from(input);
192                let array_ref = Arc::new(array);
193                let hex_result = to_hex::<$arrow_type>(&[array_ref])?;
194                let hex_array = as_string_array(&hex_result)?;
195                let expected_array = StringArray::from(expected);
196
197                assert_eq!(&expected_array, hex_array);
198                Ok(())
199            }
200        };
201    }
202
203    test_to_hex_type!(
204        to_hex_int8,
205        Int8Type,
206        Int8Array,
207        vec![Some(100), Some(0), None, Some(-1)],
208        vec![Some("64"), Some("0"), None, Some("ffffffffffffffff")]
209    );
210    test_to_hex_type!(
211        to_hex_int16,
212        Int16Type,
213        Int16Array,
214        vec![Some(100), Some(0), None, Some(-1)],
215        vec![Some("64"), Some("0"), None, Some("ffffffffffffffff")]
216    );
217    test_to_hex_type!(
218        to_hex_int32,
219        Int32Type,
220        Int32Array,
221        vec![Some(100), Some(0), None, Some(-1)],
222        vec![Some("64"), Some("0"), None, Some("ffffffffffffffff")]
223    );
224    test_to_hex_type!(
225        to_hex_int64,
226        Int64Type,
227        Int64Array,
228        vec![Some(100), Some(0), None, Some(-1)],
229        vec![Some("64"), Some("0"), None, Some("ffffffffffffffff")]
230    );
231
232    test_to_hex_type!(to_hex_uint8, UInt8Type, UInt8Array);
233    test_to_hex_type!(to_hex_uint16, UInt16Type, UInt16Array);
234    test_to_hex_type!(to_hex_uint32, UInt32Type, UInt32Array);
235    test_to_hex_type!(to_hex_uint64, UInt64Type, UInt64Array);
236
237    test_to_hex_type!(
238        to_hex_large_signed,
239        Int64Type,
240        Int64Array,
241        vec![Some(i64::MAX), Some(i64::MIN)],
242        vec![Some("7fffffffffffffff"), Some("8000000000000000")]
243    );
244
245    test_to_hex_type!(
246        to_hex_large_unsigned,
247        UInt64Type,
248        UInt64Array,
249        vec![Some(u64::MAX), Some(u64::MIN)],
250        vec![Some("ffffffffffffffff"), Some("0")]
251    );
252}
datafusion_functions/string/to_hex.rs

datafusion_functions/string/
to_hex.rs
