This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 4b38ff5132 Export NullBufferBuilder along with BooleanBufferBuilder
(#6976)
4b38ff5132 is described below
commit 4b38ff5132161d5543e70644dced4561ff79da11
Author: Andrew Lamb <[email protected]>
AuthorDate: Tue Jan 21 06:24:57 2025 -0500
Export NullBufferBuilder along with BooleanBufferBuilder (#6976)
---
arrow-array/src/builder/mod.rs | 16 ++++++++++++++++
arrow-buffer/src/builder/null.rs | 17 +++++++++++++++++
2 files changed, 33 insertions(+)
diff --git a/arrow-array/src/builder/mod.rs b/arrow-array/src/builder/mod.rs
index 29d75024ea..e859f3794a 100644
--- a/arrow-array/src/builder/mod.rs
+++ b/arrow-array/src/builder/mod.rs
@@ -216,8 +216,24 @@
//! RecordBatch::from(&builder.finish())
//! }
//! ```
+//!
+//! # Null / Validity Masks
+//!
+//! The [`NullBufferBuilder`] is optimized for creating the null mask for an
array.
+//!
+//! ```
+//! # use arrow_array::builder::NullBufferBuilder;
+//! let mut builder = NullBufferBuilder::new(8);
+//! let mut builder = NullBufferBuilder::new(8);
+//! builder.append_n_non_nulls(7);
+//! builder.append_null();
+//! let buffer = builder.finish().unwrap();
+//! assert_eq!(buffer.len(), 8);
+//! assert_eq!(buffer.iter().collect::<Vec<_>>(), vec![true, true, true, true,
true, true, true, false]);
+//! ```
pub use arrow_buffer::BooleanBufferBuilder;
+pub use arrow_buffer::NullBufferBuilder;
mod boolean_builder;
pub use boolean_builder::*;
diff --git a/arrow-buffer/src/builder/null.rs b/arrow-buffer/src/builder/null.rs
index ddbca46f71..0ad62eacf4 100644
--- a/arrow-buffer/src/builder/null.rs
+++ b/arrow-buffer/src/builder/null.rs
@@ -27,6 +27,23 @@ use crate::{BooleanBufferBuilder, MutableBuffer, NullBuffer};
///
/// This optimization is **very** important for the performance as it avoids
/// allocating memory for the null buffer when there are no nulls.
+///
+/// # Example
+/// ```
+/// # use arrow_buffer::NullBufferBuilder;
+/// let mut builder = NullBufferBuilder::new(8);
+/// builder.append_n_non_nulls(8);
+/// // If no non null values are appended, the null buffer is not created
+/// let buffer = builder.finish();
+/// assert!(buffer.is_none());
+/// // however, if a null value is appended, the null buffer is created
+/// let mut builder = NullBufferBuilder::new(8);
+/// builder.append_n_non_nulls(7);
+/// builder.append_null();
+/// let buffer = builder.finish().unwrap();
+/// assert_eq!(buffer.len(), 8);
+/// assert_eq!(buffer.iter().collect::<Vec<_>>(), vec![true, true, true, true,
true, true, true, false]);
+/// ```
#[derive(Debug)]
pub struct NullBufferBuilder {
bitmap_builder: Option<BooleanBufferBuilder>,
