This is an automated email from the ASF dual-hosted git repository.
Jefffrey 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 fc3591e082 docs(arrow-select): document the InProgressArray copy
methods (#10057)
fc3591e082 is described below
commit fc3591e0829dfd7bdf26330f75b690459f9c6605
Author: Andrew Lamb <[email protected]>
AuthorDate: Wed Aug 5 19:51:03 2026 -0400
docs(arrow-select): document the InProgressArray copy methods (#10057)
Documentation follow-up for #9755.
Comments only — no code changes. Documents the `InProgressArray` copy
methods and clarifies which operate on the source set via `set_source`
versus the one that takes the source directly.
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
---
arrow-select/src/coalesce.rs | 19 +++++++++++++++----
arrow-select/src/coalesce/byte_view.rs | 6 +++++-
2 files changed, 20 insertions(+), 5 deletions(-)
diff --git a/arrow-select/src/coalesce.rs b/arrow-select/src/coalesce.rs
index d1d73abdd8..248c7b05a7 100644
--- a/arrow-select/src/coalesce.rs
+++ b/arrow-select/src/coalesce.rs
@@ -707,9 +707,9 @@ fn create_in_progress_array(data_type: &DataType,
batch_size: usize) -> Box<dyn
/// Incrementally builds up arrays
///
/// [`GenericInProgressArray`] is the default implementation that buffers
-/// arrays and uses other kernels concatenates them when finished.
+/// arrays, uses other kernels, and concatenates them when finished.
///
-/// Some types have specialized implementations for this array types (e.g.,
+/// Some types have specialized, faster implementations (e.g.,
/// [`StringViewArray`], etc.).
///
/// [`StringViewArray`]: arrow_array::StringViewArray
@@ -722,17 +722,24 @@ trait InProgressArray: std::fmt::Debug + Send + Sync {
/// Copy rows from the current source array into the in-progress array
///
- /// The source array is set by [`Self::set_source`].
+ /// Note: The source array is set by [`Self::set_source`].
///
/// Return an error if the source array is not set
fn copy_rows(&mut self, offset: usize, len: usize) -> Result<(),
ArrowError>;
/// Copy rows selected by `filter` from the current source array.
+ ///
+ /// The default implementation calls [`Self::copy_rows_by_selection`]
fn copy_rows_by_filter(&mut self, filter: &FilterPredicate) -> Result<(),
ArrowError> {
self.copy_rows_by_selection(filter.selection())
}
- /// Copy rows selected by `filter` from `source`.
+ /// Copy rows selected by a [`FilterPredicate`] from `source`.
+ ///
+ /// Unlike the other copy methods, the source array is passed in directly,
+ /// which allows implementations more flexibility. The default
+ /// implementation simply sets `source` via [`Self::set_source`] and then
+ /// calls [`Self::copy_rows_by_filter`].
fn copy_rows_by_filter_from(
&mut self,
source: ArrayRef,
@@ -745,6 +752,10 @@ trait InProgressArray: std::fmt::Debug + Send + Sync {
}
/// Copy rows described by a [`FilterSelection`] from the current source
array.
+ ///
+ /// You typically get a [`FilterSelection`] from
[`FilterPredicate::selection`].
+ ///
+ /// Note: The source array is set by [`Self::set_source`].
fn copy_rows_by_selection(&mut self, selection: FilterSelection<'_>) ->
Result<(), ArrowError> {
match selection {
FilterSelection::None => Ok(()),
diff --git a/arrow-select/src/coalesce/byte_view.rs
b/arrow-select/src/coalesce/byte_view.rs
index 4cf0e006df..5bfee774b8 100644
--- a/arrow-select/src/coalesce/byte_view.rs
+++ b/arrow-select/src/coalesce/byte_view.rs
@@ -462,6 +462,8 @@ impl<B: ByteViewType> InProgressArray for
InProgressByteViewArray<B> {
filter: &FilterPredicate,
) -> Result<(), ArrowError> {
let s = source.as_byte_view::<B>();
+ // The source views reference no external buffers, so they must all be
+ // inline and we can copy just the nulls and views.
if s.data_buffers().is_empty() {
self.ensure_capacity();
self.append_nulls_by_filter(filter, s.nulls());
@@ -469,7 +471,9 @@ impl<B: ByteViewType> InProgressArray for
InProgressByteViewArray<B> {
return Ok(());
}
- // Match the filter kernel: filter views/nulls, but reuse data buffers.
+ // The views reference external buffers, so match the filter kernel:
+ // filter the views/nulls, but reuse the source's data buffers rather
+ // than copying the referenced string data.
let filtered = filter.filter(source.as_ref())?;
let filtered = filtered.as_byte_view::<B>();
