vortex-array 0.84.0

Vortex in memory columnar data format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright the Vortex contributors

use vortex_buffer::ByteBuffer;
use vortex_error::VortexResult;
use vortex_error::vortex_ensure_eq;
use vortex_error::vortex_err;

use crate::array::Array;
use crate::array::ArrayView;
use crate::array::VTable;
use crate::validity::Validity;

/// Type-specific access needed by shared fixed-width structural compute.
///
/// The shared `take` and `filter` kernels view an implementing array as `array.len()` records of
/// [`byte_width`] bytes each, which lets them move whole records without knowing the logical
/// type.
///
/// [`byte_width`]: FixedWidthArray::byte_width
pub(crate) trait FixedWidthArray: VTable {
    /// Returns the number of bytes each record occupies.
    fn byte_width(array: ArrayView<'_, Self>) -> usize;

    /// Returns the records of `array` as a single host-resident byte buffer.
    ///
    /// The returned buffer must contain exactly `array.len() * byte_width` bytes.
    fn values(array: ArrayView<'_, Self>) -> ByteBuffer;

    /// Rebuilds an array of this encoding from a records buffer, preserving the logical type of
    /// `array`.
    ///
    /// Callers must provide a `values` buffer of exactly `len * byte_width` bytes and a
    /// `validity` with logical length `len`. The shared kernels enforce the buffer length through
    /// the module-level `with_values` helper rather than in each implementation.
    fn with_values(
        array: ArrayView<'_, Self>,
        values: ByteBuffer,
        len: usize,
        validity: Validity,
    ) -> VortexResult<Array<Self>>;
}

/// Rebuilds a fixed-width array from `len` records in `values`, validating the buffer length
/// before dispatching to [`FixedWidthArray::with_values`].
pub(crate) fn with_values<V: FixedWidthArray>(
    array: ArrayView<'_, V>,
    values: ByteBuffer,
    len: usize,
    validity: Validity,
) -> VortexResult<Array<V>> {
    let expected_len = len
        .checked_mul(V::byte_width(array))
        .ok_or_else(|| vortex_err!("Fixed-width values buffer length overflows usize"))?;
    vortex_ensure_eq!(
        values.len(),
        expected_len,
        "Fixed-width values buffer length {} does not match expected length {expected_len}",
        values.len(),
    );
    V::with_values(array, values, len, validity)
}