This is an automated email from the ASF dual-hosted git repository.
tustvold 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 cc18d0ff29 Minor: improve the documentation of NullBuffer and
BooleanBuffer (#6974)
cc18d0ff29 is described below
commit cc18d0ff29ae278510c2f6c4f4fd4b2c42582b69
Author: Andrew Lamb <[email protected]>
AuthorDate: Wed Jan 15 03:28:19 2025 -0500
Minor: improve the documentation of NullBuffer and BooleanBuffer (#6974)
---
arrow-buffer/src/buffer/boolean.rs | 8 ++++++++
arrow-buffer/src/buffer/null.rs | 10 +++++++---
arrow-buffer/src/builder/boolean.rs | 6 ++++++
arrow-buffer/src/builder/null.rs | 8 ++++++--
4 files changed, 27 insertions(+), 5 deletions(-)
diff --git a/arrow-buffer/src/buffer/boolean.rs
b/arrow-buffer/src/buffer/boolean.rs
index aaa86832f6..c8e5144c14 100644
--- a/arrow-buffer/src/buffer/boolean.rs
+++ b/arrow-buffer/src/buffer/boolean.rs
@@ -25,6 +25,14 @@ use crate::{
use std::ops::{BitAnd, BitOr, BitXor, Not};
/// A slice-able [`Buffer`] containing bit-packed booleans
+///
+/// `BooleanBuffer`s can be creating using [`BooleanBufferBuilder`]
+///
+/// # See Also
+///
+/// * [`NullBuffer`] for representing null values in Arrow arrays
+///
+/// [`NullBuffer`]: crate::NullBuffer
#[derive(Debug, Clone, Eq)]
pub struct BooleanBuffer {
buffer: Buffer,
diff --git a/arrow-buffer/src/buffer/null.rs b/arrow-buffer/src/buffer/null.rs
index ec12b885eb..a178b3101b 100644
--- a/arrow-buffer/src/buffer/null.rs
+++ b/arrow-buffer/src/buffer/null.rs
@@ -19,13 +19,16 @@ use crate::bit_iterator::{BitIndexIterator, BitIterator,
BitSliceIterator};
use crate::buffer::BooleanBuffer;
use crate::{Buffer, MutableBuffer};
-/// A [`BooleanBuffer`] used to encode validity for arrow arrays
+/// A [`BooleanBuffer`] used to encode validity for Arrow arrays
///
-/// As per the [Arrow specification], array validity is encoded in a packed
bitmask with a
+/// In the [Arrow specification], array validity is encoded in a packed
bitmask with a
/// `true` value indicating the corresponding slot is not null, and `false`
indicating
/// that it is null.
///
+/// `NullBuffer`s can be creating using [`NullBufferBuilder`]
+///
/// [Arrow specification]:
https://arrow.apache.org/docs/format/Columnar.html#validity-bitmaps
+/// [`NullBufferBuilder`]: crate::NullBufferBuilder
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct NullBuffer {
buffer: BooleanBuffer,
@@ -49,7 +52,8 @@ impl NullBuffer {
/// Create a new [`NullBuffer`] of length `len` where all values are valid
///
- /// Note: it is more efficient to not set the null buffer if it is known
to be all valid
+ /// Note: it is more efficient to not set the null buffer if it is known to
+ /// be all valid (aka all values are not null)
pub fn new_valid(len: usize) -> Self {
Self {
buffer: BooleanBuffer::new_set(len),
diff --git a/arrow-buffer/src/builder/boolean.rs
b/arrow-buffer/src/builder/boolean.rs
index ca178ae5ce..67b306dd8c 100644
--- a/arrow-buffer/src/builder/boolean.rs
+++ b/arrow-buffer/src/builder/boolean.rs
@@ -19,6 +19,12 @@ use crate::{bit_mask, bit_util, BooleanBuffer, Buffer,
MutableBuffer};
use std::ops::Range;
/// Builder for [`BooleanBuffer`]
+///
+/// # See Also
+///
+/// * [`NullBuffer`] for building [`BooleanBuffer`]s for representing nulls
+///
+/// [`NullBuffer`]: crate::NullBuffer
#[derive(Debug)]
pub struct BooleanBufferBuilder {
buffer: MutableBuffer,
diff --git a/arrow-buffer/src/builder/null.rs b/arrow-buffer/src/builder/null.rs
index 298b479e87..ddbca46f71 100644
--- a/arrow-buffer/src/builder/null.rs
+++ b/arrow-buffer/src/builder/null.rs
@@ -17,12 +17,16 @@
use crate::{BooleanBufferBuilder, MutableBuffer, NullBuffer};
-/// Builder for creating the null bit buffer.
+/// Builder for creating [`NullBuffer`]
+///
+/// # Performance
///
/// This builder only materializes the buffer when we append `false`.
/// 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.
+///
+/// This optimization is **very** important for the performance as it avoids
+/// allocating memory for the null buffer when there are no nulls.
#[derive(Debug)]
pub struct NullBufferBuilder {
bitmap_builder: Option<BooleanBufferBuilder>,
