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    /// Creates a new null builder with space for `capacity` elements without re-allocating
63    #[deprecated = "there is no actual notion of capacity in the NullBuilder, so emulating it makes little sense"]
64    pub fn with_capacity(_capacity: usize) -> Self {
65        Self::new()
66    }
67
68    /// Returns the capacity of this builder measured in slots of type `T`
69    #[deprecated = "there is no actual notion of capacity in the NullBuilder, so emulating it makes little sense"]
70    pub fn capacity(&self) -> usize {
71        self.len
72    }
73
74    /// Appends a null slot into the builder
75    #[inline]
76    pub fn append_null(&mut self) {
77        self.len += 1;
78    }
79
80    /// Appends `n` `null`s into the builder.
81    #[inline]
82    pub fn append_nulls(&mut self, n: usize) {
83        self.len += n;
84    }
85
86    /// Appends a null slot into the builder
87    #[inline]
88    pub fn append_empty_value(&mut self) {
89        self.append_null();
90    }
91
92    /// Appends `n` `null`s into the builder.
93    #[inline]
94    pub fn append_empty_values(&mut self, n: usize) {
95        self.append_nulls(n);
96    }
97
98    /// Builds the [NullArray] and reset this builder.
99    pub fn finish(&mut self) -> NullArray {
100        let len = self.len();
101        let builder = ArrayData::new_null(&DataType::Null, len).into_builder();
102
103        let array_data = unsafe { builder.build_unchecked() };
104        NullArray::from(array_data)
105    }
106
107    /// Builds the [NullArray] without resetting the builder.
108    pub fn finish_cloned(&self) -> NullArray {
109        let len = self.len();
110        let builder = ArrayData::new_null(&DataType::Null, len).into_builder();
111
112        let array_data = unsafe { builder.build_unchecked() };
113        NullArray::from(array_data)
114    }
115}
116
117impl ArrayBuilder for NullBuilder {
118    /// Returns the builder as a non-mutable `Any` reference.
119    fn as_any(&self) -> &dyn Any {
120        self
121    }
122
123    /// Returns the builder as a mutable `Any` reference.
124    fn as_any_mut(&mut self) -> &mut dyn Any {
125        self
126    }
127
128    /// Returns the boxed builder as a box of `Any`.
129    fn into_box_any(self: Box<Self>) -> Box<dyn Any> {
130        self
131    }
132
133    /// Returns the number of array slots in the builder
134    fn len(&self) -> usize {
135        self.len
136    }
137
138    /// Builds the array and reset this builder.
139    fn finish(&mut self) -> ArrayRef {
140        Arc::new(self.finish())
141    }
142
143    /// Builds the array without resetting the builder.
144    fn finish_cloned(&self) -> ArrayRef {
145        Arc::new(self.finish_cloned())
146    }
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152    use crate::Array;
153
154    #[test]
155    fn test_null_array_builder() {
156        let mut builder = NullArray::builder(10);
157        builder.append_null();
158        builder.append_nulls(4);
159        builder.append_empty_value();
160        builder.append_empty_values(4);
161
162        let arr = builder.finish();
163        assert_eq!(10, arr.len());
164        assert_eq!(0, arr.offset());
165        assert_eq!(0, arr.null_count());
166        assert!(arr.is_nullable());
167    }
168
169    #[test]
170    fn test_null_array_builder_finish_cloned() {
171        let mut builder = NullArray::builder(16);
172        builder.append_null();
173        builder.append_empty_value();
174        builder.append_empty_values(3);
175        let mut array = builder.finish_cloned();
176        assert_eq!(5, array.len());
177
178        builder.append_empty_values(5);
179        array = builder.finish();
180        assert_eq!(10, array.len());
181    }
182}
arrow_array/builder/null_builder.rs

arrow_array/builder/
null_builder.rs
