This is an automated email from the ASF dual-hosted git repository.
alamb 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 59234c226f docs(arrow-select): document FilterSelection /
FilterPredicate::selection (docs for #9755) (#10056)
59234c226f is described below
commit 59234c226f33e5fbe7af109e62feb6e42aece1cd
Author: Andrew Lamb <[email protected]>
AuthorDate: Tue Aug 4 12:55:59 2026 -0400
docs(arrow-select): document FilterSelection / FilterPredicate::selection
(docs for #9755) (#10056)
# Which issue does this PR close?
Documentation follow-up for #9755 (`arrow-select: fuse inline
Utf8View/BinaryView filter coalescing`), which has now merged.
# Rationale for this change
The `pub(crate)` filtering APIs added alongside the fused inline-view
pathhad little explanation of *why* they exist or how to use them. This
adds that rationale.
# What changes are included in this PR?
Comments only
# Are there any user-facing changes?
No (the documented items are `pub(crate)`).
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
---
arrow-select/src/filter.rs | 18 +++++++++++++++++-
1 file changed, 17 insertions(+), 1 deletion(-)
diff --git a/arrow-select/src/filter.rs b/arrow-select/src/filter.rs
index b7227cf6d9..e3ef6daa96 100644
--- a/arrow-select/src/filter.rs
+++ b/arrow-select/src/filter.rs
@@ -365,10 +365,18 @@ impl IterationStrategy {
}
/// Borrowed description of which rows a [`FilterPredicate`] selects.
+///
+/// This is used for filtering multiple arrays with the same predicate without
+/// having to clone the predicate's internal data structures (e.g. the list of
+/// indices or slices).
pub(crate) enum FilterSelection<'a> {
+ /// No rows are selected
None,
+ /// All `len` rows are selected
All { len: usize },
+ /// Iterator of `(start, end)` slices, each a run of contiguous selected
rows
Slices(FilterSlices<'a>),
+ /// Iterator of the indices of the selected rows
Indices(FilterIndices<'a>),
}
@@ -378,7 +386,9 @@ pub(crate) type FilterSlices<'a> =
pub(crate) type FilterIndices<'a> =
FilterIterator<std::iter::Copied<std::slice::Iter<'a, usize>>,
IndexIterator<'a>>;
-/// Holds either materialized rows or a lazy iterator.
+/// Internal implementation of [`FilterSelection`] that holds either an
iterator
+/// over a precomputed (materialized) list of rows, or a lazy iterator that
+/// derives the selected rows from the predicate on the fly.
///
/// This does not implement [`Iterator`] on purpose. Callers use
/// [`Self::for_each`] or [`Self::try_for_each`] so the enum is matched once
@@ -393,6 +403,7 @@ where
M: Iterator,
I: Iterator<Item = M::Item>,
{
+ /// Call the infallible function `f` for each item in this
[`FilterIterator`]
pub(crate) fn for_each<F>(self, f: F)
where
F: FnMut(M::Item),
@@ -403,6 +414,8 @@ where
}
}
+ /// Call the fallible function `f` for each item in this
[`FilterIterator`],
+ /// stopping and returning the error if `f` returns `Err`.
pub(crate) fn try_for_each<F, E>(self, mut f: F) -> Result<(), E>
where
F: FnMut(M::Item) -> Result<(), E>,
@@ -429,6 +442,7 @@ where
pub struct FilterPredicate {
filter: BooleanArray,
count: usize,
+ /// Precomputed strategy for iterating over the selected rows of this
predicate
strategy: IterationStrategy,
}
@@ -468,6 +482,8 @@ impl FilterPredicate {
self.count
}
+ /// Return a [`FilterSelection`] for iterating over the rows selected by
+ /// this [`FilterPredicate`].
pub(crate) fn selection(&self) -> FilterSelection<'_> {
match &self.strategy {
IterationStrategy::None => FilterSelection::None,
