From c6f23c29c8c1a4cf69db6c1cf5bfd4a2b2c00797 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 15 Jul 2022 17:45:49 -0400 Subject: [PATCH 1/6] Improve doc strings for as_primtive_array --- arrow/src/array/cast.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/arrow/src/array/cast.rs b/arrow/src/array/cast.rs index dd6c7135710..7a5b386b8b3 100644 --- a/arrow/src/array/cast.rs +++ b/arrow/src/array/cast.rs @@ -20,7 +20,19 @@ use crate::array::*; use crate::datatypes::*; -/// Force downcast ArrayRef to PrimitiveArray +/// Force downcast of an [`Array`], such as an [`ArrayRef`], to +/// [`PrimitiveArray`], panic'ing on failure: +/// +/// ``` +/// # use arrow::array::*; +/// # use arrow::datatypes::*; +/// # let arr: ArrayRef = std::sync::Arc::new(Int32Array::from(vec![Some(1)])); +/// // Downcast an `ArrayRef` to Int32Array / PrimiveArray: +/// let primitive_array: &Int32Array = as_primitive_array(&arr); +/// +/// // Equivalently: +/// let primitive_array = as_primitive_array::(&arr); +/// ``` pub fn as_primitive_array(arr: &dyn Array) -> &PrimitiveArray where T: ArrowPrimitiveType, From 49f4c863615c6c362a015151a99cf78cab0d88ad Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 20 Jul 2022 15:46:48 -0400 Subject: [PATCH 2/6] Add more docs for cast --- arrow/src/array/cast.rs | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/arrow/src/array/cast.rs b/arrow/src/array/cast.rs index 7a5b386b8b3..4c7e2ea4316 100644 --- a/arrow/src/array/cast.rs +++ b/arrow/src/array/cast.rs @@ -31,7 +31,13 @@ use crate::datatypes::*; /// let primitive_array: &Int32Array = as_primitive_array(&arr); /// /// // Equivalently: -/// let primitive_array = as_primitive_array::(&arr); +/// let primitive_array = as_primitive_array::(&arr); +/// +/// // Most verbosely: +/// let primitive_array = arr +/// .as_any() +/// .downcast_ref::() +/// .unwrap(); /// ``` pub fn as_primitive_array(arr: &dyn Array) -> &PrimitiveArray where @@ -42,7 +48,17 @@ where .expect("Unable to downcast to primitive array") } -/// Force downcast ArrayRef to DictionaryArray +/// Force downcast of an [`Array`], such as an [`ArrayRef`] to +/// [`DictionaryArray`], panic'ing on failure: +/// +/// ``` +/// # use arrow::array::*; +/// # use arrow::datatypes::*; +/// # let arr: DictionaryArray = vec![Some("foo")].into_iter().collect(); +/// # let arr: ArrayRef = std::sync::Arc::new(arr); +/// // Downcast an `ArrayRef` to DictionaryArray with Int32 keys: +/// let dict_array: &DictionaryArray = as_dictionary_array::(&arr); +/// ``` pub fn as_dictionary_array(arr: &dyn Array) -> &DictionaryArray where T: ArrowDictionaryKeyType, From 9a3fb2f3a3c1250e1c031bbdbaa962318ba8f23d Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 20 Jul 2022 16:38:38 -0400 Subject: [PATCH 3/6] improvements --- arrow/src/array/array.rs | 1 + arrow/src/array/cast.rs | 9 +++++++-- arrow/src/array/mod.rs | 21 ++++++++++++++++++--- 3 files changed, 26 insertions(+), 5 deletions(-) diff --git a/arrow/src/array/array.rs b/arrow/src/array/array.rs index d29cf839d9e..1ccb2809cdc 100644 --- a/arrow/src/array/array.rs +++ b/arrow/src/array/array.rs @@ -54,6 +54,7 @@ pub trait Array: fmt::Debug + Send + Sync + JsonEqual { /// .expect("Failed to downcast"); /// # Ok(()) /// # } + /// /// ``` fn as_any(&self) -> &dyn Any; diff --git a/arrow/src/array/cast.rs b/arrow/src/array/cast.rs index 4c7e2ea4316..61346e343a8 100644 --- a/arrow/src/array/cast.rs +++ b/arrow/src/array/cast.rs @@ -15,13 +15,15 @@ // specific language governing permissions and limitations // under the License. -//! Defines helper functions for force Array type downcast +//! Defines helper functions for force [`Array`] downcasts use crate::array::*; use crate::datatypes::*; /// Force downcast of an [`Array`], such as an [`ArrayRef`], to -/// [`PrimitiveArray`], panic'ing on failure: +/// [`PrimitiveArray`], panic'ing on failure. +/// +/// # Example /// /// ``` /// # use arrow::array::*; @@ -39,6 +41,7 @@ use crate::datatypes::*; /// .downcast_ref::() /// .unwrap(); /// ``` + pub fn as_primitive_array(arr: &dyn Array) -> &PrimitiveArray where T: ArrowPrimitiveType, @@ -51,6 +54,8 @@ where /// Force downcast of an [`Array`], such as an [`ArrayRef`] to /// [`DictionaryArray`], panic'ing on failure: /// +/// # Example +/// /// ``` /// # use arrow::array::*; /// # use arrow::datatypes::*; diff --git a/arrow/src/array/mod.rs b/arrow/src/array/mod.rs index e533f9e75d5..815f098ddf0 100644 --- a/arrow/src/array/mod.rs +++ b/arrow/src/array/mod.rs @@ -24,9 +24,11 @@ //! Arrays are often passed around as a dynamically typed [`&dyn Array`] or [`ArrayRef`]. //! For example, [`RecordBatch`](`crate::record_batch::RecordBatch`) stores columns as [`ArrayRef`]. //! -//! Whilst these arrays can be passed directly to the [`compute`](crate::compute), -//! [`csv`](crate::csv), [`json`](crate::json), etc... APIs, it is often the case that you wish -//! to interact with the data directly. This requires downcasting to the concrete type of the array: +//! Whilst these arrays can be passed directly to the +//! [`compute`](crate::compute), [`csv`](crate::csv), +//! [`json`](crate::json), etc... APIs, it is often the case that you +//! wish to interact with the data directly. This requires downcasting +//! to the concrete type of the array: //! //! ``` //! # use arrow::array::{Array, Float32Array, Int32Array}; @@ -42,6 +44,19 @@ //! } //! ``` //! +//! There are convient functions to do this casting for you such as +//! [`as_primtive_array`] and [`as_string_array`]: +//! +//! ``` +//! # use arrow::array::*; +//! # use arrow::datatypes::*; +//! # +//! fn as_f32_slice(array: &dyn Array) -> &[f32] { +//! // use as_primtive_array +//! as_primitive_array().values() +//! } +//! ``` + //! # Building an Array //! //! Most [`Array`] implementations can be constructed directly from iterators or [`Vec`] From 94c2007485ffb3d8084066cc567a05dc5bd07fb7 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 21 Jul 2022 07:37:53 -0400 Subject: [PATCH 4/6] improvements --- arrow/src/array/array.rs | 1 - arrow/src/array/cast.rs | 70 ++++++++++++++++++++++++++++++++-------- arrow/src/array/mod.rs | 6 ++-- 3 files changed, 59 insertions(+), 18 deletions(-) diff --git a/arrow/src/array/array.rs b/arrow/src/array/array.rs index 1ccb2809cdc..d29cf839d9e 100644 --- a/arrow/src/array/array.rs +++ b/arrow/src/array/array.rs @@ -54,7 +54,6 @@ pub trait Array: fmt::Debug + Send + Sync + JsonEqual { /// .expect("Failed to downcast"); /// # Ok(()) /// # } - /// /// ``` fn as_any(&self) -> &dyn Any; diff --git a/arrow/src/array/cast.rs b/arrow/src/array/cast.rs index 61346e343a8..fd57133bc84 100644 --- a/arrow/src/array/cast.rs +++ b/arrow/src/array/cast.rs @@ -28,14 +28,16 @@ use crate::datatypes::*; /// ``` /// # use arrow::array::*; /// # use arrow::datatypes::*; -/// # let arr: ArrayRef = std::sync::Arc::new(Int32Array::from(vec![Some(1)])); +/// # use std::sync::Arc; +/// let arr: ArrayRef = Arc::new(Int32Array::from(vec![Some(1)])); +/// /// // Downcast an `ArrayRef` to Int32Array / PrimiveArray: /// let primitive_array: &Int32Array = as_primitive_array(&arr); /// /// // Equivalently: /// let primitive_array = as_primitive_array::(&arr); /// -/// // Most verbosely: +/// // This is the equivalent of: /// let primitive_array = arr /// .as_any() /// .downcast_ref::() @@ -52,16 +54,16 @@ where } /// Force downcast of an [`Array`], such as an [`ArrayRef`] to -/// [`DictionaryArray`], panic'ing on failure: +/// [`DictionaryArray`], panic'ing on failure. /// /// # Example /// /// ``` /// # use arrow::array::*; /// # use arrow::datatypes::*; -/// # let arr: DictionaryArray = vec![Some("foo")].into_iter().collect(); -/// # let arr: ArrayRef = std::sync::Arc::new(arr); -/// // Downcast an `ArrayRef` to DictionaryArray with Int32 keys: +/// # use std::sync::Arc; +/// let arr: DictionaryArray = vec![Some("foo")].into_iter().collect(); +/// let arr: ArrayRef = std::sync::Arc::new(arr); /// let dict_array: &DictionaryArray = as_dictionary_array::(&arr); /// ``` pub fn as_dictionary_array(arr: &dyn Array) -> &DictionaryArray @@ -73,7 +75,8 @@ where .expect("Unable to downcast to dictionary array") } -#[doc = "Force downcast ArrayRef to GenericListArray"] +/// Force downcast of an [`Array`], such as an [`ArrayRef`] to +/// [`GenericListArray`], panic'ing on failure. pub fn as_generic_list_array( arr: &dyn Array, ) -> &GenericListArray { @@ -82,19 +85,22 @@ pub fn as_generic_list_array( .expect("Unable to downcast to list array") } -#[doc = "Force downcast ArrayRef to ListArray"] +/// Force downcast of an [`Array`], such as an [`ArrayRef`] to +/// [`ListArray`], panic'ing on failure. #[inline] pub fn as_list_array(arr: &dyn Array) -> &ListArray { as_generic_list_array::(arr) } -#[doc = "Force downcast ArrayRef to LargeListArray"] +/// Force downcast of an [`Array`], such as an [`ArrayRef`] to +/// [`LargeListArray`], panic'ing on failure. #[inline] pub fn as_large_list_array(arr: &dyn Array) -> &LargeListArray { as_generic_list_array::(arr) } -#[doc = "Force downcast ArrayRef to GenericBinaryArray"] +/// Force downcast of an [`Array`], such as an [`ArrayRef`] to +/// [`GenericBinaryArray`], panic'ing on failure. #[inline] pub fn as_generic_binary_array( arr: &dyn Array, @@ -104,9 +110,43 @@ pub fn as_generic_binary_array( .expect("Unable to downcast to binary array") } +/// Force downcast of an [`Array`], such as an [`ArrayRef`] to +/// [`StringArray`], panic'ing on failure. +/// +/// # Example +/// +/// ``` +/// # use arrow::array::*; +/// # use std::sync::Arc; +/// let arr: ArrayRef = Arc::new(StringArray::from_iter(vec![Some("foo")])); +/// let string_array = as_string_array(&arr); +/// ``` +pub fn as_string_array(arr: &dyn Array) -> &StringArray { + arr.as_any() + .downcast_ref::() + .expect("Unable to downcast to StringArray") +} + +/// Force downcast of an [`Array`], such as an [`ArrayRef`] to +/// [`BooleanArray`], panic'ing on failure. +/// +/// # Example +/// +/// ``` +/// # use arrow::array::*; +/// # use std::sync::Arc; +/// let arr: ArrayRef = Arc::new(BooleanArray::from_iter(vec![Some(true)])); +/// let boolean_array = as_boolean_array(&arr); +/// ``` +pub fn as_boolean_array(arr: &dyn Array) -> &BooleanArray { + arr.as_any() + .downcast_ref::() + .expect("Unable to downcast to BooleanArray") +} + macro_rules! array_downcast_fn { ($name: ident, $arrty: ty, $arrty_str:expr) => { - #[doc = "Force downcast ArrayRef to "] + #[doc = "Force downcast of an [`Array`], such as an [`ArrayRef`] to "] #[doc = $arrty_str] pub fn $name(arr: &dyn Array) -> &$arrty { arr.as_any().downcast_ref::<$arrty>().expect(concat!( @@ -118,13 +158,15 @@ macro_rules! array_downcast_fn { // use recursive macro to generate dynamic doc string for a given array type ($name: ident, $arrty: ty) => { - array_downcast_fn!($name, $arrty, stringify!($arrty)); + array_downcast_fn!( + $name, + $arrty, + concat!("[`", stringify!($arrty), "`], panic'ing on failure.") + ); }; } -array_downcast_fn!(as_string_array, StringArray); array_downcast_fn!(as_largestring_array, LargeStringArray); -array_downcast_fn!(as_boolean_array, BooleanArray); array_downcast_fn!(as_null_array, NullArray); array_downcast_fn!(as_struct_array, StructArray); array_downcast_fn!(as_union_array, UnionArray); diff --git a/arrow/src/array/mod.rs b/arrow/src/array/mod.rs index 815f098ddf0..9b88fb92e0f 100644 --- a/arrow/src/array/mod.rs +++ b/arrow/src/array/mod.rs @@ -44,8 +44,8 @@ //! } //! ``` //! -//! There are convient functions to do this casting for you such as -//! [`as_primtive_array`] and [`as_string_array`]: +//! Additionally, there are convenient functions to do this casting +//! such as [`as_primitive_array`] and [`as_string_array`]: //! //! ``` //! # use arrow::array::*; @@ -53,7 +53,7 @@ //! # //! fn as_f32_slice(array: &dyn Array) -> &[f32] { //! // use as_primtive_array -//! as_primitive_array().values() +//! as_primitive_array().values() //! } //! ``` From 56a2f2974fe3c00dcfae0b2911d15934f162228e Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 21 Jul 2022 14:56:38 -0400 Subject: [PATCH 5/6] Update arrow/src/array/mod.rs Co-authored-by: Liang-Chi Hsieh --- arrow/src/array/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow/src/array/mod.rs b/arrow/src/array/mod.rs index 9b88fb92e0f..c800107667f 100644 --- a/arrow/src/array/mod.rs +++ b/arrow/src/array/mod.rs @@ -53,7 +53,7 @@ //! # //! fn as_f32_slice(array: &dyn Array) -> &[f32] { //! // use as_primtive_array -//! as_primitive_array().values() +//! as_primitive_array::().values() //! } //! ``` From 2af1be2bb9065857d45b84329a6cfc7fe3f7c48e Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Thu, 21 Jul 2022 15:04:42 -0400 Subject: [PATCH 6/6] fixups --- arrow/src/array/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow/src/array/mod.rs b/arrow/src/array/mod.rs index 9b88fb92e0f..d805710ccf5 100644 --- a/arrow/src/array/mod.rs +++ b/arrow/src/array/mod.rs @@ -53,7 +53,7 @@ //! # //! fn as_f32_slice(array: &dyn Array) -> &[f32] { //! // use as_primtive_array -//! as_primitive_array().values() +//! as_primitive_array::(array).values() //! } //! ```