From 56a4c026452aefcbab72c1ece16d402ebe1f46c3 Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Mon, 13 Jan 2025 15:45:24 -0500
Subject: [PATCH] Export NullBufferBuilder along with BooleanBufferBuilder

---
 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 29d75024ea72..e859f3794ad4 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 298b479e87df..6c5fee8043d6 100644
--- a/arrow-buffer/src/builder/null.rs
+++ b/arrow-buffer/src/builder/null.rs
@@ -23,6 +23,23 @@ use crate::{BooleanBufferBuilder, MutableBuffer, NullBuffer};
 /// If you only append `true`s to the builder, what you get will be
 /// `None` when calling [`finish`](#method.finish).
 /// This optimization is **very** important for the performance.
+///
+/// # 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>,