Skip to main content

arrow_buffer/builder/
offset.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
5use std::ops::Deref;
6
7use crate::{ArrowNativeType, OffsetBuffer, OverflowError};
8
9/// Builder of [`OffsetBuffer`]
10#[derive(Debug)]
11pub struct OffsetBufferBuilder<O: ArrowNativeType> {
12    offsets: Vec<O>,
13    last_offset: usize,
14}
15
16impl<O: ArrowNativeType> OffsetBufferBuilder<O> {
17    /// Create a new builder with space for `capacity + 1` offsets
18    pub fn new(capacity: usize) -> Self {
19        let mut offsets = Vec::with_capacity(capacity + 1);
20        offsets.push(O::usize_as(0));
21        Self {
22            offsets,
23            last_offset: 0,
24        }
25    }
26
27    /// Push a slice of `length` bytes
28    ///
29    /// # Panics
30    ///
31    /// Panics if adding `length` would overflow `usize`.
32    /// Use [`Self::try_push_length`] for a fallible version.
33    #[inline]
34    pub fn push_length(&mut self, length: usize) {
35        self.try_push_length(length)
36            .unwrap_or_else(|err| panic!("{err}"))
37    }
38
39    /// Push a slice of `length` bytes
40    ///
41    /// # Errors
42    ///
43    /// Errors if adding `length` would overflow `usize`. The builder is left unchanged.
44    #[inline]
45    pub fn try_push_length(&mut self, length: usize) -> Result<(), OverflowError> {
46        self.last_offset = self
47            .last_offset
48            .checked_add(length)
49            .ok_or_else(|| OverflowError::new::<usize>("total length"))?;
50        self.offsets.push(O::usize_as(self.last_offset));
51        Ok(())
52    }
53
54    /// Reserve space for at least `additional` further offsets
55    #[inline]
56    pub fn reserve(&mut self, additional: usize) {
57        self.offsets.reserve(additional);
58    }
59
60    /// Takes the builder itself and returns an [`OffsetBuffer`]
61    ///
62    /// # Panics
63    ///
64    /// Panics if offsets overflow `O`. Use [`Self::try_finish`] for a fallible version.
65    pub fn finish(self) -> OffsetBuffer<O> {
66        self.try_finish().unwrap_or_else(|err| panic!("{err}"))
67    }
68
69    /// Takes the builder itself and returns an [`OffsetBuffer`]
70    ///
71    /// # Errors
72    ///
73    /// Errors if offsets overflow `O`, e.g. if they add up to more than `i32::MAX`
74    /// for a `OffsetBufferBuilder<i32>`.
75    pub fn try_finish(self) -> Result<OffsetBuffer<O>, OverflowError> {
76        O::from_usize(self.last_offset)
77            .ok_or_else(|| OverflowError::new::<O>("offset").with_value(self.last_offset))?;
78        Ok(unsafe { OffsetBuffer::new_unchecked(self.offsets.into()) })
79    }
80
81    /// Builds the [OffsetBuffer] without resetting the builder.
82    ///
83    /// # Panics
84    ///
85    /// Panics if offsets overflow `O`. Use [`Self::try_finish_cloned`] for a fallible version.
86    pub fn finish_cloned(&self) -> OffsetBuffer<O> {
87        self.try_finish_cloned()
88            .unwrap_or_else(|err| panic!("{err}"))
89    }
90
91    /// Builds the [OffsetBuffer] without resetting the builder.
92    ///
93    /// # Errors
94    ///
95    /// Errors for the same reasons as [`Self::try_finish`].
96    pub fn try_finish_cloned(&self) -> Result<OffsetBuffer<O>, OverflowError> {
97        let cloned = Self {
98            offsets: self.offsets.clone(),
99            last_offset: self.last_offset,
100        };
101        cloned.try_finish()
102    }
103}
104
105impl<O: ArrowNativeType> Deref for OffsetBufferBuilder<O> {
106    type Target = [O];
107
108    fn deref(&self) -> &Self::Target {
109        self.offsets.as_ref()
110    }
111}
112
113#[cfg(test)]
114mod tests {
115
116    #[test]
117    fn try_finish_overflow() {
118        let mut builder = OffsetBufferBuilder::<i32>::new(2);
119        builder.try_push_length(u32::MAX as usize).unwrap();
120        let expected = "offset overflow: 4294967295 does not fit in i32";
121        assert_eq!(
122            builder.try_finish_cloned().unwrap_err().to_string(),
123            expected
124        );
125        assert_eq!(builder.try_finish().unwrap_err().to_string(), expected);
126
127        let mut builder = OffsetBufferBuilder::<i32>::new(2);
128        builder.try_push_length(usize::MAX).unwrap();
129        // The builder is unchanged by a failed push:
130        assert_eq!(
131            builder.try_push_length(1).unwrap_err().to_string(),
132            "total length overflow: does not fit in usize"
133        );
134        assert_eq!(builder.len(), 2);
135    }
136    use crate::OffsetBufferBuilder;
137
138    #[test]
139    fn test_basic() {
140        let mut builder = OffsetBufferBuilder::<i32>::new(5);
141        assert_eq!(builder.len(), 1);
142        assert_eq!(&*builder, &[0]);
143        let finished = builder.finish_cloned();
144        assert_eq!(finished.len(), 1);
145        assert_eq!(&*finished, &[0]);
146
147        builder.push_length(2);
148        builder.push_length(6);
149        builder.push_length(0);
150        builder.push_length(13);
151
152        let finished = builder.finish();
153        assert_eq!(&*finished, &[0, 2, 8, 8, 21]);
154    }
155
156    #[test]
157    #[should_panic(expected = "overflow")]
158    fn test_usize_overflow() {
159        let mut builder = OffsetBufferBuilder::<i32>::new(5);
160        builder.push_length(1);
161        builder.push_length(usize::MAX);
162        builder.finish();
163    }
164
165    #[test]
166    #[should_panic(expected = "overflow")]
167    fn test_i32_overflow() {
168        let mut builder = OffsetBufferBuilder::<i32>::new(5);
169        builder.push_length(1);
170        builder.push_length(i32::MAX as usize);
171        builder.finish();
172    }
173}