Documentation Improvements

arrow-array/src/array/binary_array.rs

@@ -23,7 +23,7 @@ use arrow_buffer::{bit_util, Buffer, MutableBuffer};
 use arrow_data::ArrayData;
 use arrow_schema::DataType;
 
-/// See [`BinaryArray`] and [`LargeBinaryArray`] for storing binary data
+/// A [`GenericBinaryArray`] for storing `[u8]`
 pub type GenericBinaryArray<OffsetSize> = GenericByteArray<GenericBinaryType<OffsetSize>>;
 
 impl<OffsetSize: OffsetSizeTrait> GenericBinaryArray<OffsetSize> {
@@ -217,7 +217,7 @@ where
     }
 }
 
-/// An array of `[u8]` using `i32` offsets
+/// A [`GenericBinaryArray`] of `[u8]` using `i32` offsets
 ///
 /// The byte length of each element is represented by an i32.
 ///
@@ -256,9 +256,10 @@ where
 /// assert!(!array.is_null(4));
 /// ```
 ///
+/// See [`GenericByteArray`] for more information and examples
 pub type BinaryArray = GenericBinaryArray<i32>;
 
-/// An array of `[u8]` using `i64` offsets
+/// A [`GenericBinaryArray`] of `[u8]` using `i64` offsets
 ///
 /// # Examples
 ///
@@ -295,6 +296,7 @@ pub type BinaryArray = GenericBinaryArray<i32>;
 /// assert!(!array.is_null(4));
 /// ```
 ///
+/// See [`GenericByteArray`] for more information and examples
 pub type LargeBinaryArray = GenericBinaryArray<i64>;
 
 #[cfg(test)]

arrow-array/src/array/boolean_array.rs

@@ -27,51 +27,43 @@ use std::sync::Arc;
 
 /// An array of [boolean values](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
 ///
-/// # Examples
+/// # Example: From a Vec
 ///
-/// Construction
+/// ```
+/// # use arrow_array::{Array, BooleanArray};
+/// let arr: BooleanArray = vec![true, true, false].into();
+/// ```
+///
+/// # Example: From an optional Vec
 ///
 /// ```
-///#     use arrow_array::{Array, BooleanArray};
-/// // Create from Vec<Option<bool>>
-/// let arr = BooleanArray::from(vec![Some(false), Some(true), None, Some(true)]);
-/// // Create from Vec<bool>
-/// let arr = BooleanArray::from(vec![false, true, true]);
-/// // Create from iter/collect
-/// let arr: BooleanArray = std::iter::repeat(Some(true)).take(10).collect();
+/// # use arrow_array::{Array, BooleanArray};
+/// let arr: BooleanArray = vec![Some(true), None, Some(false)].into();
 /// ```
 ///
-/// Construction and Access
+/// # Example: From an iterator
 ///
 /// ```
-/// use arrow_array::{Array, BooleanArray};
-/// let arr = BooleanArray::from(vec![Some(false), Some(true), None, Some(true)]);
-/// assert_eq!(4, arr.len());
-/// assert_eq!(1, arr.null_count());
-/// assert!(arr.is_valid(0));
-/// assert!(!arr.is_null(0));
-/// assert_eq!(false, arr.value(0));
-/// assert!(!arr.is_valid(2));
-/// assert!(arr.is_null(2));
+/// # use arrow_array::{Array, BooleanArray};
+/// let arr: BooleanArray = (0..5).map(|x| (x % 2 == 0).then(|| x % 3 == 0)).collect();
+/// let values: Vec<_> = arr.iter().collect();
+/// assert_eq!(&values, &[Some(true), None, Some(false), None, Some(false)])
 /// ```
 ///
-/// Using `collect`
+/// # Example: Using Builder
+///
 /// ```
-/// use arrow_array::{Array, BooleanArray};
-/// let v = vec![Some(false), Some(true), Some(false), Some(true)];
-/// let arr = v.into_iter().collect::<BooleanArray>();
-/// assert_eq!(4, arr.len());
-/// assert_eq!(0, arr.offset());
-/// assert_eq!(0, arr.null_count());
-/// assert!(arr.is_valid(0));
-/// assert_eq!(false, arr.value(0));
-/// assert!(arr.is_valid(1));
-/// assert_eq!(true, arr.value(1));
-/// assert!(arr.is_valid(2));
-/// assert_eq!(false, arr.value(2));
-/// assert!(arr.is_valid(3));
-/// assert_eq!(true, arr.value(3));
+/// # use arrow_array::Array;
+/// # use arrow_array::builder::BooleanBuilder;
+/// let mut builder = BooleanBuilder::new();
+/// builder.append_value(true);
+/// builder.append_null();
+/// builder.append_value(false);
+/// let array = builder.finish();
+/// let values: Vec<_> = array.iter().collect();
+/// assert_eq!(&values, &[Some(true), None, Some(false)])
 /// ```
