arrow_array/builder/
fixed_size_binary_builder.rs1use 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#[derive(Debug)]
32pub struct FixedSizeBinaryBuilder {
33 values_builder: Vec<u8>,
34 null_buffer_builder: NullBufferBuilder,
35 value_length: i32,
36}
37
38impl FixedSizeBinaryBuilder {
39 pub fn new(byte_width: i32) -> Self {
41 Self::with_capacity(1024, byte_width)
42 }
43
44 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 #[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 #[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 #[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 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 pub fn values_slice(&self) -> &[u8] {
115 self.values_builder.as_slice()
116 }
117
118 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 let array_data = unsafe { array_data_builder.build_unchecked() };
127 FixedSizeBinaryArray::from(array_data)
128 }
129
130 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 let array_data = unsafe { array_data_builder.build_unchecked() };
140 FixedSizeBinaryArray::from(array_data)
141 }
142
143 pub fn validity_slice(&self) -> Option<&[u8]> {
145 self.null_buffer_builder.as_slice()
146 }
147 pub fn capacity(&self) -> usize {
149 self.values_builder.capacity() + self.null_buffer_builder.allocated_size() + 4 }
151}
152
153impl ArrayBuilder for FixedSizeBinaryBuilder {
154 fn as_any(&self) -> &dyn Any {
156 self
157 }
158
159 fn as_any_mut(&mut self) -> &mut dyn Any {
161 self
162 }
163
164 fn into_box_any(self: Box<Self>) -> Box<dyn Any> {
166 self
167 }
168
169 fn len(&self) -> usize {
171 self.null_buffer_builder.len()
172 }
173
174 fn finish(&mut self) -> ArrayRef {
176 Arc::new(self.finish())
177 }
178
179 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 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 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 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 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}