(arrow-rs) branch main updated: Improve documentation for `prep_null_mask_flter (#8722)

[jeffreyvo]

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 ed2cf821ec Improve documentation for `prep_null_mask_flter (#8722)
ed2cf821ec is described below

commit ed2cf821eceb3bc4468c04bd295b2b17aa8316de
Author: Andrew Lamb <and...@nerdnetworks.org>
AuthorDate: Sun Dec 14 22:48:22 2025 -0500

    Improve documentation for `prep_null_mask_flter (#8722)
    
    # Which issue does this PR close?
    
    - related to https://github.com/apache/arrow-rs/pull/8711
    
    # Rationale for this change
    
    While reviewing https://github.com/apache/arrow-rs/pull/8711 from
    @rluvaton I found that the documentation for `prep_null_mask_filter` was
    not very informative
    
    # What changes are included in this PR?
    
    improve the documentation example and add a doc test
    
    # Are these changes tested?
    yes
    
    
    # Are there any user-facing changes?
    
    better docs
---
 arrow-select/src/filter.rs | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/arrow-select/src/filter.rs b/arrow-select/src/filter.rs
index e0e0fef716..6153845e8c 100644
--- a/arrow-select/src/filter.rs
+++ b/arrow-select/src/filter.rs
@@ -118,7 +118,33 @@ fn filter_count(filter: &BooleanArray) -> usize {
     filter.values().count_set_bits()
 }
 
-/// Remove null values by do a bitmask AND operation with null bits and the 
boolean bits.
+/// Convert all null values in `BooleanArray` to `false`
+///
+/// This is useful for filter-like operations which select only `true`
+/// values, but not `false` or `NULL` values
+///
+/// Internally this is implemented as a bitwise `AND` operation with null bits
+/// and the boolean bits.
+///
+/// # Example
+/// ```
+/// # use arrow_array::{Array, BooleanArray};
+/// # use arrow_select::filter::prep_null_mask_filter;
+/// let filter = BooleanArray::from(vec![
+///   Some(true),
+///   Some(false),
+///   None
+/// ]);
+/// // convert Boolean array to a filter mask
+/// let null_mask = prep_null_mask_filter(&filter);
+/// // there are no nulls in the output mask
+/// assert!(null_mask.nulls().is_none());
+/// assert_eq!(null_mask, BooleanArray::from(vec![
+///  true,
+///  false,
+///  false, // Null is converted to false
+/// ]));
+/// ```
 pub fn prep_null_mask_filter(filter: &BooleanArray) -> BooleanArray {
     let nulls = filter.nulls().unwrap();
     let mask = filter.values() & nulls.inner();