[arrow-datafusion] branch main updated: Minor: Add doc comments and example for `ScalarVaue::to_scalar` (#7491)

[al...@apache.org]

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-datafusion.git


The following commit(s) were added to refs/heads/main by this push:
     new 81d7f886e3 Minor: Add doc comments and example for `ScalarVaue::to_scalar` (#7491)
81d7f886e3 is described below

commit 81d7f886e3c9d9143ce73682dfaa338ba3d1cf83
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Thu Sep 7 12:43:04 2023 -0400

    Minor: Add doc comments and example for `ScalarVaue::to_scalar` (#7491)
---
 datafusion/common/src/scalar.rs | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/datafusion/common/src/scalar.rs b/datafusion/common/src/scalar.rs
index 3939293aac..b0e3a75e7f 100644
--- a/datafusion/common/src/scalar.rs
+++ b/datafusion/common/src/scalar.rs
@@ -1321,7 +1321,34 @@ impl ScalarValue {
         self.to_array_of_size(1)
     }
 
-    /// Converts a scalar into an arrow [`Scalar`]
+    /// Converts a scalar into an arrow [`Scalar`] (which implements
+    /// the [`Datum`] interface).
+    ///
+    /// This can be used to call arrow compute kernels such as `lt`
+    ///
+    /// # Example
+    /// ```
+    /// use datafusion_common::ScalarValue;
+    /// use arrow::array::{BooleanArray, Int32Array};
+    ///
+    /// let arr = Int32Array::from(vec![Some(1), None, Some(10)]);
+    /// let five = ScalarValue::Int32(Some(5));
+    ///
+    /// let result = arrow::compute::kernels::cmp::lt(
+    ///   &arr,
+    ///   &five.to_scalar(),
+    /// ).unwrap();
+    ///
+    /// let expected = BooleanArray::from(vec![
+    ///     Some(true),
+    ///     None,
+    ///     Some(false)
+    ///   ]
+    /// );
+    ///
+    /// assert_eq!(&result, &expected);
+    /// ```
+    /// [`Datum`]: arrow_array::Datum
     pub fn to_scalar(&self) -> Scalar<ArrayRef> {
         Scalar::new(self.to_array_of_size(1))
     }
@@ -1332,7 +1359,7 @@ impl ScalarValue {
     /// Returns an error if the iterator is empty or if the
     /// [`ScalarValue`]s are not all the same type
     ///
-    /// Example
+    /// # Example
     /// ```
     /// use datafusion_common::ScalarValue;
     /// use arrow::array::{ArrayRef, BooleanArray};