alamb commented on code in PR #4381:
URL: https://github.com/apache/arrow-rs/pull/4381#discussion_r1223404073
##########
arrow-array/src/array/dictionary_array.rs:
##########
@@ -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);
/// ```
+///
Review Comment:
👍
##########
arrow-array/src/array/primitive_array.rs:
##########
@@ -384,23 +407,70 @@ pub type Decimal128Array = PrimitiveArray<Decimal128Type>;
/// // Create iter/collect
/// let arr: Decimal256Array =
std::iter::repeat(i256::from(42)).take(10).collect();
/// ```
+///
+/// See [`PrimitiveArray`] for more information and examples
pub type Decimal256Array = PrimitiveArray<Decimal256Type>;
pub use crate::types::ArrowPrimitiveType;
/// An array of [primitive
values](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
///
+/// # Example: From a Vec
+///
+/// ```
+/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
+/// let arr: PrimitiveArray<Int32Type> = vec![1, 2, 3, 4].into();
+/// assert_eq!(4, arr.len());
+/// assert_eq!(0, arr.null_count());
+/// assert_eq!(arr.values(), &[1, 2, 3, 4])
+/// ```
+///
+/// # Example: From an optional Vec
+///
+/// ```
+/// # use arrow_array::{Array, PrimitiveArray, types::Int32Type};
+/// let arr: PrimitiveArray<Int32Type> = vec![Some(1), None, Some(3),
None].into();
+/// assert_eq!(4, arr.len());
+/// assert_eq!(2, arr.null_count());
+/// assert_eq!(arr.values(), &[1, 0, 3, 0])
Review Comment:
is it worth pointing out that the `0` (for the `null` locations) are
arbitrary values?
##########
arrow-array/src/array/list_array.rs:
##########
@@ -471,58 +473,10 @@ impl<OffsetSize: OffsetSizeTrait> std::fmt::Debug for
GenericListArray<OffsetSiz
}
}
-/// An array of variable size lists, storing offsets as `i32`.
-///
-/// # Example
-///
-/// ```
-/// # use arrow_array::{Array, ListArray, Int32Array, types::Int32Type};
-/// # use arrow_schema::DataType;
-/// let data = vec![
-/// Some(vec![]),
-/// None,
-/// Some(vec![Some(3), None, Some(5), Some(19)]),
-/// Some(vec![Some(6), Some(7)]),
-/// ];
-/// let list_array = ListArray::from_iter_primitive::<Int32Type, _, _>(data);
-///
-/// assert_eq!(false, list_array.is_valid(1));
-///
-/// let list0 = list_array.value(0);
-/// let list2 = list_array.value(2);
-/// let list3 = list_array.value(3);
-///
-/// assert_eq!(&[] as &[i32],
list0.as_any().downcast_ref::<Int32Array>().unwrap().values());
-/// assert_eq!(false,
list2.as_any().downcast_ref::<Int32Array>().unwrap().is_valid(1));
-/// assert_eq!(&[6, 7],
list3.as_any().downcast_ref::<Int32Array>().unwrap().values());
-/// ```
+/// A [`GenericListArray`] of variable size lists, storing offsets as `i32`.
Review Comment:
Can we also add a link here to the builder too?
```suggestion
/// A [`GenericListArray`] of variable size lists, storing offsets as `i32`.
///
/// See [`GenericListBuilder`](crate::builder::GenericListBuilder) for how
to construct a [`GenericListArray`]
```
##########
arrow-array/src/array/list_array.rs:
##########
@@ -471,58 +473,10 @@ impl<OffsetSize: OffsetSizeTrait> std::fmt::Debug for
GenericListArray<OffsetSiz
}
}
-/// An array of variable size lists, storing offsets as `i32`.
-///
-/// # Example
-///
-/// ```
-/// # use arrow_array::{Array, ListArray, Int32Array, types::Int32Type};
-/// # use arrow_schema::DataType;
-/// let data = vec![
-/// Some(vec![]),
-/// None,
-/// Some(vec![Some(3), None, Some(5), Some(19)]),
-/// Some(vec![Some(6), Some(7)]),
-/// ];
-/// let list_array = ListArray::from_iter_primitive::<Int32Type, _, _>(data);
-///
-/// assert_eq!(false, list_array.is_valid(1));
-///
-/// let list0 = list_array.value(0);
-/// let list2 = list_array.value(2);
-/// let list3 = list_array.value(3);
-///
-/// assert_eq!(&[] as &[i32],
list0.as_any().downcast_ref::<Int32Array>().unwrap().values());
-/// assert_eq!(false,
list2.as_any().downcast_ref::<Int32Array>().unwrap().is_valid(1));
-/// assert_eq!(&[6, 7],
list3.as_any().downcast_ref::<Int32Array>().unwrap().values());
-/// ```
+/// A [`GenericListArray`] of variable size lists, storing offsets as `i32`.
pub type ListArray = GenericListArray<i32>;
-/// An array of variable size lists, storing offsets as `i64`.
-///
-/// # Example
-///
-/// ```
-/// # use arrow_array::{Array, LargeListArray, Int32Array, types::Int32Type};
-/// # use arrow_schema::DataType;
-/// let data = vec![
-/// Some(vec![]),
-/// None,
-/// Some(vec![Some(3), None, Some(5), Some(19)]),
-/// Some(vec![Some(6), Some(7)]),
-/// ];
-/// let list_array = LargeListArray::from_iter_primitive::<Int32Type, _,
_>(data);
-///
-/// assert_eq!(false, list_array.is_valid(1));
-///
-/// let list0 = list_array.value(0);
-/// let list2 = list_array.value(2);
-/// let list3 = list_array.value(3);
-///
-/// assert_eq!(&[] as &[i32],
list0.as_any().downcast_ref::<Int32Array>().unwrap().values());
-/// assert_eq!(false,
list2.as_any().downcast_ref::<Int32Array>().unwrap().is_valid(1));
-/// assert_eq!(&[6, 7],
list3.as_any().downcast_ref::<Int32Array>().unwrap().values());
-/// ```
+/// A [`GenericListArray`] of variable size lists, storing offsets as `i64`.
Review Comment:
```suggestion
/// A [`GenericListArray`] of variable size lists, storing offsets as `i64`.
///
/// See [`GenericListBuilder`](crate::builder::GenericListBuilder) for how
to construct a [`GenericListArray`]
```
##########
arrow-array/src/array/primitive_array.rs:
##########
@@ -384,23 +407,70 @@ pub type Decimal128Array = PrimitiveArray<Decimal128Type>;
/// // Create iter/collect
/// let arr: Decimal256Array =
std::iter::repeat(i256::from(42)).take(10).collect();
/// ```
+///
+/// See [`PrimitiveArray`] for more information and examples
pub type Decimal256Array = PrimitiveArray<Decimal256Type>;
pub use crate::types::ArrowPrimitiveType;
/// An array of [primitive
values](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
///
+/// # Example: From a Vec
Review Comment:
I think these are nice examples 👍
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
