(arrow-datafusion) 03/03: improve docs

[al...@apache.org]

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

alamb pushed a commit to branch alamb/array_crate
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git

commit 8d1c0a1395b4a4a552c6feb9419b53dd2f57b7a8
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Fri Feb 2 09:58:26 2024 -0500

    improve docs
---
 datafusion/expr/src/columnar_value.rs | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/datafusion/expr/src/columnar_value.rs b/datafusion/expr/src/columnar_value.rs
index 5f2481ebc6..378ef52f01 100644
--- a/datafusion/expr/src/columnar_value.rs
+++ b/datafusion/expr/src/columnar_value.rs
@@ -78,9 +78,18 @@ impl ColumnarValue {
 
     /// A helper function used to infer the length of arguments of Scalar
     /// functions and convert [`ColumnarValue`]s to [`ArrayRef`]s with the
-    /// inferred length. Note that this function only works for functions that
-    /// accept either all scalar arguments or all arguments are arrays
-    /// with same length. Otherwise, it will return an error.
+    /// inferred length.
+    ///
+    /// # Note on Performance
+    ///
+    /// This function expands any `ScalalarValues` to arrays of the same length.
+    /// This allows a single function implementaiton in terms of arrays, but it
+    /// can be inefficient. It is recommended to provide specialized
+    /// implementations for scalar values if performance is a concern.
+    ///
+    /// # Errors
+    ///
+    /// If there are multiple array arguments that have different lengths
     pub fn values_to_arrays(args: &[ColumnarValue]) -> Result<Vec<ArrayRef>> {
         if args.is_empty() {
             return Ok(vec![]);