alamb commented on code in PR #3951:
URL: https://github.com/apache/arrow-rs/pull/3951#discussion_r1150537954
##########
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
Review Comment:
```suggestion
//! # Converting other objects to Arrow Arrays
```
I was confused at first about the term "Row" as it is over loaded. What do
you think about talking about "objects" instead?
##########
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
Review Comment:
```suggestion
//! It is common to have a collection of objects that you want to
//! convert to Arrow arrays. An example of doing so is below
```
##########
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
Review Comment:
```suggestion
//! /// A representation of a row (defined in code elsewhere)
```
##########
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 {
Review Comment:
I know "extend" is probably more idomatic, but I think it obscures the key
use of the builders
I suggest refactoring just the "append one row" code into its own function
for clarity
```rust
impl RowBuilder {
pub fn append_row(&mut self, row: &Row) {
...
}
}
```
##########
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 {
Review Comment:
Maybe it could be called "MyRow" to emphasize it is defined in user code
##########
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),
+//! }
+//! }
+//! }
+//! }
+//!
+//! impl RowBuilder {
+//! /// Note: returns StructArray to allow nesting within another array if
desired
Review Comment:
Maybe it is also worth mentioning (or adding a function that does so) that
it could return a 4 column RecordBatch as well
--
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]
