This is an automated email from the ASF dual-hosted git repository.
jeffreyvo 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 c245a45efe Minor: Clarify documentation on
`NullBufferBuilder::allocated_size` (#7089)
c245a45efe is described below
commit c245a45efef9d9453f121587365e56d53c39d28f
Author: Andrew Lamb <[email protected]>
AuthorDate: Sat Feb 8 20:14:10 2025 -0500
Minor: Clarify documentation on `NullBufferBuilder::allocated_size` (#7089)
* Minor: Clarify documentaiton on NullBufferBuilder::allocated_size
* add note about why allocations are 64 bytes
---
arrow-buffer/src/buffer/mutable.rs | 3 ++-
arrow-buffer/src/builder/boolean.rs | 19 ++++++++++++++++++-
arrow-buffer/src/builder/null.rs | 2 +-
3 files changed, 21 insertions(+), 3 deletions(-)
diff --git a/arrow-buffer/src/buffer/mutable.rs
b/arrow-buffer/src/buffer/mutable.rs
index 5ad55e306e..19ca0fef15 100644
--- a/arrow-buffer/src/buffer/mutable.rs
+++ b/arrow-buffer/src/buffer/mutable.rs
@@ -288,7 +288,8 @@ impl MutableBuffer {
self.len
}
- /// Returns the total capacity in this buffer.
+ /// Returns the total capacity in this buffer, in bytes.
+ ///
/// The invariant `buffer.len() <= buffer.capacity()` is always upheld.
#[inline]
pub const fn capacity(&self) -> usize {
diff --git a/arrow-buffer/src/builder/boolean.rs
b/arrow-buffer/src/builder/boolean.rs
index da8fb06430..bdcc3a55db 100644
--- a/arrow-buffer/src/builder/boolean.rs
+++ b/arrow-buffer/src/builder/boolean.rs
@@ -83,7 +83,24 @@ impl BooleanBufferBuilder {
self.len == 0
}
- /// Returns the capacity of the buffer
+ /// Returns the capacity of the buffer, in bits (not bytes)
+ ///
+ /// Note this
+ ///
+ /// # Example
+ /// ```
+ /// # use arrow_buffer::builder::BooleanBufferBuilder;
+ /// // empty requires 0 bytes
+ /// let b = BooleanBufferBuilder::new(0);
+ /// assert_eq!(0, b.capacity());
+ /// // Creating space for 1 bit results in 64 bytes (space for 512 bits)
+ /// // (64 is the minimum allocation size for 64 bit architectures)
+ /// let mut b = BooleanBufferBuilder::new(1);
+ /// assert_eq!(512, b.capacity());
+ /// // 1000 bits requires 128 bytes (space for 1024 bits)
+ /// b.append_n(1000, true);
+ /// assert_eq!(1024, b.capacity());
+ /// ```
#[inline]
pub fn capacity(&self) -> usize {
self.buffer.capacity() * 8
diff --git a/arrow-buffer/src/builder/null.rs b/arrow-buffer/src/builder/null.rs
index fdd2bb4dfc..607daf7ddb 100644
--- a/arrow-buffer/src/builder/null.rs
+++ b/arrow-buffer/src/builder/null.rs
@@ -217,7 +217,7 @@ impl NullBufferBuilder {
self.bitmap_builder.as_mut().map(|b| b.as_slice_mut())
}
- /// Return the allocated size of this builder, in bytes, useful for memory
accounting.
+ /// Return the allocated size of this builder, in bits, useful for memory
accounting.
pub fn allocated_size(&self) -> usize {
self.bitmap_builder
.as_ref()
