Skip to main content

arrow_select/
window.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5//! Defines windowing functions, like `shift`ing
6
7use crate::concat::concat;
8use arrow_array::{Array, ArrayRef, make_array, new_null_array};
9use arrow_schema::ArrowError;
10use num_traits::abs;
11
12/// Shifts array by defined number of items (to left or right)
13/// A positive value for `offset` shifts the array to the right
14/// a negative value shifts the array to the left.
15/// # Examples
16/// ```
17/// # use arrow_array::Int32Array;
18/// # use arrow_select::window::shift;
19/// let a: Int32Array = vec![Some(1), None, Some(4)].into();
20///
21/// // shift array 1 element to the right
22/// let res = shift(&a, 1).unwrap();
23/// let expected: Int32Array = vec![None, Some(1), None].into();
24/// assert_eq!(res.as_ref(), &expected);
25///
26/// // shift array 1 element to the left
27/// let res = shift(&a, -1).unwrap();
28/// let expected: Int32Array = vec![None, Some(4), None].into();
29/// assert_eq!(res.as_ref(), &expected);
30///
31/// // shift array 0 element, although not recommended
32/// let res = shift(&a, 0).unwrap();
33/// let expected: Int32Array = vec![Some(1), None, Some(4)].into();
34/// assert_eq!(res.as_ref(), &expected);
35///
36/// // shift array 3 element to the right
37/// let res = shift(&a, 3).unwrap();
38/// let expected: Int32Array = vec![None, None, None].into();
39/// assert_eq!(res.as_ref(), &expected);
40/// ```
41pub fn shift(array: &dyn Array, offset: i64) -> Result<ArrayRef, ArrowError> {
42    let value_len = array.len() as i64;
43    if offset == 0 {
44        Ok(make_array(array.to_data()))
45    } else if offset == i64::MIN || abs(offset) >= value_len {
46        Ok(new_null_array(array.data_type(), array.len()))
47    } else {
48        // Concatenate both arrays, add nulls after if shift > 0 else before
49        if offset > 0 {
50            let length = array.len() - offset as usize;
51            let slice = array.slice(0, length);
52
53            // Generate array with remaining `null` items
54            let null_arr = new_null_array(array.data_type(), offset as usize);
55            concat(&[null_arr.as_ref(), slice.as_ref()])
56        } else {
57            let offset = -offset as usize;
58            let length = array.len() - offset;
59            let slice = array.slice(offset, length);
60
61            // Generate array with remaining `null` items
62            let null_arr = new_null_array(array.data_type(), offset);
63            concat(&[slice.as_ref(), null_arr.as_ref()])
64        }
65    }
66}
67
68#[cfg(test)]
69mod tests {
70    use super::*;
71    use arrow_array::{Float64Array, Int32Array, Int32DictionaryArray};
72
73    #[test]
74    fn test_shift_neg() {
75        let a: Int32Array = vec![Some(1), None, Some(4)].into();
76        let res = shift(&a, -1).unwrap();
77        let expected: Int32Array = vec![None, Some(4), None].into();
78        assert_eq!(res.as_ref(), &expected);
79    }
80
81    #[test]
82    fn test_shift_pos() {
83        let a: Int32Array = vec![Some(1), None, Some(4)].into();
84        let res = shift(&a, 1).unwrap();
85        let expected: Int32Array = vec![None, Some(1), None].into();
86        assert_eq!(res.as_ref(), &expected);
87    }
88
89    #[test]
90    fn test_shift_neg_float64() {
91        let a: Float64Array = vec![Some(1.), None, Some(4.)].into();
92        let res = shift(&a, -1).unwrap();
93        let expected: Float64Array = vec![None, Some(4.), None].into();
94        assert_eq!(res.as_ref(), &expected);
95    }
96
97    #[test]
98    fn test_shift_pos_float64() {
99        let a: Float64Array = vec![Some(1.), None, Some(4.)].into();
100        let res = shift(&a, 1).unwrap();
101        let expected: Float64Array = vec![None, Some(1.), None].into();
102        assert_eq!(res.as_ref(), &expected);
103    }
104
105    #[test]
106    fn test_shift_neg_int32_dict() {
107        let a: Int32DictionaryArray = [Some("alpha"), None, Some("beta"), Some("alpha")]
108            .iter()
109            .copied()
110            .collect();
111        let res = shift(&a, -1).unwrap();
112        let expected: Int32DictionaryArray = [None, Some("beta"), Some("alpha"), None]
113            .iter()
114            .copied()
115            .collect();
116        assert_eq!(res.as_ref(), &expected);
117    }
118
119    #[test]
120    fn test_shift_pos_int32_dict() {
121        let a: Int32DictionaryArray = [Some("alpha"), None, Some("beta"), Some("alpha")]
122            .iter()
123            .copied()
124            .collect();
125        let res = shift(&a, 1).unwrap();
126        let expected: Int32DictionaryArray = [None, Some("alpha"), None, Some("beta")]
127            .iter()
128            .copied()
129            .collect();
130        assert_eq!(res.as_ref(), &expected);
131    }
132
133    #[test]
134    fn test_shift_nil() {
135        let a: Int32Array = vec![Some(1), None, Some(4)].into();
136        let res = shift(&a, 0).unwrap();
137        let expected: Int32Array = vec![Some(1), None, Some(4)].into();
138        assert_eq!(res.as_ref(), &expected);
139    }
140
141    #[test]
142    fn test_shift_boundary_pos() {
143        let a: Int32Array = vec![Some(1), None, Some(4)].into();
144        let res = shift(&a, 3).unwrap();
145        let expected: Int32Array = vec![None, None, None].into();
146        assert_eq!(res.as_ref(), &expected);
147    }
148
149    #[test]
150    fn test_shift_boundary_neg() {
151        let a: Int32Array = vec![Some(1), None, Some(4)].into();
152        let res = shift(&a, -3).unwrap();
153        let expected: Int32Array = vec![None, None, None].into();
154        assert_eq!(res.as_ref(), &expected);
155    }
156
157    #[test]
158    fn test_shift_boundary_neg_min() {
159        let a: Int32Array = vec![Some(1), None, Some(4)].into();
160        let res = shift(&a, i64::MIN).unwrap();
161        let expected: Int32Array = vec![None, None, None].into();
162        assert_eq!(res.as_ref(), &expected);
163    }
164
165    #[test]
166    fn test_shift_large_pos() {
167        let a: Int32Array = vec![Some(1), None, Some(4)].into();
168        let res = shift(&a, 1000).unwrap();
169        let expected: Int32Array = vec![None, None, None].into();
170        assert_eq!(res.as_ref(), &expected);
171    }
172
173    #[test]
174    fn test_shift_large_neg() {
175        let a: Int32Array = vec![Some(1), None, Some(4)].into();
176        let res = shift(&a, -1000).unwrap();
177        let expected: Int32Array = vec![None, None, None].into();
178        assert_eq!(res.as_ref(), &expected);
179    }
180}