perf: Optimize overlay with new string builder (#22182)

## Which issue does this PR close?

- Closes #22181.

## Rationale for this change

This PR optimizes `overlay` by switching to the new bulk-NULL string
builders, and also taking advantage of `append_with` to avoid copying
into an intermediate `String`. Along the way, we also optimize character
counting for Unicode inputs, reducing the number of times we need to
walk the input string.

Benchmarks (Arm64):

StringArray

  - all_utf8: 3.6 ms → 1.85 ms (-48.6%)
  - ascii: 319.8 µs → 134.9 µs (-57.8%)
  - high_nulls: 400.7 µs → 75.1 µs (-81.3%)
  - low_nulls: 2.0 ms → 1.03 ms (-48.3%)
  - no_for: 2.1 ms → 1.12 ms (-46.8%)
  - no_nulls: 2.0 ms → 1.05 ms (-48.4%)

StringViewArray

  - all_utf8: 3.6 ms → 1.86 ms (-48.4%)
  - ascii: 313.8 µs → 133.8 µs (-57.4%)
  - low_nulls: 2.0 ms → 1.05 ms (-47.4%)
  - no_for: 2.1 ms → 1.12 ms (-46.7%)

## What changes are included in this PR?

* Switch to `BulkNullStringArrayBuilder` to build the result set, and
`NullBuffer::union_many` to compute NULLs in bulk
* Use `append_with` to avoid an intermediate string copy
* For Unicode inputs, replace three `char_indices` walks with a single
string traversal
* More comprehensive benchmark coverage
* Fix a misleading/inaccurate error message

## Are these changes tested?

Yes, covered by existing tests.

## Are there any user-facing changes?

No.

Author: neilconway

datafusion/functions/benches/overlay.rs

@@ -21,40 +21,56 @@ use arrow::datatypes::{DataType, Field};
 use criterion::{Criterion, criterion_group, criterion_main};
 use datafusion_common::ScalarValue;
 use datafusion_common::config::ConfigOptions;
-use datafusion_expr::{ColumnarValue, ScalarFunctionArgs};
+use datafusion_expr::{ColumnarValue, ScalarFunctionArgs, ScalarUDF};
 use helper::gen_string_array;
 use std::hint::black_box;
 use std::sync::Arc;
 
-fn criterion_benchmark(c: &mut Criterion) {
-    const N_ROWS: usize = 8192;
+#[expect(clippy::too_many_arguments)]
+fn bench_overlay(
+    c: &mut Criterion,
+    name: &str,
+    overlay: &ScalarUDF,
+    n_rows: usize,
+    null_density: f32,
+    utf8_density: f32,
+    is_string_view: bool,
+    with_for: bool,
+) {
     const STR_LEN: usize = 128;
 
-    let overlay = datafusion_functions::core::overlay();
-    let config_options = Arc::new(ConfigOptions::default());
-
-    let mut args = gen_string_array(N_ROWS, STR_LEN, 0.1, 0.5, false);
-    args.push(ColumnarValue::Scalar(ScalarValue::Utf8(Some(
-        "DataFusion".to_string(),
-    ))));
+    let mut args =
+        gen_string_array(n_rows, STR_LEN, null_density, utf8_density, is_string_view);
+    // The substring scalar's type must match the string column's type (the
+    // function dispatches per-type without coercion).
+    let substr = "DataFusion".to_string();
+    let substr_scalar = if is_string_view {
+        ScalarValue::Utf8View(Some(substr))
+    } else {
+        ScalarValue::Utf8(Some(substr))
+    };
+    args.push(ColumnarValue::Scalar(substr_scalar));
     args.push(ColumnarValue::Scalar(ScalarValue::Int64(Some(32))));
-    args.push(ColumnarValue::Scalar(ScalarValue::Int64(Some(8))));
+    if with_for {
+        args.push(ColumnarValue::Scalar(ScalarValue::Int64(Some(8))));
+    }
 
     let arg_fields = args
         .iter()
         .enumerate()
         .map(|(idx, arg)| Field::new(format!("arg_{idx}"), arg.data_type(), true).into())
         .collect::<Vec<_>>();
     let return_field = Arc::new(Field::new("f", DataType::Utf8, true));
+    let config_options = Arc::new(ConfigOptions::default());
 
-    c.bench_function("overlay_StringArray_utf8_scalar_args", |b| {
+    c.bench_function(name, |b| {
         b.iter(|| {
             black_box(
                 overlay
                     .invoke_with_args(ScalarFunctionArgs {
                         args: args.clone(),
                         arg_fields: arg_fields.clone(),
-                        number_rows: N_ROWS,
+                        number_rows: n_rows,
                         return_field: Arc::clone(&return_field),
                         config_options: Arc::clone(&config_options),
                     })
@@ -64,5 +80,121 @@ fn criterion_benchmark(c: &mut Criterion) {
     });
 }
 
+fn criterion_benchmark(c: &mut Criterion) {
+    const N_ROWS: usize = 8192;
+    const MIXED_UTF8: f32 = 0.5;
+    let overlay = datafusion_functions::core::overlay();
+
+    // Null-density variants on StringArray (mixed ASCII/UTF-8, 4-arg form).
+    bench_overlay(
+        c,
+        "overlay_StringArray_low_nulls",
+        &overlay,
+        N_ROWS,
+        0.1,
+        MIXED_UTF8,
+        false,
+        true,
+    );
+    bench_overlay(
+        c,
+        "overlay_StringArray_high_nulls",
+        &overlay,
+        N_ROWS,
+        0.9,
+        MIXED_UTF8,
+        false,
+        true,
+    );
+    bench_overlay(
+        c,
+        "overlay_StringArray_no_nulls",
+        &overlay,
+        N_ROWS,
+        0.0,
+        MIXED_UTF8,
+        false,
+        true,
+    );
+
+    // Content variants on StringArray (no nulls, 4-arg form). Pair against
+    // `overlay_StringArray_no_nulls` to isolate the impact of UTF-8 density.
+    bench_overlay(
+        c,
+        "overlay_StringArray_ascii",
+        &overlay,
+        N_ROWS,
+        0.0,
+        0.0,
+        false,
+        true,
+    );
+    bench_overlay(
+        c,
+        "overlay_StringArray_all_utf8",
+        &overlay,
+        N_ROWS,
+        0.0,
+        1.0,
+        false,
+        true,
+    );
+
+    // 3-arg form (no FOR clause), where the replace length is derived from
+    // the substring per row.
+    bench_overlay(
+        c,
+        "overlay_StringArray_no_for",
+        &overlay,
+        N_ROWS,
+        0.0,
+        MIXED_UTF8,
+        false,
+        false,
+    );
+
+    // StringViewArray counterparts.
+    bench_overlay(
+        c,
+        "overlay_StringViewArray_low_nulls",
+        &overlay,
+        N_ROWS,
+        0.1,
+        MIXED_UTF8,
+        true,
+        true,
+    );
+    bench_overlay(
+        c,
+        "overlay_StringViewArray_ascii",
+        &overlay,
+        N_ROWS,
+        0.0,
+        0.0,
+        true,
+        true,
+    );
+    bench_overlay(
+        c,
+        "overlay_StringViewArray_all_utf8",
+        &overlay,
+        N_ROWS,
+        0.0,
+        1.0,
+        true,
+        true,
+    );
+    bench_overlay(
+        c,
+        "overlay_StringViewArray_no_for",
+        &overlay,
+        N_ROWS,
+        0.0,
+        MIXED_UTF8,
+        true,
+        false,
+    );
+}
+
 criterion_group!(benches, criterion_benchmark);
 criterion_main!(benches);