chore: add docs for how to use Extend for generic methods on ArrayBuilders

Author: wiedld

arrow-array/src/builder/mod.rs

@@ -134,6 +134,8 @@
 //!     }
 //! }
 //!
+//! /// For building arrays in generic code, use Extend instead of the append_* methods
+//! /// e.g. append_value, append_option, append_null
 //! impl<'a> Extend<&'a MyRow> for MyRowBuilder {
 //!     fn extend<T: IntoIterator<Item = &'a MyRow>>(&mut self, iter: T) {
 //!         iter.into_iter().for_each(|row| self.append(row));
@@ -193,8 +195,8 @@ use std::any::Any;
 ///
 /// ```
 /// // Create
-/// # use arrow_array::{ArrayRef, StringArray};
-/// # use arrow_array::builder::{ArrayBuilder, Float64Builder, Int64Builder, StringBuilder};
+/// # use arrow_array::{Array, ArrayRef, StringArray};
+/// # use arrow_array::builder::{ArrayBuilder, Float64Builder, Int64Builder, ListBuilder, StringBuilder};
 ///
 /// let mut data_builders: Vec<Box<dyn ArrayBuilder>> = vec![
 ///     Box::new(Float64Builder::new()),
@@ -234,6 +236,47 @@ use std::any::Any;
 ///         .value(0),
 ///     "🍎"
 /// );
+///
+/// // For generic methods that fill a list of values for an [`ArrayBuilder`], use the [`Extend`] trait.
+/// fn filter_and_fill<V, I: IntoIterator<Item = V>>(builder: &mut impl Extend<V>, values: I, filter: V)
+/// where V: PartialEq
+/// {
+///     builder.extend(values.into_iter().filter(|v| *v == filter));
+/// }
+/// let mut builder = StringBuilder::new();
+/// filter_and_fill(
+///     &mut builder,
+///     vec![Some("🍐"), Some("🍎"), None],
+///     Some("🍎"),
+/// );
+/// assert_eq!(builder.finish().len(), 1);
+///
+/// // For generic methods that fills lists-of-lists for an [`ArrayBuilder`], use the [`Extend`] trait.
+/// fn filter_and_fill_if_contains<T, V, I: IntoIterator<Item = Option<V>>>(
+///     list_builder: &mut impl Extend<Option<V>>,
+///     values: I,
+///     filter: Option<T>,
+/// ) where
+///     T: PartialEq,
+///     for<'a> &'a V: IntoIterator<Item = &'a Option<T>>,
+/// {
+///     list_builder.extend(values.into_iter().filter(|string: &Option<V>| {
+///         string
+///             .as_ref()
+///             .map(|str: &V| str.into_iter().any(|ch: &Option<T>| ch == &filter))
+///             .unwrap_or(false)
+///     }));
+///  }
+/// let builder = StringBuilder::new();
+/// let mut list_builder = ListBuilder::new(builder);
+/// let pear_pear = vec![Some("🍐"),Some("🍐")];
+/// let pear_app = vec![Some("🍐"),Some("🍎")];
+/// filter_and_fill_if_contains(
+///     &mut list_builder,
+///     vec![Some(pear_pear), Some(pear_app), None],
+///     Some("🍎"),
+/// );
+/// assert_eq!(list_builder.finish().len(), 1);
 /// ```
 pub trait ArrayBuilder: Any + Send + Sync {
     /// Returns the number of array slots in the builder