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 = self.len();
89        let builder = ArrayData::new_null(&DataType::Null, len).into_builder();
90
91        let array_data = unsafe { builder.build_unchecked() };
92        NullArray::from(array_data)
93    }
94
95    /// Builds the [NullArray] without resetting the builder.
96    pub fn finish_cloned(&self) -> NullArray {
97        let len = self.len();
98        let builder = ArrayData::new_null(&DataType::Null, len).into_builder();
99
100        let array_data = unsafe { builder.build_unchecked() };
101        NullArray::from(array_data)
102    }
103}
104
105impl ArrayBuilder for NullBuilder {
106    /// Returns the builder as a non-mutable `Any` reference.
107    fn as_any(&self) -> &dyn Any {
108        self
109    }
110
111    /// Returns the builder as a mutable `Any` reference.
112    fn as_any_mut(&mut self) -> &mut dyn Any {
113        self
114    }
115
116    /// Returns the boxed builder as a box of `Any`.
117    fn into_box_any(self: Box<Self>) -> Box<dyn Any> {
118        self
119    }
120
121    /// Returns the number of array slots in the builder
122    fn len(&self) -> usize {
123        self.len
124    }
125
126    /// Builds the array and reset this builder.
127    fn finish(&mut self) -> ArrayRef {
128        Arc::new(self.finish())
129    }
130
131    /// Builds the array without resetting the builder.
132    fn finish_cloned(&self) -> ArrayRef {
133        Arc::new(self.finish_cloned())
134    }
135}
136
137#[cfg(test)]
138mod tests {
139    use super::*;
140    use crate::Array;
141
142    #[test]
143    fn test_null_array_builder() {
144        let mut builder = NullArray::builder(10);
145        builder.append_null();
146        builder.append_nulls(4);
147        builder.append_empty_value();
148        builder.append_empty_values(4);
149
150        let arr = builder.finish();
151        assert_eq!(10, arr.len());
152        assert_eq!(0, arr.offset());
153        assert_eq!(0, arr.null_count());
154        assert!(arr.is_nullable());
155    }
156
157    #[test]
158    fn test_null_array_builder_finish_cloned() {
159        let mut builder = NullArray::builder(16);
160        builder.append_null();
161        builder.append_empty_value();
162        builder.append_empty_values(3);
163        let mut array = builder.finish_cloned();
164        assert_eq!(5, array.len());
165
166        builder.append_empty_values(5);
167        array = builder.finish();
168        assert_eq!(10, array.len());
169    }
170}
arrow_array/builder/null_builder.rs

arrow_array/builder/
null_builder.rs
