Skip to main content

arrow_array/builder/
fixed_size_binary_builder.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 crate::array::Array;
6use crate::builder::ArrayBuilder;
7use crate::{ArrayRef, FixedSizeBinaryArray};
8use arrow_buffer::Buffer;
9use arrow_buffer::NullBufferBuilder;
10use arrow_data::ArrayData;
11use arrow_schema::{ArrowError, DataType};
12use std::any::Any;
13use std::sync::Arc;
14
15/// Builder for [`FixedSizeBinaryArray`]
16/// ```
17/// # use arrow_array::builder::FixedSizeBinaryBuilder;
18/// # use arrow_array::Array;
19/// #
20/// let mut builder = FixedSizeBinaryBuilder::with_capacity(3, 5);
21/// // [b"hello", null, b"arrow"]
22/// builder.append_value(b"hello").unwrap();
23/// builder.append_null();
24/// builder.append_value(b"arrow").unwrap();
25///
26/// let array = builder.finish();
27/// assert_eq!(array.value(0), b"hello");
28/// assert!(array.is_null(1));
29/// assert_eq!(array.value(2), b"arrow");
30/// ```
31#[derive(Debug)]
32pub struct FixedSizeBinaryBuilder {
33    values_builder: Vec<u8>,
34    null_buffer_builder: NullBufferBuilder,
35    value_length: i32,
36}
37
38impl FixedSizeBinaryBuilder {
39    /// Creates a new [`FixedSizeBinaryBuilder`]
40    pub fn new(byte_width: i32) -> Self {
41        Self::with_capacity(1024, byte_width)
42    }
43
44    /// Creates a new [`FixedSizeBinaryBuilder`], `capacity` is the number of byte slices
45    /// that can be appended without reallocating
46    ///
47    /// # Panics
48    ///
49    /// Panics if `byte_width < 0`
50    pub fn with_capacity(capacity: usize, byte_width: i32) -> Self {
51        assert!(
52            byte_width >= 0,
53            "value length ({byte_width}) of the array must >= 0"
54        );
55        Self {
56            values_builder: Vec::with_capacity(capacity * byte_width as usize),
57            null_buffer_builder: NullBufferBuilder::new(capacity),
58            value_length: byte_width,
59        }
60    }
61
62    /// Appends a byte slice into the builder.
63    ///
64    /// Automatically update the null buffer to delimit the slice appended in as a
65    /// distinct value element.
66    #[inline]
67    pub fn append_value(&mut self, value: impl AsRef<[u8]>) -> Result<(), ArrowError> {
68        if self.value_length != value.as_ref().len() as i32 {
69            Err(ArrowError::InvalidArgumentError(
70                "Byte slice does not have the same length as FixedSizeBinaryBuilder value lengths"
71                    .to_string(),
72            ))
73        } else {
74            self.values_builder.extend_from_slice(value.as_ref());
75            self.null_buffer_builder.append_non_null();
76            Ok(())
77        }
78    }
79
80    /// Append a null value to the array.
81    #[inline]
82    pub fn append_null(&mut self) {
83        self.values_builder
84            .extend(std::iter::repeat_n(0u8, self.value_length as usize));
85        self.null_buffer_builder.append_null();
86    }
87
88    /// Appends `n` `null`s into the builder.
89    #[inline]
90    pub fn append_nulls(&mut self, n: usize) {
91        self.values_builder
92            .extend(std::iter::repeat_n(0u8, self.value_length as usize * n));
93        self.null_buffer_builder.append_n_nulls(n);
94    }
95
96    /// Appends all elements in array into the builder.
97    pub fn append_array(&mut self, array: &FixedSizeBinaryArray) -> Result<(), ArrowError> {
98        if self.value_length != array.value_length() {
99            return Err(ArrowError::InvalidArgumentError(
100                "Cannot append FixedSizeBinaryArray with different value length".to_string(),
101            ));
102        }
103        let buffer = array.value_data();
104        self.values_builder.extend_from_slice(buffer);
105        if let Some(validity) = array.nulls() {
106            self.null_buffer_builder.append_buffer(validity);
107        } else {
108            self.null_buffer_builder.append_n_non_nulls(array.len());
109        }
110        Ok(())
111    }
112
113    /// Returns the current values buffer as a slice
114    pub fn values_slice(&self) -> &[u8] {
115        self.values_builder.as_slice()
116    }
117
118    /// Builds the [`FixedSizeBinaryArray`] and reset this builder.
119    pub fn finish(&mut self) -> FixedSizeBinaryArray {
120        let array_length = self.len();
121        let array_data_builder = ArrayData::builder(DataType::FixedSizeBinary(self.value_length))
122            .add_buffer(std::mem::take(&mut self.values_builder).into())
123            .nulls(self.null_buffer_builder.finish())
124            .len(array_length);
125        // SAFETY: value_length >= 0, values.len() == len * value_length, and nulls.len() == len — all guaranteed by the builder
126        let array_data = unsafe { array_data_builder.build_unchecked() };
127        FixedSizeBinaryArray::from(array_data)
128    }
129
130    /// Builds the [`FixedSizeBinaryArray`] without resetting the builder.
131    pub fn finish_cloned(&self) -> FixedSizeBinaryArray {
132        let array_length = self.len();
133        let values_buffer = Buffer::from_slice_ref(self.values_builder.as_slice());
134        let array_data_builder = ArrayData::builder(DataType::FixedSizeBinary(self.value_length))
135            .add_buffer(values_buffer)
136            .nulls(self.null_buffer_builder.finish_cloned())
137            .len(array_length);
138        // SAFETY: value_length >= 0, values.len() == len * value_length, and nulls.len() == len — all guaranteed by the builder
139        let array_data = unsafe { array_data_builder.build_unchecked() };
140        FixedSizeBinaryArray::from(array_data)
141    }
142
143    /// Returns the current null buffer as a slice
144    pub fn validity_slice(&self) -> Option<&[u8]> {
145        self.null_buffer_builder.as_slice()
146    }
147    ///  Returns the total memory capacity in bytes currently
148    pub fn capacity(&self) -> usize {
149        self.values_builder.capacity() + self.null_buffer_builder.allocated_size() + 4 // i32 
150    }
151}
152
153impl ArrayBuilder for FixedSizeBinaryBuilder {
154    /// Returns the builder as a non-mutable `Any` reference.
155    fn as_any(&self) -> &dyn Any {
156        self
157    }
158
159    /// Returns the builder as a mutable `Any` reference.
160    fn as_any_mut(&mut self) -> &mut dyn Any {
161        self
162    }
163
164    /// Returns the boxed builder as a box of `Any`.
165    fn into_box_any(self: Box<Self>) -> Box<dyn Any> {
166        self
167    }
168
169    /// Returns the number of array slots in the builder
170    fn len(&self) -> usize {
171        self.null_buffer_builder.len()
172    }
173
174    /// Builds the array and reset this builder.
175    fn finish(&mut self) -> ArrayRef {
176        Arc::new(self.finish())
177    }
178
179    /// Builds the array without resetting the builder.
180    fn finish_cloned(&self) -> ArrayRef {
181        Arc::new(self.finish_cloned())
182    }
183}
184
185#[cfg(test)]
186mod tests {
187    use super::*;
188
189    use crate::Array;
190
191    #[test]
192    fn test_fixed_size_binary_builder() {
193        let mut builder = FixedSizeBinaryBuilder::with_capacity(3, 5);
194
195        //  [b"hello", null, "arrow", null, null, "world"]
196        builder.append_value(b"hello").unwrap();
197        builder.append_null();
198        builder.append_value(b"arrow").unwrap();
199        builder.append_nulls(2);
200        builder.append_value(b"world").unwrap();
201        let array = builder.finish();
202
203        assert_eq!(&DataType::FixedSizeBinary(5), array.data_type());
204        assert_eq!(6, array.len());
205        assert_eq!(3, array.null_count());
206        assert_eq!(5, array.value_length());
207        assert_eq!(b"arrow", array.value(2));
208        assert!(array.is_null(3));
209        assert!(array.is_null(4));
210        assert_eq!(b"world", array.value(5));
211    }
212
213    #[test]
214    fn test_fixed_size_binary_builder_finish_cloned() {
215        let mut builder = FixedSizeBinaryBuilder::with_capacity(3, 5);
216
217        //  [b"hello", null, "arrow"]
218        builder.append_value(b"hello").unwrap();
219        builder.append_null();
220        builder.append_value(b"arrow").unwrap();
221        let mut array = builder.finish_cloned();
222
223        assert_eq!(&DataType::FixedSizeBinary(5), array.data_type());
224        assert_eq!(3, array.len());
225        assert_eq!(1, array.null_count());
226        assert_eq!(5, array.value_length());
227        assert_eq!(b"arrow", array.value(2));
228
229        //  [b"finis", null, "clone"]
230        builder.append_value(b"finis").unwrap();
231        builder.append_null();
232        builder.append_value(b"clone").unwrap();
233
234        array = builder.finish();
235
236        assert_eq!(&DataType::FixedSizeBinary(5), array.data_type());
237        assert_eq!(6, array.len());
238        assert_eq!(2, array.null_count());
239        assert_eq!(5, array.value_length());
240        assert_eq!(b"clone", array.value(5));
241    }
242
243    #[test]
244    fn test_fixed_size_binary_builder_with_zero_value_length() {
245        let mut builder = FixedSizeBinaryBuilder::new(0);
246
247        builder.append_value(b"").unwrap();
248        builder.append_null();
249        builder.append_value(b"").unwrap();
250        assert!(!builder.is_empty());
251
252        let array = builder.finish();
253        assert_eq!(&DataType::FixedSizeBinary(0), array.data_type());
254        assert_eq!(3, array.len());
255        assert_eq!(1, array.null_count());
256        assert_eq!(0, array.value_length());
257        assert_eq!(b"", array.value(0));
258        assert_eq!(b"", array.value(2));
259    }
260
261    #[test]
262    #[should_panic(
263        expected = "Byte slice does not have the same length as FixedSizeBinaryBuilder value lengths"
264    )]
265    fn test_fixed_size_binary_builder_with_inconsistent_value_length() {
266        let mut builder = FixedSizeBinaryBuilder::with_capacity(1, 4);
267        builder.append_value(b"hello").unwrap();
268    }
269    #[test]
270    fn test_fixed_size_binary_builder_empty() {
271        let mut builder = FixedSizeBinaryBuilder::new(5);
272        assert!(builder.is_empty());
273
274        let fixed_size_binary_array = builder.finish();
275        assert_eq!(
276            &DataType::FixedSizeBinary(5),
277            fixed_size_binary_array.data_type()
278        );
279        assert_eq!(0, fixed_size_binary_array.len());
280    }
281
282    #[test]
283    #[should_panic(expected = "value length (-1) of the array must >= 0")]
284    fn test_fixed_size_binary_builder_invalid_value_length() {
285        let _ = FixedSizeBinaryBuilder::with_capacity(15, -1);
286    }
287
288    #[test]
289    fn test_fixed_size_binary_builder_append_array() {
290        let mut other_builder = FixedSizeBinaryBuilder::with_capacity(3, 5);
291        other_builder.append_value(b"hello").unwrap();
292        other_builder.append_null();
293        other_builder.append_value(b"arrow").unwrap();
294        let other_array = other_builder.finish();
295
296        let mut builder = FixedSizeBinaryBuilder::with_capacity(6, 5);
297        builder.append_array(&other_array).unwrap();
298        // Append again to test if breaks when appending multiple times
299        builder.append_array(&other_array).unwrap();
300        let array = builder.finish();
301
302        assert_eq!(array.value_length(), other_array.value_length());
303        assert_eq!(&DataType::FixedSizeBinary(5), array.data_type());
304        assert_eq!(6, array.len());
305        assert_eq!(2, array.null_count());
306        assert_eq!(b"hello", array.value(0));
307        assert!(array.is_null(1));
308        assert_eq!(b"arrow", array.value(2));
309
310        assert_eq!(b"hello", array.value(3));
311        assert!(array.is_null(4));
312        assert_eq!(b"arrow", array.value(5));
313    }
314
315    #[test]
316    #[should_panic(expected = "Cannot append FixedSizeBinaryArray with different value length")]
317    fn test_fixed_size_binary_builder_append_array_invalid_value_length() {
318        let mut other_builder = FixedSizeBinaryBuilder::with_capacity(3, 4);
319        other_builder.append_value(b"test").unwrap();
320        let other_array = other_builder.finish();
321        let mut builder = FixedSizeBinaryBuilder::with_capacity(3, 5);
322        builder.append_array(&other_array).unwrap();
323    }
324}