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 e2ebb2303b Add example to convert `PrimitiveArray` to a `Vec` (#8771)
e2ebb2303b is described below
commit e2ebb2303b7de252ff6d39ee1733b85ccc4164c7
Author: Andrew Lamb <[email protected]>
AuthorDate: Tue Nov 4 03:11:46 2025 -0500
Add example to convert `PrimitiveArray` to a `Vec` (#8771)
# Which issue does this PR close?
- related to https://github.com/apache/datafusion/pull/18424
# Rationale for this change
It may not be obvious how to convert certain Arrow arrays to/from Vec
without copying for manipulation, so let's add an example
# What changes are included in this PR?
1. Add note about zero copy arrays
2. Add examples of modifying a primitive array using zero-copy
conversion to/from Vec
# Are these changes tested?
By CI
# Are there any user-facing changes?
Docs only, no functional change
---------
Co-authored-by: Vegard Stikbakke <[email protected]>
---
arrow-array/src/array/primitive_array.rs | 30 ++++++++++++++++++++++++++++++
arrow-buffer/src/buffer/immutable.rs | 4 ++--
2 files changed, 32 insertions(+), 2 deletions(-)
diff --git a/arrow-array/src/array/primitive_array.rs
b/arrow-array/src/array/primitive_array.rs
index a5bbd0e664..e71f4d4719 100644
--- a/arrow-array/src/array/primitive_array.rs
+++ b/arrow-array/src/array/primitive_array.rs
@@ -493,6 +493,9 @@ pub use crate::types::ArrowPrimitiveType;
///
/// # Example: From a Vec
///
+/// *Note*: Converting a `Vec` to a `PrimitiveArray` does not copy the data.
+/// The new `PrimitiveArray` uses the same underlying allocation from the
`Vec`.
+///
/// ```
/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
/// let arr: PrimitiveArray<Int32Type> = vec![1, 2, 3, 4].into();
@@ -501,6 +504,33 @@ pub use crate::types::ArrowPrimitiveType;
/// assert_eq!(arr.values(), &[1, 2, 3, 4])
/// ```
///
+/// # Example: To a `Vec<T>`
+///
+/// *Note*: In some cases, converting `PrimitiveArray` to a `Vec` is zero-copy
+/// and does not copy the data (see [`Buffer::into_vec`] for conditions). In
+/// such cases, the `Vec` will use the same underlying memory allocation from
+/// the `PrimitiveArray`.
+///
+/// The Rust compiler generates highly optimized code for operations on
+/// Vec, so using a Vec can often be faster than using a PrimitiveArray
directly.
+///
+/// ```
+/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
+/// let arr = PrimitiveArray::<Int32Type>::from(vec![1, 2, 3, 4]);
+/// let starting_ptr = arr.values().as_ptr();
+/// // split into its parts
+/// let (datatype, buffer, nulls) = arr.into_parts();
+/// // Convert the buffer to a Vec<i32> (zero copy)
+/// // (note this requires that there are no other references)
+/// let mut vec: Vec<i32> = buffer.into();
+/// vec[2] = 300;
+/// // put the parts back together
+/// let arr = PrimitiveArray::<Int32Type>::try_new(vec.into(), nulls).unwrap();
+/// assert_eq!(arr.values(), &[1, 2, 300, 4]);
+/// // The same allocation was used
+/// assert_eq!(starting_ptr, arr.values().as_ptr());
+/// ```
+///
/// # Example: From an optional Vec
///
/// ```
diff --git a/arrow-buffer/src/buffer/immutable.rs
b/arrow-buffer/src/buffer/immutable.rs
index 20eb966a8f..dafcee3d5b 100644
--- a/arrow-buffer/src/buffer/immutable.rs
+++ b/arrow-buffer/src/buffer/immutable.rs
@@ -388,8 +388,8 @@ impl Buffer {
/// # Errors
///
/// Returns `Err(self)` if
- /// 1. this buffer does not have the same [`Layout`] as the destination Vec
- /// 2. contains a non-zero offset
+ /// 1. The buffer does not have the same [`Layout`] as the destination Vec
+ /// 2. The buffer contains a non-zero offset
/// 3. The buffer is shared
pub fn into_vec<T: ArrowNativeType>(self) -> Result<Vec<T>, Self> {
let layout = match self.data.deallocation() {
