datafusion_functions_nested/
reverse.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
18//! [`ScalarUDFImpl`] definitions for array_reverse function.
19
20use crate::utils::make_scalar_function;
21use arrow::array::{
22    Array, ArrayRef, Capacities, GenericListArray, MutableArrayData, OffsetSizeTrait,
23};
24use arrow::buffer::OffsetBuffer;
25use arrow::datatypes::DataType::{LargeList, List, Null};
26use arrow::datatypes::{DataType, FieldRef};
27use datafusion_common::cast::{as_large_list_array, as_list_array};
28use datafusion_common::{exec_err, utils::take_function_args, Result};
29use datafusion_expr::{
30    ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
31};
32use datafusion_macros::user_doc;
33use std::any::Any;
34use std::sync::Arc;
35
36make_udf_expr_and_func!(
37    ArrayReverse,
38    array_reverse,
39    array,
40    "reverses the order of elements in the array.",
41    array_reverse_udf
42);
43
44#[user_doc(
45    doc_section(label = "Array Functions"),
46    description = "Returns the array with the order of the elements reversed.",
47    syntax_example = "array_reverse(array)",
48    sql_example = r#"```sql
49> select array_reverse([1, 2, 3, 4]);
50+------------------------------------------------------------+
51| array_reverse(List([1, 2, 3, 4]))                          |
52+------------------------------------------------------------+
53| [4, 3, 2, 1]                                               |
54+------------------------------------------------------------+
55```"#,
56    argument(
57        name = "array",
58        description = "Array expression. Can be a constant, column, or function, and any combination of array operators."
59    )
60)]
61#[derive(Debug)]
62pub struct ArrayReverse {
63    signature: Signature,
64    aliases: Vec<String>,
65}
66
67impl Default for ArrayReverse {
68    fn default() -> Self {
69        Self::new()
70    }
71}
72
73impl ArrayReverse {
74    pub fn new() -> Self {
75        Self {
76            signature: Signature::any(1, Volatility::Immutable),
77            aliases: vec!["list_reverse".to_string()],
78        }
79    }
80}
81
82impl ScalarUDFImpl for ArrayReverse {
83    fn as_any(&self) -> &dyn Any {
84        self
85    }
86
87    fn name(&self) -> &str {
88        "array_reverse"
89    }
90
91    fn signature(&self) -> &Signature {
92        &self.signature
93    }
94
95    fn return_type(&self, arg_types: &[DataType]) -> Result<DataType> {
96        Ok(arg_types[0].clone())
97    }
98
99    fn invoke_with_args(
100        &self,
101        args: datafusion_expr::ScalarFunctionArgs,
102    ) -> Result<ColumnarValue> {
103        make_scalar_function(array_reverse_inner)(&args.args)
104    }
105
106    fn aliases(&self) -> &[String] {
107        &self.aliases
108    }
109
110    fn documentation(&self) -> Option<&Documentation> {
111        self.doc()
112    }
113}
114
115/// array_reverse SQL function
116pub fn array_reverse_inner(arg: &[ArrayRef]) -> Result<ArrayRef> {
117    let [input_array] = take_function_args("array_reverse", arg)?;
118
119    match &input_array.data_type() {
120        List(field) => {
121            let array = as_list_array(input_array)?;
122            general_array_reverse::<i32>(array, field)
123        }
124        LargeList(field) => {
125            let array = as_large_list_array(input_array)?;
126            general_array_reverse::<i64>(array, field)
127        }
128        Null => Ok(Arc::clone(input_array)),
129        array_type => exec_err!("array_reverse does not support type '{array_type:?}'."),
130    }
131}
132
133fn general_array_reverse<O: OffsetSizeTrait + TryFrom<i64>>(
134    array: &GenericListArray<O>,
135    field: &FieldRef,
136) -> Result<ArrayRef> {
137    let values = array.values();
138    let original_data = values.to_data();
139    let capacity = Capacities::Array(original_data.len());
140    let mut offsets = vec![O::usize_as(0)];
141    let mut nulls = vec![];
142    let mut mutable =
143        MutableArrayData::with_capacities(vec![&original_data], false, capacity);
144
145    for (row_index, offset_window) in array.offsets().windows(2).enumerate() {
146        // skip the null value
147        if array.is_null(row_index) {
148            nulls.push(false);
149            offsets.push(offsets[row_index] + O::one());
150            mutable.extend(0, 0, 1);
151            continue;
152        } else {
153            nulls.push(true);
154        }
155
156        let start = offset_window[0];
157        let end = offset_window[1];
158
159        let mut index = end - O::one();
160        let mut cnt = 0;
161
162        while index >= start {
163            mutable.extend(0, index.to_usize().unwrap(), index.to_usize().unwrap() + 1);
164            index = index - O::one();
165            cnt += 1;
166        }
167        offsets.push(offsets[row_index] + O::usize_as(cnt));
168    }
169
170    let data = mutable.freeze();
171    Ok(Arc::new(GenericListArray::<O>::try_new(
172        Arc::clone(field),
173        OffsetBuffer::<O>::new(offsets.into()),
174        arrow::array::make_array(data),
175        Some(nulls.into()),
176    )?))
177}
datafusion_functions_nested/reverse.rs

datafusion_functions_nested/
reverse.rs
