(arrow) branch main updated: GH-46321: [C++][Doc] Better explain ArrayData IsValid and GetNullCount (#46332)

[ap...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

apitrou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git


The following commit(s) were added to refs/heads/main by this push:
     new 5652af6631 GH-46321: [C++][Doc] Better explain ArrayData IsValid and GetNullCount (#46332)
5652af6631 is described below

commit 5652af6631f8035d2c7fea9236767b6b392cbbac
Author: Antoine Pitrou <an...@python.org>
AuthorDate: Wed May 7 09:12:15 2025 +0200

    GH-46321: [C++][Doc] Better explain ArrayData IsValid and GetNullCount (#46332)
    
    ### What changes are included in this PR?
    
    Address a comment that was not addressed in PR https://github.com/apache/arrow/pull/46271.
    
    ### Are these changes tested?
    
    No, only docstring changes.
    
    ### Are there any user-facing changes?
    
    No, only docstring changes.
    
    * GitHub Issue: #46321
    
    Authored-by: Antoine Pitrou <an...@python.org>
    Signed-off-by: Antoine Pitrou <an...@python.org>
---
 cpp/src/arrow/array/data.h | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/cpp/src/arrow/array/data.h b/cpp/src/arrow/array/data.h
index 29bec6f1b4..e921da86e1 100644
--- a/cpp/src/arrow/array/data.h
+++ b/cpp/src/arrow/array/data.h
@@ -217,6 +217,7 @@ struct ARROW_EXPORT ArrayData {
   /// queried instead.
   /// For dictionary arrays, this reflects the validity of the dictionary
   /// index, but the corresponding dictionary value might still be null.
+  /// For null arrays, this always returns false.
   bool IsValid(int64_t i) const {
     if (buffers[0] != NULLPTR) {
       return bit_util::GetBit(buffers[0]->data(), i + offset);
@@ -358,8 +359,16 @@ struct ARROW_EXPORT ArrayData {
 
   /// \brief Return the physical null count
   ///
-  /// The null count is lazily computed from the array's validity bitmap,
-  /// if not already cached.
+  /// This method returns the number of array elements for which `IsValid` would
+  /// return false.
+  ///
+  /// A cached value is returned if already available, otherwise it is first
+  /// computed and stored.
+  /// How it is is computed depends on the data type, see `IsValid` for details.
+  ///
+  /// Note that this method is typically much faster than calling `IsValid`
+  /// for all elements. Therefore, it helps avoid per-element validity bitmap
+  /// lookups in the common cases where the array contains zero or only nulls.
   int64_t GetNullCount() const;
 
   /// \brief Return true if the array may have nulls in its validity bitmap
@@ -492,9 +501,14 @@ struct ARROW_EXPORT BufferSpan {
   }
 };
 
-/// \brief EXPERIMENTAL: A non-owning ArrayData reference that is cheaply
-/// copyable and does not contain any shared_ptr objects. Do not use in public
-/// APIs aside from compute kernels for now
+/// \brief EXPERIMENTAL: A non-owning array data container
+///
+/// Unlike ArrayData, this class doesn't own its referenced data type nor data buffers.
+/// It is cheaply copyable and can therefore be suitable for use cases where
+/// shared_ptr overhead is not acceptable. However, care should be taken to
+/// keep alive the referenced objects and memory while the ArraySpan object is in use.
+/// For this reason, this should not be exposed in most public APIs (apart from
+/// compute kernel interfaces).
 struct ARROW_EXPORT ArraySpan {
   const DataType* type = NULLPTR;
   int64_t length = 0;