chore: move to mod docs and add more examples

arrow-array/src/builder/mod.rs

@@ -78,6 +78,73 @@
 //! ))
 //! ```
 //!
+//! # Using the [`Extend`] trait to append values from an iterator:
+//!
+//! ```
+//! # use arrow_array::{Array};
+//! # use arrow_array::builder::{ArrayBuilder, StringBuilder};
+//!
+//! let mut builder = StringBuilder::new();
+//! builder.extend(vec![Some("🍐"), Some("🍎"), None]);
+//! assert_eq!(builder.finish().len(), 3);
+//! ```
+//!
+//! # Using the [`Extend`] trait to write generic functions:
+//!
+//! ```
+//! # use arrow_array::{Array, ArrayRef, StringArray};
+//! # use arrow_array::builder::{ArrayBuilder, Int32Builder, ListBuilder, StringBuilder};
+//!
+//! // 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 string_builder = StringBuilder::new();
+//! filter_and_fill(
+//!     &mut string_builder,
+//!     vec![Some("🍐"), Some("🍎"), None],
+//!     Some("🍎"),
+//! );
+//! assert_eq!(string_builder.finish().len(), 1);
+//!
+//! let mut int_builder = Int32Builder::new();
+//! filter_and_fill(
+//!     &mut int_builder,
+//!     vec![Some(11), Some(42), None],
+//!     Some(42),
+//! );
+//! assert_eq!(int_builder.finish().len(), 1);
+//!
+//! // For generic methods that fill 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);
+//! ```
+//!
 //! # Custom Builders
 //!
 //! It is common to have a collection of statically defined Rust types that
@@ -195,8 +262,8 @@ use std::any::Any;
 ///
 /// ```
 /// // Create
-/// # use arrow_array::{Array, ArrayRef, StringArray};
-/// # use arrow_array::builder::{ArrayBuilder, Float64Builder, Int64Builder, ListBuilder, StringBuilder};
+/// # use arrow_array::{ArrayRef, StringArray};
+/// # use arrow_array::builder::{ArrayBuilder, Float64Builder, Int64Builder, StringBuilder};
 ///
 /// let mut data_builders: Vec<Box<dyn ArrayBuilder>> = vec![
 ///     Box::new(Float64Builder::new()),
@@ -236,47 +303,6 @@ 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 fill 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