arrow_data/transform/
utils.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 arrow_buffer::{ArrowNativeType, MutableBuffer, bit_util};
19use arrow_schema::ArrowError;
20use num_integer::Integer;
21use num_traits::CheckedAdd;
22
23/// extends the `buffer` to be able to hold `len` bits, setting all bits of the new size to zero.
24#[inline]
25pub(super) fn resize_for_bits(buffer: &mut MutableBuffer, len: usize) {
26    let needed_bytes = bit_util::ceil(len, 8);
27    if buffer.len() < needed_bytes {
28        buffer.resize(needed_bytes, 0);
29    }
30}
31
32/// Extends `buffer` with the re-based offsets from `offsets`, returning an error on overflow.
33pub(super) fn try_extend_offsets<T: ArrowNativeType + Integer + CheckedAdd>(
34    buffer: &mut MutableBuffer,
35    mut last_offset: T,
36    offsets: &[T],
37) -> Result<(), ArrowError> {
38    buffer
39        .try_reserve(std::mem::size_of_val(offsets))
40        .map_err(|e| ArrowError::MemoryError(e.to_string()))?;
41    // Snapshot the length so we can roll back partial writes on overflow.
42    let original_len = buffer.len();
43    for window in offsets.windows(2) {
44        let length = window[1] - window[0];
45        match last_offset.checked_add(&length) {
46            Some(new_offset) => {
47                last_offset = new_offset;
48                buffer.push(last_offset);
49            }
50            None => {
51                // Restore the buffer to its state before this call so the
52                // caller is not left with a partially-written offset sequence.
53                buffer.resize(original_len, 0);
54                return Err(ArrowError::InvalidArgumentError(
55                    "offset overflow: data exceeds the capacity of the offset type. \
56                     Try splitting into smaller batches or using a larger type \
57                     (e.g. LargeStringArray / LargeBinaryArray instead of StringArray / BinaryArray)"
58                        .to_string(),
59                ));
60            }
61        }
62    }
63    Ok(())
64}
65
66#[inline]
67pub(super) unsafe fn get_last_offset<T: ArrowNativeType>(offset_buffer: &MutableBuffer) -> T {
68    // JUSTIFICATION
69    //  Benefit
70    //      20% performance improvement extend of variable sized arrays (see bench `mutable_array`)
71    //  Soundness
72    //      * offset buffer is always extended in slices of T and aligned accordingly.
73    //      * Buffer[0] is initialized with one element, 0, and thus `mutable_offsets.len() - 1` is always valid.
74    let (prefix, offsets, suffix) = unsafe { offset_buffer.as_slice().align_to::<T>() };
75    debug_assert!(prefix.is_empty() && suffix.is_empty());
76    *unsafe { offsets.get_unchecked(offsets.len() - 1) }
77}
78
79#[cfg(test)]
80mod tests {
81    use crate::transform::utils::try_extend_offsets;
82    use arrow_buffer::MutableBuffer;
83
84    #[test]
85    fn test_overflow_returns_error() {
86        let mut buffer = MutableBuffer::new(10);
87        let err = try_extend_offsets(&mut buffer, i32::MAX - 4, &[0i32, 5]).unwrap_err();
88        assert!(
89            err.to_string().contains("offset overflow"),
90            "unexpected error: {err}"
91        );
92    }
93
94    #[test]
95    fn test_overflow_restores_buffer() {
96        // Pre-populate the buffer with a known-good offset so we can verify
97        // it is unchanged after a failed extend.
98        let mut buffer = MutableBuffer::new(16);
99        buffer.push(0i32);
100        buffer.push(10i32);
101        let len_before = buffer.len();
102
103        // Offsets [0, 3, i32::MAX]: the second window (3 → i32::MAX) will overflow
104        // because last_offset (i32::MAX - 4 + 3 = i32::MAX - 1) + (i32::MAX - 3) overflows.
105        // Use a simpler case: start near MAX so the very first window overflows.
106        let err = try_extend_offsets(&mut buffer, i32::MAX - 2, &[0i32, 5]).unwrap_err();
107        assert!(
108            err.to_string().contains("offset overflow"),
109            "unexpected error: {err}"
110        );
111        // Buffer must be exactly as it was before the failed call.
112        assert_eq!(
113            buffer.len(),
114            len_before,
115            "buffer length changed after overflow rollback"
116        );
117    }
118}
arrow_data/transform/utils.rs

arrow_data/transform/
utils.rs
