arrow_array/builder/
null_builder.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 crate::builder::ArrayBuilder;
19use crate::{ArrayRef, NullArray};
20use arrow_data::ArrayData;
21use arrow_schema::DataType;
22use std::any::Any;
23use std::sync::Arc;
24
25/// Builder for [`NullArray`]
26///
27/// # Example
28///
29/// Create a `NullArray` from a `NullBuilder`
30///
31/// ```
32///
33/// # use arrow_array::{Array, NullArray, builder::NullBuilder};
34///
35/// let mut b = NullBuilder::new();
36/// b.append_empty_value();
37/// b.append_null();
38/// b.append_nulls(3);
39/// b.append_empty_values(3);
40/// let arr = b.finish();
41///
42/// assert_eq!(8, arr.len());
43/// assert_eq!(0, arr.null_count());
44/// ```
45#[derive(Debug)]
46pub struct NullBuilder {
47    len: usize,
48}
49
50impl Default for NullBuilder {
51    fn default() -> Self {
52        Self::new()
53    }
54}
55
56impl NullBuilder {
57    /// Creates a new null builder
58    pub fn new() -> Self {
59        Self { len: 0 }
60    }
61
62    /// Appends a null slot into the builder
63    #[inline]
64    pub fn append_null(&mut self) {
65        self.len += 1;
66    }
67
68    /// Appends `n` `null`s into the builder.
69    #[inline]
70    pub fn append_nulls(&mut self, n: usize) {
71        self.len += n;
72    }
73
74    /// Appends a null slot into the builder
75    #[inline]
76    pub fn append_empty_value(&mut self) {
77        self.append_null();
78    }
79
80    /// Appends `n` `null`s into the builder.
81    #[inline]
82    pub fn append_empty_values(&mut self, n: usize) {
83        self.append_nulls(n);
84    }
85
86    /// Builds the [NullArray] and reset this builder.
87    pub fn finish(&mut self) -> NullArray {
88        let len = std::mem::take(&mut self.len);
89        let builder = ArrayData::new_null(&DataType::Null, len).into_builder();
90
91        // SAFETY: ArrayData::new_null produces valid null array data, so all builder invariants hold
92        let array_data = unsafe { builder.build_unchecked() };
93        NullArray::from(array_data)
94    }
95
96    /// Builds the [NullArray] without resetting the builder.
97    pub fn finish_cloned(&self) -> NullArray {
98        let len = self.len();
99        let builder = ArrayData::new_null(&DataType::Null, len).into_builder();
100
101        // SAFETY: ArrayData::new_null produces valid null array data, so all builder invariants hold
102        let array_data = unsafe { builder.build_unchecked() };
103        NullArray::from(array_data)
104    }
105}
106
107impl ArrayBuilder for NullBuilder {
108    /// Returns the builder as a non-mutable `Any` reference.
109    fn as_any(&self) -> &dyn Any {
110        self
111    }
112
113    /// Returns the builder as a mutable `Any` reference.
114    fn as_any_mut(&mut self) -> &mut dyn Any {
115        self
116    }
117
118    /// Returns the boxed builder as a box of `Any`.
119    fn into_box_any(self: Box<Self>) -> Box<dyn Any> {
120        self
121    }
122
123    /// Returns the number of array slots in the builder
124    fn len(&self) -> usize {
125        self.len
126    }
127
128    /// Builds the array and reset this builder.
129    fn finish(&mut self) -> ArrayRef {
130        Arc::new(self.finish())
131    }
132
133    /// Builds the array without resetting the builder.
134    fn finish_cloned(&self) -> ArrayRef {
135        Arc::new(self.finish_cloned())
136    }
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142    use crate::Array;
143
144    #[test]
145    fn test_null_array_builder() {
146        let mut builder = NullArray::builder(10);
147        builder.append_null();
148        builder.append_nulls(4);
149        builder.append_empty_value();
150        builder.append_empty_values(4);
151
152        let arr = builder.finish();
153        assert_eq!(10, arr.len());
154        assert_eq!(0, arr.offset());
155        assert_eq!(0, arr.null_count());
156        assert!(arr.is_nullable());
157    }
158
159    #[test]
160    fn test_null_array_builder_finish_cloned() {
161        let mut builder = NullArray::builder(16);
162        builder.append_null();
163        builder.append_empty_value();
164        builder.append_empty_values(3);
165        let mut array = builder.finish_cloned();
166        assert_eq!(5, array.len());
167
168        builder.append_empty_values(5);
169        array = builder.finish();
170        assert_eq!(10, array.len());
171    }
172
173    #[test]
174    fn test_null_array_builder_finish_resets() {
175        let mut builder = NullBuilder::new();
176        builder.append_nulls(10);
177
178        let array = builder.finish();
179        assert_eq!(10, array.len());
180        assert_eq!(0, builder.len());
181        assert!(builder.is_empty());
182
183        builder.append_nulls(3);
184        let array = builder.finish();
185        assert_eq!(3, array.len());
186        assert_eq!(0, builder.len());
187    }
188}
arrow_array/builder/null_builder.rs

arrow_array/builder/
null_builder.rs