+///
 #[derive(Clone)]
 pub struct BooleanArray {
     values: BooleanBuffer,

arrow-array/src/array/byte_array.rs

@@ -34,6 +34,52 @@ use std::sync::Arc;
 ///
 /// See [`BinaryArray`] and [`LargeBinaryArray`] for storing arbitrary bytes
 ///
+/// # Example: From a Vec
+///
+/// ```
+/// # use arrow_array::{Array, GenericByteArray, types::Utf8Type};
+/// let arr: GenericByteArray<Utf8Type> = vec!["hello", "world", ""].into();
+/// assert_eq!(arr.value_data(), b"helloworld");
+/// assert_eq!(arr.value_offsets(), &[0, 5, 10, 10]);
+/// let values: Vec<_> = arr.iter().collect();
+/// assert_eq!(values, &[Some("hello"), Some("world"), Some("")]);
+/// ```
+///
+/// # Example: From an optional Vec
+///
+/// ```
+/// # use arrow_array::{Array, GenericByteArray, types::Utf8Type};
+/// let arr: GenericByteArray<Utf8Type> = vec![Some("hello"), Some("world"), Some(""), None].into();
+/// assert_eq!(arr.value_data(), b"helloworld");
+/// assert_eq!(arr.value_offsets(), &[0, 5, 10, 10, 10]);
+/// let values: Vec<_> = arr.iter().collect();
+/// assert_eq!(values, &[Some("hello"), Some("world"), Some(""), None]);
+/// ```
+///
+/// # Example: From an iterator of option
+///
+/// ```
+/// # use arrow_array::{Array, GenericByteArray, types::Utf8Type};
+/// let arr: GenericByteArray<Utf8Type> = (0..5).map(|x| (x % 2 == 0).then(|| x.to_string())).collect();
+/// let values: Vec<_> = arr.iter().collect();
+/// assert_eq!(values, &[Some("0"), None, Some("2"), None, Some("4")]);
+/// ```
+///
+/// # Example: Using Builder
+///
+/// ```
+/// # use arrow_array::Array;
+/// # use arrow_array::builder::GenericByteBuilder;
+/// # use arrow_array::types::Utf8Type;
+/// let mut builder = GenericByteBuilder::<Utf8Type>::new();
+/// builder.append_value("hello");
+/// builder.append_null();
+/// builder.append_value("world");
+/// let array = builder.finish();
+/// let values: Vec<_> = array.iter().collect();
+/// assert_eq!(values, &[Some("hello"), None, Some("world")]);
+/// ```
+///
 /// [`StringArray`]: crate::StringArray
 /// [`LargeStringArray`]: crate::LargeStringArray
 /// [`BinaryArray`]: crate::BinaryArray

arrow-array/src/array/dictionary_array.rs

@@ -30,7 +30,7 @@ use arrow_schema::{ArrowError, DataType};
 use std::any::Any;
 use std::sync::Arc;
 
-/// A dictionary array indexed by `i8`
+/// A [`DictionaryArray`] indexed by `i8`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -42,9 +42,11 @@ use std::sync::Arc;
 /// assert_eq!(array.keys(), &Int8Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type Int8DictionaryArray = DictionaryArray<Int8Type>;
 
-/// A dictionary array indexed by `i16`
+/// A [`DictionaryArray`] indexed by `i16`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -56,9 +58,11 @@ pub type Int8DictionaryArray = DictionaryArray<Int8Type>;
 /// assert_eq!(array.keys(), &Int16Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type Int16DictionaryArray = DictionaryArray<Int16Type>;
 
-/// A dictionary array indexed by `i32`
+/// A [`DictionaryArray`] indexed by `i32`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -70,9 +74,11 @@ pub type Int16DictionaryArray = DictionaryArray<Int16Type>;
 /// assert_eq!(array.keys(), &Int32Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type Int32DictionaryArray = DictionaryArray<Int32Type>;
 
-/// A dictionary array indexed by `i64`
+/// A [`DictionaryArray`] indexed by `i64`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -84,9 +90,11 @@ pub type Int32DictionaryArray = DictionaryArray<Int32Type>;
 /// assert_eq!(array.keys(), &Int64Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type Int64DictionaryArray = DictionaryArray<Int64Type>;
 
-/// A dictionary array indexed by `u8`
+/// A [`DictionaryArray`] indexed by `u8`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -98,9 +106,11 @@ pub type Int64DictionaryArray = DictionaryArray<Int64Type>;
 /// assert_eq!(array.keys(), &UInt8Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type UInt8DictionaryArray = DictionaryArray<UInt8Type>;
 
-/// A dictionary array indexed by `u16`
+/// A [`DictionaryArray`] indexed by `u16`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -112,9 +122,11 @@ pub type UInt8DictionaryArray = DictionaryArray<UInt8Type>;
 /// assert_eq!(array.keys(), &UInt16Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type UInt16DictionaryArray = DictionaryArray<UInt16Type>;
 
-/// A dictionary array indexed by `u32`
+/// A [`DictionaryArray`] indexed by `u32`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -126,9 +138,11 @@ pub type UInt16DictionaryArray = DictionaryArray<UInt16Type>;
 /// assert_eq!(array.keys(), &UInt32Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type UInt32DictionaryArray = DictionaryArray<UInt32Type>;
 
-/// A dictionary array indexed by `u64`
+/// A [`DictionaryArray`] indexed by `u64`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -140,6 +154,8 @@ pub type UInt32DictionaryArray = DictionaryArray<UInt32Type>;
 /// assert_eq!(array.keys(), &UInt64Array::from(vec![0, 0, 1, 2]));
 /// assert_eq!(array.values(), &values);
 /// ```
+///
+/// See [`DictionaryArray`] for more information and examples
 pub type UInt64DictionaryArray = DictionaryArray<UInt64Type>;
 
 /// An array of [dictionary encoded values](https://arrow.apache.org/docs/format/Columnar.html#dictionary-encoded-layout)
@@ -175,39 +191,54 @@ pub type UInt64DictionaryArray = DictionaryArray<UInt64Type>;
 ///              length = 6
 /// ```
 ///
-/// Example **with nullable** data:
+/// # Example: From Nullable Data
 ///
 /// ```
-/// use arrow_array::{DictionaryArray, Int8Array, types::Int8Type};
+/// # use arrow_array::{DictionaryArray, Int8Array, types::Int8Type};
 /// let test = vec!["a", "a", "b", "c"];
 /// let array : DictionaryArray<Int8Type> = test.iter().map(|&x| if x == "b" {None} else {Some(x)}).collect();
 /// assert_eq!(array.keys(), &Int8Array::from(vec![Some(0), Some(0), None, Some(1)]));
 /// ```
 ///
-/// Example **without nullable** data:
+/// # Example: From Non-Nullable Data
 ///
 /// ```
-/// use arrow_array::{DictionaryArray, Int8Array, types::Int8Type};
+/// # use arrow_array::{DictionaryArray, Int8Array, types::Int8Type};
 /// let test = vec!["a", "a", "b", "c"];
 /// let array : DictionaryArray<Int8Type> = test.into_iter().collect();
 /// assert_eq!(array.keys(), &Int8Array::from(vec![0, 0, 1, 2]));
 /// ```
 ///
-/// Example from existing arrays:
+/// # Example: From Existing Arrays
 ///
 /// ```
-/// use std::sync::Arc;
-/// use arrow_array::{DictionaryArray, Int8Array, StringArray, types::Int8Type};
+/// # use std::sync::Arc;
+/// # use arrow_array::{DictionaryArray, Int8Array, StringArray, types::Int8Type};
 /// // You can form your own DictionaryArray by providing the
 /// // values (dictionary) and keys (indexes into the dictionary):
 /// let values = StringArray::from_iter_values(["a", "b", "c"]);
 /// let keys = Int8Array::from_iter_values([0, 0, 1, 2]);
 /// let array = DictionaryArray::<Int8Type>::try_new(keys, Arc::new(values)).unwrap();
-/// let expected: DictionaryArray::<Int8Type> = vec!["a", "a", "b", "c"]
-///    .into_iter()
-///    .collect();
+/// let expected: DictionaryArray::<Int8Type> = vec!["a", "a", "b", "c"].into_iter().collect();
 /// assert_eq!(&array, &expected);
 /// ```
+///
+/// # Example: Using Builder
+///
+/// ```
+/// # use arrow_array::{Array, StringArray};
+/// # use arrow_array::builder::StringDictionaryBuilder;
+/// # use arrow_array::types::Int32Type;
+/// let mut builder = StringDictionaryBuilder::<Int32Type>::new();
+/// builder.append_value("a");
+/// builder.append_null();
+/// builder.append_value("a");
+/// builder.append_value("b");
+/// let array = builder.finish();
+///
+/// let values: Vec<_> = array.downcast_dict::<StringArray>().unwrap().into_iter().collect();
+/// assert_eq!(&values, &[Some("a"), None, Some("a"), Some("b")]);
+/// ```
 pub struct DictionaryArray<K: ArrowDictionaryKeyType> {
     data_type: DataType,