Updates for documentation, minor improvements.

datafusion/functions/src/regex/regexpcount.rs

@@ -15,24 +15,24 @@
 // specific language governing permissions and limitations
 // under the License.
 
+use crate::string::common::StringArrayType;
 use arrow::array::{Array, ArrayRef, AsArray, Datum, Int64Array};
 use arrow::datatypes::{DataType, Int64Type};
 use arrow::datatypes::{
     DataType::Int64, DataType::LargeUtf8, DataType::Utf8, DataType::Utf8View,
 };
 use arrow::error::ArrowError;
 use datafusion_common::{exec_err, internal_err, Result, ScalarValue};
+use datafusion_expr::scalar_doc_sections::DOC_SECTION_REGEX;
 use datafusion_expr::{
-    ColumnarValue, ScalarUDFImpl, Signature, TypeSignature::Exact,
+    ColumnarValue, Documentation, ScalarUDFImpl, Signature, TypeSignature::Exact,
     TypeSignature::Uniform, Volatility,
 };
 use itertools::izip;
 use regex::Regex;
 use std::collections::hash_map::Entry;
 use std::collections::HashMap;
-use std::sync::Arc;
-
-use crate::string::common::StringArrayType;
+use std::sync::{Arc, OnceLock};
 
 #[derive(Debug)]
 pub struct RegexpCountFunc {
@@ -50,13 +50,13 @@ impl RegexpCountFunc {
         Self {
             signature: Signature::one_of(
                 vec![
-                    Uniform(2, vec![Utf8, LargeUtf8, Utf8View]),
-                    Exact(vec![Utf8, Utf8, Int64]),
-                    Exact(vec![Utf8, Utf8, Int64, Utf8]),
-                    Exact(vec![LargeUtf8, LargeUtf8, Int64]),
-                    Exact(vec![LargeUtf8, LargeUtf8, Int64, LargeUtf8]),
+                    Uniform(2, vec![Utf8View, LargeUtf8, Utf8]),
                     Exact(vec![Utf8View, Utf8View, Int64]),
+                    Exact(vec![LargeUtf8, LargeUtf8, Int64]),
+                    Exact(vec![Utf8, Utf8, Int64]),
                     Exact(vec![Utf8View, Utf8View, Int64, Utf8View]),
+                    Exact(vec![LargeUtf8, LargeUtf8, Int64, LargeUtf8]),
+                    Exact(vec![Utf8, Utf8, Int64, Utf8]),
                 ],
                 Volatility::Immutable,
             ),
@@ -81,7 +81,7 @@ impl ScalarUDFImpl for RegexpCountFunc {
         Ok(Int64)
     }
 
-    fn invoke(&self, args: &[datafusion_expr::ColumnarValue]) -> Result<ColumnarValue> {
+    fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue> {
         let len = args
             .iter()
             .fold(Option::<usize>::None, |acc, arg| match arg {
@@ -105,6 +105,36 @@ impl ScalarUDFImpl for RegexpCountFunc {
             result.map(ColumnarValue::Array)
         }
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_regexp_count_doc())
+    }
+}
+
+static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
+
+fn get_regexp_count_doc() -> &'static Documentation {
+    DOCUMENTATION.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_REGEX)
+            .with_description("Returns the number of matches that a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has in a string.")
+            .with_syntax_example("regexp_count(str, regexp[, start, flags])")
+            .with_sql_example(r#"```sql
+>
+```"#)
+            .with_standard_argument("str", "String")
+            .with_standard_argument("regexp","Regular")
+            .with_argument("start", "- **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function.")
+            .with_argument("flags",
+                           r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
+  - **i**: case-insensitive: letters match both upper and lower case
+  - **m**: multi-line mode: ^ and $ match begin/end of line
+  - **s**: allow . to match \n
+  - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
+  - **U**: swap the meaning of x* and x*?"#)
+            .build()
+            .unwrap()
+    })
 }
 
 pub fn regexp_count_func(args: &[ArrayRef]) -> Result<ArrayRef> {
@@ -264,6 +294,8 @@ where
             (None, None, true)
         };
 
+    let mut regex_cache = HashMap::new();
+
     match (is_regex_scalar, is_start_scalar, is_flags_scalar) {
         (true, true, true) => {
             let regex = match regex_scalar {
@@ -294,12 +326,11 @@ where
             if values.len() != flags_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "flags_array must be the same length as values array; got {} and {}",
+                    flags_array.len(),
                     values.len(),
-                    flags_array.len()
                 )));
             }
 
-            let mut regex_cache = HashMap::new();
             Ok(Arc::new(Int64Array::from_iter_values(
                 values
                     .iter()
@@ -344,12 +375,11 @@ where
             if values.len() != flags_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "flags_array must be the same length as values array; got {} and {}",
+                    flags_array.len(),
                     values.len(),
-                    flags_array.len()
                 )));
             }
 
-            let mut regex_cache = HashMap::new();
             Ok(Arc::new(Int64Array::from_iter_values(
                 izip!(
                     values.iter(),
@@ -369,12 +399,11 @@ where
             if values.len() != regex_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "regex_array must be the same length as values array; got {} and {}",
+                    regex_array.len(),
                     values.len(),
-                    regex_array.len()
                 )));
             }
 
-            let mut regex_cache = HashMap::new();
             Ok(Arc::new(Int64Array::from_iter_values(
                 values
                     .iter()
@@ -399,21 +428,20 @@ where
             if values.len() != regex_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "regex_array must be the same length as values array; got {} and {}",
+                    regex_array.len(),
                     values.len(),
-                    regex_array.len()
                 )));
             }
 
             let flags_array = flags_array.unwrap();
             if values.len() != flags_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "flags_array must be the same length as values array; got {} and {}",
+                    flags_array.len(),
                     values.len(),
-                    flags_array.len()
                 )));
             }
 
-            let mut regex_cache = HashMap::new();
             Ok(Arc::new(Int64Array::from_iter_values(
                 izip!(values.iter(), regex_array.iter(), flags_array.iter())
                     .map(|(value, regex, flags)| {
@@ -434,21 +462,20 @@ where
             if values.len() != regex_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "regex_array must be the same length as values array; got {} and {}",
+                    regex_array.len(),
                     values.len(),
-                    regex_array.len()
                 )));
             }
 
             let start_array = start_array.unwrap();
             if values.len() != start_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "start_array must be the same length as values array; got {} and {}",
+                    start_array.len(),
                     values.len(),
-                    start_array.len()
                 )));
             }
 
-            let mut regex_cache = HashMap::new();
             Ok(Arc::new(Int64Array::from_iter_values(
                 izip!(values.iter(), regex_array.iter(), start_array.iter())
                     .map(|(value, regex, start)| {
@@ -471,30 +498,29 @@ where
             if values.len() != regex_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "regex_array must be the same length as values array; got {} and {}",
+                    regex_array.len(),
                     values.len(),
-                    regex_array.len()
                 )));
             }
 
             let start_array = start_array.unwrap();
             if values.len() != start_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "start_array must be the same length as values array; got {} and {}",
+                    start_array.len(),
                     values.len(),
-                    start_array.len()
                 )));
             }
 
             let flags_array = flags_array.unwrap();
             if values.len() != flags_array.len() {
                 return Err(ArrowError::ComputeError(format!(
                     "flags_array must be the same length as values array; got {} and {}",
+                    flags_array.len(),
                     values.len(),
-                    flags_array.len()
                 )));
             }
 
-            let mut regex_cache = HashMap::new();
             Ok(Arc::new(Int64Array::from_iter_values(
                 izip!(
                     values.iter(),

docs/source/user-guide/sql/scalar_functions.md

@@ -569,38 +569,13 @@ Apache DataFusion uses a [PCRE-like] regular expression [syntax]
 (minus support for several features including look-around and backreferences).
 The following regular expression functions are supported:
 
-- [regexp_count](#regex_count)
 - [regexp_like](#regexp_like)
 - [regexp_match](#regexp_match)
 - [regexp_replace](#regexp_replace)
 
 [pcre-like]: https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions
 [syntax]: https://docs.rs/regex/latest/regex/#syntax
 
-### `regexp_count`
-
-Returns the number of matchs that a [regular expression] has in a string.
-
-```
-regexp_count(str, regexp[, start, flags])
-```
-
-#### Arguments
-
-- **str**: String expression to operate on.
-  Can be a constant, column, or function, and any combination of string operators.
-- **regexp**: Regular expression to test against the string expression.
-  Can be a constant, column, or function.
-- **start**: Optional start position to search for the regular expression.
-  Can be a constant, column, or function.
-- **flags**: Optional regular expression flags that control the behavior of the
-  regular expression. The following flags are supported:
-  - **i**: case-insensitive: letters match both upper and lower case
-  - **m**: multi-line mode: ^ and $ match begin/end of line
-  - **s**: allow . to match \n
-  - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
-  - **U**: swap the meaning of x* and x*?
-
 ### `regexp_like`
 
 Returns true if a [regular expression] has at least one match in a string,