improvements

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;
 

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<Int32>:
 /// let primitive_array: &Int32Array = as_primitive_array(&arr);
 ///
 /// // Equivalently:
 /// let primitive_array = as_primitive_array::<Int32Type>(&arr);
 ///
-/// // Most verbosely:
+/// // This is the equivalent of:
 /// let primitive_array = arr
 ///     .as_any()
 ///     .downcast_ref::<Int32Array>()
@@ -52,16 +54,16 @@ where
 }
 
 /// Force downcast of an [`Array`], such as an [`ArrayRef`] to
-/// [`DictionaryArray<T>`], panic'ing on failure:
+/// [`DictionaryArray<T>`], panic'ing on failure.
 ///
 /// # Example
 ///
 /// ```
 /// # use arrow::array::*;
 /// # use arrow::datatypes::*;
-/// # let arr: DictionaryArray<Int32Type> = 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<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>
@@ -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<T>`], panic'ing on failure.
 pub fn as_generic_list_array<S: OffsetSizeTrait>(
     arr: &dyn Array,
 ) -> &GenericListArray<S> {
@@ -82,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,
@@ -104,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!(
@@ -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);

arrow/src/array/mod.rs

@@ -44,16 +44,16 @@
 //! }
 //! ```
 //!
-//! 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<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<Int32Type>().values()
+//!     as_primitive_array<Float32Type>().values()
 //! }
 //! ```