tustvold commented on code in PR #3951:
URL: https://github.com/apache/arrow-rs/pull/3951#discussion_r1149116257
##########
arrow-array/src/builder/mod.rs:
##########
@@ -15,7 +15,140 @@
// specific language governing permissions and limitations
// under the License.
-//! Defines builders for the various array types
+//! Defines builders that can be used to safely build arrays
+//!
+//! # Basic Usage
+//!
+//! Builders can be used to build simple, non-nested arrays
+//!
+//! ```
+//! # use arrow_array::builder::Int32Builder;
+//! # use arrow_array::PrimitiveArray;
+//! let mut a = Int32Builder::new();
+//! a.append_value(1);
+//! a.append_null();
+//! a.append_value(2);
+//! let a = a.finish();
+//!
+//! assert_eq!(a, PrimitiveArray::from(vec![Some(1), None, Some(2)]));
+//! ```
+//!
+//! ```
+//! # use arrow_array::builder::StringBuilder;
+//! # use arrow_array::{Array, StringArray};
+//! let mut a = StringBuilder::new();
+//! a.append_value("foo");
+//! a.append_value("bar");
+//! a.append_null();
+//! let a = a.finish();
+//!
+//! assert_eq!(a, StringArray::from_iter([Some("foo"), Some("bar"), None]));
+//! ```
+//!
+//! # Nested Usage
+//!
+//! Builders can also be used to build more complex nested arrays, such as
lists
+//!
+//! ```
+//! # use arrow_array::builder::{Int32Builder, ListBuilder};
+//! # use arrow_array::ListArray;
+//! # use arrow_array::types::Int32Type;
+//! let mut a = ListBuilder::new(Int32Builder::new());
+//! // [1, 2]
+//! a.values().append_value(1);
+//! a.values().append_value(2);
+//! a.append(true);
+//! // null
+//! a.append(false);
+//! // []
+//! a.append(true);
+//! // [3, null]
+//! a.values().append_value(3);
+//! a.values().append_null();
+//! a.append(true);
+//!
+//! // [[1, 2], null, [], [3, null]]
+//! let a = a.finish();
+//!
+//! assert_eq!(a, ListArray::from_iter_primitive::<Int32Type, _, _>([
+//! Some(vec![Some(1), Some(2)]),
+//! None,
+//! Some(vec![]),
+//! Some(vec![Some(3), None])]
+//! ))
+//! ```
+//!
+//! # Row Conversion
+//!
+//! It is common to have a statically defined row representation, and to want
to convert
+//! this to an arrow representation. An example of this can be seen below
+//!
+//! ```
+//! use std::any::Any;
+//! use arrow_array::builder::{ArrayBuilder, Int32Builder, ListBuilder,
StringBuilder};
+//! use arrow_array::{ArrayRef, RecordBatch, StructArray};
+//! use arrow_schema::{DataType, Field};
+//! use std::sync::Arc;
+//! /// A representation of a row
+//! struct Row {
+//! i32: i32,
+//! optional_i32: Option<i32>,
+//! string: Option<String>,
+//! i32_list: Option<Vec<Option<i32>>>,
+//! }
+//!
+//! /// Converts `Vec<Row>` into `StructArray`
+//! #[derive(Debug, Default)]
+//! struct RowBuilder {
+//! i32: Int32Builder,
+//! string: StringBuilder,
+//! i32_list: ListBuilder<Int32Builder>,
+//! }
+//!
+//! impl<'a> Extend<&'a Row> for RowBuilder {
+//! fn extend<T: IntoIterator<Item = &'a Row>>(&mut self, iter: T) {
+//! for row in iter {
+//! self.i32.append_value(row.i32);
+//! self.string.append_option(row.string.as_ref());
+//! match &row.i32_list {
+//! Some(list) => {
+//! list.iter().for_each(|v|
self.i32_list.values().append_option(*v));
+//! self.i32_list.append(true);
+//! }
+//! None => self.i32_list.append(false),
+//! }
Review Comment:
https://github.com/apache/arrow-rs/pull/3954 should simplify this
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
