You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by tu...@apache.org on 2022/07/21 22:00:19 UTC
[arrow-rs] branch master updated: Improve docstrings + examples for `as_primitive_array` cast functions (#2114)
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 f62f26a23 Improve docstrings + examples for `as_primitive_array` cast functions (#2114)
f62f26a23 is described below
commit f62f26a23540d55356601b7df0730f4f0f2ae5fc
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Thu Jul 21 18:00:14 2022 -0400
Improve docstrings + examples for `as_primitive_array` cast functions (#2114)
* Improve doc strings for as_primtive_array
* Add more docs for cast
* improvements
* improvements
* Update arrow/src/array/mod.rs
Co-authored-by: Liang-Chi Hsieh <vi...@gmail.com>
* fixups
Co-authored-by: Liang-Chi Hsieh <vi...@gmail.com>
---
arrow/src/array/cast.rs | 97 +++++++++++++++++++++++++++++++++++++++++++------
arrow/src/array/mod.rs | 21 +++++++++--
2 files changed, 104 insertions(+), 14 deletions(-)
diff --git a/arrow/src/array/cast.rs b/arrow/src/array/cast.rs
index dd6c71357..fd57133bc 100644
--- a/arrow/src/array/cast.rs
+++ b/arrow/src/array/cast.rs
@@ -15,12 +15,35 @@
// 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 ArrayRef to PrimitiveArray<T>
+/// Force downcast of an [`Array`], such as an [`ArrayRef`], to
+/// [`PrimitiveArray<T>`], panic'ing on failure.
+///
+/// # Example
+///
+/// ```
+/// # use arrow::array::*;
+/// # use arrow::datatypes::*;
+/// # use std::sync::Arc;
+/// let arr: ArrayRef = Arc::new(Int32Array::from(vec![Some(1)]));
+///
+/// // Downcast an `ArrayRef` to Int32Array / PrimiveArray<Int32>:
+/// let primitive_array: &Int32Array = as_primitive_array(&arr);
+///
+/// // Equivalently:
+/// let primitive_array = as_primitive_array::<Int32Type>(&arr);
+///
+/// // This is the equivalent of:
+/// let primitive_array = arr
+/// .as_any()
+/// .downcast_ref::<Int32Array>()
+/// .unwrap();
+/// ```
+
pub fn as_primitive_array<T>(arr: &dyn Array) -> &PrimitiveArray<T>
where
T: ArrowPrimitiveType,
@@ -30,7 +53,19 @@ where
.expect("Unable to downcast to primitive array")
}
-/// Force downcast ArrayRef to DictionaryArray<T>
+/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
+/// [`DictionaryArray<T>`], panic'ing on failure.
+///
+/// # Example
+///
+/// ```
+/// # use arrow::array::*;
+/// # use arrow::datatypes::*;
+/// # use std::sync::Arc;
+/// let arr: DictionaryArray<Int32Type> = vec![Some("foo")].into_iter().collect();
+/// let arr: ArrayRef = std::sync::Arc::new(arr);
+/// let dict_array: &DictionaryArray<Int32Type> = as_dictionary_array::<Int32Type>(&arr);
+/// ```
pub fn as_dictionary_array<T>(arr: &dyn Array) -> &DictionaryArray<T>
where
T: ArrowDictionaryKeyType,
@@ -40,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<T>`], panic'ing on failure.
pub fn as_generic_list_array<S: OffsetSizeTrait>(
arr: &dyn Array,
) -> &GenericListArray<S> {
@@ -49,19 +85,22 @@ pub fn as_generic_list_array<S: OffsetSizeTrait>(
.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::<i32>(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::<i64>(arr)
}
-#[doc = "Force downcast ArrayRef to GenericBinaryArray"]
+/// Force downcast of an [`Array`], such as an [`ArrayRef`] to
+/// [`GenericBinaryArray<S>`], panic'ing on failure.
#[inline]
pub fn as_generic_binary_array<S: OffsetSizeTrait>(
arr: &dyn Array,
@@ -71,9 +110,43 @@ pub fn as_generic_binary_array<S: OffsetSizeTrait>(
.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::<StringArray>()
+ .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::<BooleanArray>()
+ .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!(
@@ -85,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 e533f9e75..d805710cc 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 @@
//! }
//! ```
//!
+//! Additionally, there are convenient functions to do this casting
+//! such as [`as_primitive_array<T>`] 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::<Float32Type>(array).values()
+//! }
+//! ```
+
//! # Building an Array
//!
//! Most [`Array`] implementations can be constructed directly from iterators or [`Vec`]