This is an automated email from the ASF dual-hosted git repository.
mbrobbel 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 f9dd799f7b Update docs for zero copy conversion of ScalarBuffer (#8772)
f9dd799f7b is described below
commit f9dd799f7baf9731ee01027c10cf6b64c94a793f
Author: Andrew Lamb <[email protected]>
AuthorDate: Tue Nov 4 03:13:17 2025 -0500
Update docs for zero copy conversion of ScalarBuffer (#8772)
# Which issue does this PR close?
- Similar to https://github.com/apache/arrow-rs/pull/8771
# Rationale for this change
As people write more arrow kernels, let's make it easier to understand
how to go back/forth to Vec without copying
# What changes are included in this PR?
Add some additional information and examples about converting
ScalarBuffer back/forth to Vec
# Are these changes tested?
Yes by CI
# Are there any user-facing changes?
Docs only. No functional change
---
arrow-buffer/src/buffer/scalar.rs | 23 ++++++++++++++++++++++-
1 file changed, 22 insertions(+), 1 deletion(-)
diff --git a/arrow-buffer/src/buffer/scalar.rs
b/arrow-buffer/src/buffer/scalar.rs
index c058fbdce9..3c5334ca51 100644
--- a/arrow-buffer/src/buffer/scalar.rs
+++ b/arrow-buffer/src/buffer/scalar.rs
@@ -29,17 +29,38 @@ use std::ops::Deref;
/// with the following differences:
///
/// - slicing and cloning is O(1).
-/// - it supports external allocated memory
+/// - support for external allocated memory (e.g. via FFI).
///
+/// See [`Buffer`] for more low-level memory management details.
+///
+/// # Example: Convert to/from Vec (without copies)
+///
+/// (See [`Buffer::from_vec`] and [`Buffer::into_vec`] for a lower level API)
/// ```
/// # use arrow_buffer::ScalarBuffer;
/// // Zero-copy conversion from Vec
/// let buffer = ScalarBuffer::from(vec![1, 2, 3]);
/// assert_eq!(&buffer, &[1, 2, 3]);
+/// // convert the buffer back to Vec without copy assuming:
+/// // 1. the inner buffer is not sliced
+/// // 2. the inner buffer uses standard allocation
+/// // 3. there are no other references to the inner buffer
+/// let vec: Vec<i32> = buffer.into();
+/// assert_eq!(&vec, &[1, 2, 3]);
+/// ```
///
+/// # Example: Zero copy slicing
+/// ```
+/// # use arrow_buffer::ScalarBuffer;
+/// let buffer = ScalarBuffer::from(vec![1, 2, 3]);
+/// assert_eq!(&buffer, &[1, 2, 3]);
/// // Zero-copy slicing
/// let sliced = buffer.slice(1, 2);
/// assert_eq!(&sliced, &[2, 3]);
+/// // Original buffer is unchanged
+/// assert_eq!(&buffer, &[1, 2, 3]);
+/// // converting the sliced buffer back to Vec incurs a copy
+/// let vec: Vec<i32> = sliced.into();
/// ```
#[derive(Clone, Default)]
pub struct ScalarBuffer<T: ArrowNativeType> {
