From 3325a87f0f0e24368e7f6a94e791596c3f25e0ab Mon Sep 17 00:00:00 2001 From: Navin Keswani Date: Sun, 25 Jul 2021 17:16:42 +1000 Subject: [PATCH 1/2] Doctests for UnionBuilder and UnionArray. --- arrow/src/array/array_union.rs | 69 ++++++---------------------------- arrow/src/array/builder.rs | 41 ++++++++++++++++++++ 2 files changed, 52 insertions(+), 58 deletions(-) diff --git a/arrow/src/array/array_union.rs b/arrow/src/array/array_union.rs index e369037244ac..924784ba1474 100644 --- a/arrow/src/array/array_union.rs +++ b/arrow/src/array/array_union.rs @@ -15,64 +15,8 @@ // specific language governing permissions and limitations // under the License. -//! Contains the `UnionArray` type. -//! -//! Each slot in a `UnionArray` can have a value chosen from a number of types. Each of the -//! possible types are named like the fields of a [`StructArray`](crate::array::StructArray). -//! A `UnionArray` can have two possible memory layouts, "dense" or "sparse". For more information -//! on please see the [specification](https://arrow.apache.org/docs/format/Columnar.html#union-layout). -//! -//! Builders are provided for `UnionArray`'s involving primitive types. `UnionArray`'s of nested -//! types are also supported but not via `UnionBuilder`, see the tests for examples. -//! -//! # Example: Dense Memory Layout -//! -//! ``` -//! use arrow::array::UnionBuilder; -//! use arrow::datatypes::{Float64Type, Int32Type}; -//! -//! # fn main() -> arrow::error::Result<()> { -//! let mut builder = UnionBuilder::new_dense(3); -//! builder.append::("a", 1).unwrap(); -//! builder.append::("b", 3.0).unwrap(); -//! builder.append::("a", 4).unwrap(); -//! let union = builder.build().unwrap(); -//! -//! assert_eq!(union.type_id(0), 0_i8); -//! assert_eq!(union.type_id(1), 1_i8); -//! assert_eq!(union.type_id(2), 0_i8); -//! -//! assert_eq!(union.value_offset(0), 0_i32); -//! assert_eq!(union.value_offset(1), 0_i32); -//! assert_eq!(union.value_offset(2), 1_i32); -//! -//! # Ok(()) -//! # } -//! ``` -//! -//! # Example: Sparse Memory Layout -//! ``` -//! use arrow::array::UnionBuilder; -//! use arrow::datatypes::{Float64Type, Int32Type}; -//! -//! # fn main() -> arrow::error::Result<()> { -//! let mut builder = UnionBuilder::new_sparse(3); -//! builder.append::("a", 1).unwrap(); -//! builder.append::("b", 3.0).unwrap(); -//! builder.append::("a", 4).unwrap(); -//! let union = builder.build().unwrap(); -//! -//! assert_eq!(union.type_id(0), 0_i8); -//! assert_eq!(union.type_id(1), 1_i8); -//! assert_eq!(union.type_id(2), 0_i8); -//! -//! assert_eq!(union.value_offset(0), 0_i32); -//! assert_eq!(union.value_offset(1), 1_i32); -//! assert_eq!(union.value_offset(2), 2_i32); -//! -//! # Ok(()) -//! # } -//! ``` +/// Contains the `UnionArray` type. +/// use crate::array::{data::count_nulls, make_array, Array, ArrayData, ArrayRef}; use crate::buffer::Buffer; use crate::datatypes::*; @@ -83,6 +27,15 @@ use std::any::Any; use std::mem::size_of; /// An Array that can represent slots of varying types. +/// +/// Each slot in a `UnionArray` can have a value chosen from a number of types. Each of the +/// possible types are named like the fields of a [`StructArray`](crate::array::StructArray). +/// A `UnionArray` can have two possible memory layouts, "dense" or "sparse". For more information +/// on please see the [specification](https://arrow.apache.org/docs/format/Columnar.html#union-layout). +/// +/// Builders are provided for `UnionArray`'s involving primitive types. `UnionArray`'s of nested +/// types are also supported but not via `UnionBuilder`, see the tests for examples. +/// pub struct UnionArray { data: ArrayData, boxed_fields: Vec, diff --git a/arrow/src/array/builder.rs b/arrow/src/array/builder.rs index 66f2d818f728..54a4dac72672 100644 --- a/arrow/src/array/builder.rs +++ b/arrow/src/array/builder.rs @@ -1696,6 +1696,47 @@ impl FieldData { } /// Builder type for creating a new `UnionArray`. +/// +/// Example: **Dense Memory Layout** +/// +/// ``` +/// use arrow::array::UnionBuilder; +/// use arrow::datatypes::{Float64Type, Int32Type}; +/// +/// let mut builder = UnionBuilder::new_dense(3); +/// builder.append::("a", 1).unwrap(); +/// builder.append::("b", 3.0).unwrap(); +/// builder.append::("a", 4).unwrap(); +/// let union = builder.build().unwrap(); +/// +/// assert_eq!(union.type_id(0), 0_i8); +/// assert_eq!(union.type_id(1), 1_i8); +/// assert_eq!(union.type_id(2), 0_i8); +/// +/// assert_eq!(union.value_offset(0), 0_i32); +/// assert_eq!(union.value_offset(1), 0_i32); +/// assert_eq!(union.value_offset(2), 1_i32); +/// ``` +/// +/// Example: **Sparse Memory Layout** +/// ``` +/// use arrow::array::UnionBuilder; +/// use arrow::datatypes::{Float64Type, Int32Type}; +/// +/// let mut builder = UnionBuilder::new_sparse(3); +/// builder.append::("a", 1).unwrap(); +/// builder.append::("b", 3.0).unwrap(); +/// builder.append::("a", 4).unwrap(); +/// let union = builder.build().unwrap(); +/// +/// assert_eq!(union.type_id(0), 0_i8); +/// assert_eq!(union.type_id(1), 1_i8); +/// assert_eq!(union.type_id(2), 0_i8); +/// +/// assert_eq!(union.value_offset(0), 0_i32); +/// assert_eq!(union.value_offset(1), 1_i32); +/// assert_eq!(union.value_offset(2), 2_i32); +/// ``` #[derive(Debug)] pub struct UnionBuilder { /// The current number of slots in the array From 1d49007aa491aad7c4cba4efbadaa525ca00a63e Mon Sep 17 00:00:00 2001 From: Navin Date: Sun, 25 Jul 2021 22:35:29 +1000 Subject: [PATCH 2/2] Update arrow/src/array/array_union.rs Co-authored-by: Andrew Lamb --- arrow/src/array/array_union.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow/src/array/array_union.rs b/arrow/src/array/array_union.rs index 924784ba1474..2cc13c201ed3 100644 --- a/arrow/src/array/array_union.rs +++ b/arrow/src/array/array_union.rs @@ -33,7 +33,7 @@ use std::mem::size_of; /// A `UnionArray` can have two possible memory layouts, "dense" or "sparse". For more information /// on please see the [specification](https://arrow.apache.org/docs/format/Columnar.html#union-layout). /// -/// Builders are provided for `UnionArray`'s involving primitive types. `UnionArray`'s of nested +/// [`UnionBuilder`]can be used to create `UnionArray`'s of primitive types. `UnionArray`'s of nested /// types are also supported but not via `UnionBuilder`, see the tests for examples. /// pub struct UnionArray {