|
| 1 | +// SPDX-License-Identifier: Apache-2.0 |
| 2 | +// SPDX-FileCopyrightText: Copyright the Vortex contributors |
| 3 | + |
| 4 | +use vortex_buffer::BitBuffer; |
| 5 | +use vortex_buffer::Buffer; |
| 6 | +use vortex_error::VortexResult; |
| 7 | + |
| 8 | +use crate::arrays::BoolArray; |
| 9 | +use crate::arrays::PrimitiveArray; |
| 10 | +use crate::arrays::StructArray; |
| 11 | +use crate::arrays::bool::BoolArrayExt as _; |
| 12 | +use crate::arrays::primitive::PrimitiveArrayExt as _; |
| 13 | +use crate::arrays::struct_::StructArrayExt as _; |
| 14 | +use crate::canonical::Canonical; |
| 15 | +use crate::executor::ExecutionCtx; |
| 16 | +use crate::match_each_native_ptype; |
| 17 | +use crate::validity::Validity; |
| 18 | +use crate::{ArrayRef, IntoArray as _}; |
| 19 | + |
| 20 | +/// Reverses a canonical array, dispatching to type-specific fast paths where possible. |
| 21 | +/// |
| 22 | +/// Fast paths: |
| 23 | +/// - `Bool`: reverses the bit buffer directly via `value_unchecked` — O(n), no extra allocation. |
| 24 | +/// - `Primitive`: reverses the element buffer directly — O(n), no extra allocation. |
| 25 | +/// - `Struct`: reverses each field lazily via [`ArrayRef::reverse`] — allows per-field |
| 26 | +/// optimisations (e.g. the `Dict` reduce rule fires on dict-encoded fields). |
| 27 | +/// |
| 28 | +/// All other canonical variants fall back to a reversed-index `take`, which is equivalent |
| 29 | +/// to the generic path but is deferred to decode time. |
| 30 | +pub(super) fn reverse_canonical( |
| 31 | + child: &ArrayRef, |
| 32 | + ctx: &mut ExecutionCtx, |
| 33 | +) -> VortexResult<ArrayRef> { |
| 34 | + let n = child.len(); |
| 35 | + if n <= 1 { |
| 36 | + return Ok(child.clone()); |
| 37 | + } |
| 38 | + |
| 39 | + let canonical = child.clone().execute::<Canonical>(ctx)?; |
| 40 | + Ok(match canonical { |
| 41 | + Canonical::Bool(a) => reverse_bool(&a)?.into_array(), |
| 42 | + Canonical::Primitive(a) => reverse_primitive(&a)?.into_array(), |
| 43 | + Canonical::Struct(a) => reverse_struct(&a)?.into_array(), |
| 44 | + // All other canonical types: reverse via take with reversed indices. |
| 45 | + _ => { |
| 46 | + let indices = PrimitiveArray::from_iter((0u64..n as u64).rev()).into_array(); |
| 47 | + child.take(indices)? |
| 48 | + } |
| 49 | + }) |
| 50 | +} |
| 51 | + |
| 52 | +/// Reverses a `BoolArray` by reading each bit in reverse order. |
| 53 | +/// |
| 54 | +/// Uses `value_unchecked` for O(n) direct bit access with no intermediate `Vec` allocation, |
| 55 | +/// and correctly handles the buffer's bit offset. |
| 56 | +fn reverse_bool(array: &BoolArray) -> VortexResult<BoolArray> { |
| 57 | + let validity = reverse_validity(array.validity()?)?; |
| 58 | + let bits = array.to_bit_buffer(); |
| 59 | + let n = bits.len(); |
| 60 | + let reversed = BitBuffer::collect_bool(n, |i| { |
| 61 | + // SAFETY: `n - 1 - i` is in `[0, n)` since `i` is in `[0, n)`. |
| 62 | + unsafe { bits.value_unchecked(n - 1 - i) } |
| 63 | + }); |
| 64 | + Ok(BoolArray::new(reversed, validity)) |
| 65 | +} |
| 66 | + |
| 67 | +/// Reverses a `PrimitiveArray` by iterating the typed buffer backwards. |
| 68 | +/// |
| 69 | +/// This is O(n × element_width) and sequential in both reads and writes, so it is |
| 70 | +/// highly cache-friendly and eligible for auto-vectorisation. |
| 71 | +fn reverse_primitive(array: &PrimitiveArray) -> VortexResult<PrimitiveArray> { |
| 72 | + let validity = reverse_validity(array.validity()?)?; |
| 73 | + match_each_native_ptype!(array.ptype(), |T| { |
| 74 | + let reversed: Vec<T> = array.as_slice::<T>().iter().rev().copied().collect(); |
| 75 | + Ok(PrimitiveArray::new(Buffer::from(reversed), validity)) |
| 76 | + }) |
| 77 | +} |
| 78 | + |
| 79 | +/// Reverses a `StructArray` by lazily reversing each child field. |
| 80 | +/// |
| 81 | +/// Each field is reversed via [`ArrayRef::reverse`], which in turn runs the optimizer. |
| 82 | +/// For dict-encoded fields this fires the `ReverseReduce for Dict` rule, so only the |
| 83 | +/// (small) codes array is reversed; the values dictionary remains untouched. |
| 84 | +fn reverse_struct(array: &StructArray) -> VortexResult<StructArray> { |
| 85 | + let validity = reverse_validity(array.struct_validity())?; |
| 86 | + let names = array.names().clone(); |
| 87 | + let n = array.len(); |
| 88 | + let reversed_fields = array |
| 89 | + .iter_unmasked_fields() |
| 90 | + .map(|field| field.reverse()) |
| 91 | + .collect::<VortexResult<Vec<ArrayRef>>>()?; |
| 92 | + StructArray::try_new(names, reversed_fields, n, validity) |
| 93 | +} |
| 94 | + |
| 95 | +/// Reverses a [`Validity`] value. |
| 96 | +/// |
| 97 | +/// `NonNullable`, `AllValid`, and `AllInvalid` are identity under reversal. |
| 98 | +/// `Array` variants are reversed lazily: `arr.reverse()` creates a |
| 99 | +/// `ReversedArray` wrapper that is further optimised at decode time. |
| 100 | +fn reverse_validity(validity: Validity) -> VortexResult<Validity> { |
| 101 | + match validity { |
| 102 | + Validity::NonNullable => Ok(Validity::NonNullable), |
| 103 | + Validity::AllValid => Ok(Validity::AllValid), |
| 104 | + Validity::AllInvalid => Ok(Validity::AllInvalid), |
| 105 | + Validity::Array(arr) => Ok(Validity::Array(arr.reverse()?)), |
| 106 | + } |
| 107 | +} |
0 commit comments