This is an automated email from the ASF dual-hosted git repository.
tustvold pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/master by this push:
new 526c57a0f Minor: add examples for `ListBuilder` and
`GenericListBuilder` (#3891)
526c57a0f is described below
commit 526c57a0f65ee7aaa838f252f48c8179f7d9ce03
Author: Andrew Lamb <[email protected]>
AuthorDate: Thu Mar 23 13:45:08 2023 +0100
Minor: add examples for `ListBuilder` and `GenericListBuilder` (#3891)
* Minor: add examples for `ListBuilder` and `GenericListBuilder`
* use '[' and ']' for list notation
---
arrow-array/src/builder/generic_list_builder.rs | 10 +++-
arrow-array/src/builder/mod.rs | 65 ++++++++++++++++++++++++-
2 files changed, 72 insertions(+), 3 deletions(-)
diff --git a/arrow-array/src/builder/generic_list_builder.rs
b/arrow-array/src/builder/generic_list_builder.rs
index 622847554..de09694fb 100644
--- a/arrow-array/src/builder/generic_list_builder.rs
+++ b/arrow-array/src/builder/generic_list_builder.rs
@@ -24,7 +24,15 @@ use arrow_schema::Field;
use std::any::Any;
use std::sync::Arc;
-/// Array builder for [`GenericListArray`]
+/// Array builder for [`GenericListArray`]s.
+///
+/// Use [`ListBuilder`] to build [`ListArray`]s and [`LargeListBuilder`] to
build [`LargeListArray`]s.
+///
+///
+/// [`ListBuilder`]: crate::builder::ListBuilder
+/// [`ListArray`]: crate::array::ListArray
+/// [`LargeListBuilder`]: crate::builder::LargeListBuilder
+/// [`LargeListArray`]: crate::array::LargeListArray
#[derive(Debug)]
pub struct GenericListBuilder<OffsetSize: OffsetSizeTrait, T: ArrayBuilder> {
offsets_builder: BufferBuilder<OffsetSize>,
diff --git a/arrow-array/src/builder/mod.rs b/arrow-array/src/builder/mod.rs
index fc2454635..df26fa358 100644
--- a/arrow-array/src/builder/mod.rs
+++ b/arrow-array/src/builder/mod.rs
@@ -132,9 +132,70 @@ pub trait ArrayBuilder: Any + Send {
fn into_box_any(self: Box<Self>) -> Box<dyn Any>;
}
-/// A list array builder with i32 offsets
+/// Builder for [`ListArray`]s (i32 offsets)
+///
+/// [`ListArray`]: crate::array::ListArray
+///
+/// # Example
+///
+/// ```
+/// # use arrow_array::builder::{StringBuilder, ListBuilder};
+/// # use arrow_array::ListArray;
+/// // Build a 3 element array of lists:
+/// //
+/// // column
+/// // ---------
+/// // [one]
+/// // []
+/// // [two, three]
+///
+/// let mut builder = ListBuilder::new(StringBuilder::new());
+/// // [one]
+/// builder.values().append_value("one");
+/// builder.append(true);
+/// // []
+/// builder.append(true);
+/// // [two, three]
+/// builder.values().append_value("two");
+/// builder.values().append_value("three");
+/// builder.append(true);
+///
+/// // Create an array
+/// let list_array: ListArray = builder.finish();
+/// ```
pub type ListBuilder<T> = GenericListBuilder<i32, T>;
-/// A list array builder with i64 offsets
+
+/// Builder for [`LargeListArray`]s (i64 offsets)
+///
+/// [`LargeListArray`]: crate::array::LargeListArray
+///
+/// # Example
+///
+/// ```
+/// # use arrow_array::builder::{StringBuilder, LargeListBuilder};
+/// # use arrow_array::LargeListArray;
+/// // Build a 3 element array of lists:
+/// //
+/// // column
+/// // ---------
+/// // [one],
+/// // [],
+/// // [two, three]
+///
+/// let mut builder = LargeListBuilder::new(StringBuilder::new());
+/// // [one]
+/// builder.values().append_value("one");
+/// builder.append(true);
+/// // []
+/// builder.append(true);
+/// // [two, three]
+/// builder.values().append_value("two");
+/// builder.values().append_value("three");
+/// builder.append(true);
+///
+/// // Create an array
+/// let list_array: LargeListArray = builder.finish();
+/// ```
pub type LargeListBuilder<T> = GenericListBuilder<i64, T>;
/// A binary array builder with i32 offsets
