[arrow-rs] branch active_release updated: Doctests for DictionaryArray::from_iter, PrimitiveDictionaryBuilder and DecimalBuilder. (#673) (#679)

[al...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

alamb pushed a commit to branch active_release
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git


The following commit(s) were added to refs/heads/active_release by this push:
     new 52bbc81  Doctests for DictionaryArray::from_iter, PrimitiveDictionaryBuilder and DecimalBuilder. (#673) (#679)
52bbc81 is described below

commit 52bbc81c9c4cd8a05a0573709a0982a902524e87
Author: Andrew Lamb <an...@nerdnetworks.org>
AuthorDate: Mon Aug 9 07:25:51 2021 -0400

    Doctests for DictionaryArray::from_iter, PrimitiveDictionaryBuilder and DecimalBuilder. (#673) (#679)
    
    * Doctest for PrimitiveDictionaryBuilder.
    
    * Doctests for DictionaryArray::from_iter.
    
    * Documentation for DecimalBuilder.
    
    Co-authored-by: Navin <na...@novemberkilo.com>
---
 arrow/src/array/array_dictionary.rs | 30 ++++++++++++++++++++++++++++
 arrow/src/array/builder.rs          | 39 +++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/arrow/src/array/array_dictionary.rs b/arrow/src/array/array_dictionary.rs
index cf847ef..de9873c 100644
--- a/arrow/src/array/array_dictionary.rs
+++ b/arrow/src/array/array_dictionary.rs
@@ -153,6 +153,22 @@ impl<T: ArrowPrimitiveType> From<ArrayData> for DictionaryArray<T> {
 }
 
 /// Constructs a `DictionaryArray` from an iterator of optional strings.
+///
+/// # Example:
+/// ```
+/// use arrow::array::{DictionaryArray, PrimitiveArray, StringArray};
+/// use arrow::datatypes::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!(
+///     "DictionaryArray {keys: PrimitiveArray<Int8>\n[\n  0,\n  0,\n  null,\n  1,\n] values: StringArray\n[\n  \"a\",\n  \"c\",\n]}\n",
+///     format!("{:?}", array)
+/// );
+/// ```
 impl<'a, T: ArrowPrimitiveType + ArrowDictionaryKeyType> FromIterator<Option<&'a str>>
     for DictionaryArray<T>
 {
@@ -181,6 +197,20 @@ impl<'a, T: ArrowPrimitiveType + ArrowDictionaryKeyType> FromIterator<Option<&'a
 }
 
 /// Constructs a `DictionaryArray` from an iterator of strings.
+///
+/// # Example:
+///
+/// ```
+/// use arrow::array::{DictionaryArray, PrimitiveArray, StringArray};
+/// use arrow::datatypes::Int8Type;
+///
+/// let test = vec!["a", "a", "b", "c"];
+/// let array: DictionaryArray<Int8Type> = test.into_iter().collect();
+/// assert_eq!(
+///     "DictionaryArray {keys: PrimitiveArray<Int8>\n[\n  0,\n  0,\n  1,\n  2,\n] values: StringArray\n[\n  \"a\",\n  \"b\",\n  \"c\",\n]}\n",
+///     format!("{:?}", array)
+/// );
+/// ```
 impl<'a, T: ArrowPrimitiveType + ArrowDictionaryKeyType> FromIterator<&'a str>
     for DictionaryArray<T>
 {
diff --git a/arrow/src/array/builder.rs b/arrow/src/array/builder.rs
index c3835f9..d0d144a 100644
--- a/arrow/src/array/builder.rs
+++ b/arrow/src/array/builder.rs
@@ -1062,6 +1062,11 @@ pub struct FixedSizeBinaryBuilder {
     builder: FixedSizeListBuilder<UInt8Builder>,
 }
 
+///
+/// Array Builder for [`DecimalArray`]
+///
+/// See [`DecimalArray`] for example.
+///
 #[derive(Debug)]
 pub struct DecimalBuilder {
     builder: FixedSizeListBuilder<UInt8Builder>,
@@ -1938,6 +1943,40 @@ impl UnionBuilder {
 /// Array builder for `DictionaryArray`. For example to map a set of byte indices
 /// to f32 values. Note that the use of a `HashMap` here will not scale to very large
 /// arrays or result in an ordered dictionary.
+///
+/// # Example:
+///
+/// ```
+///  use arrow::array::{
+///      Array, PrimitiveBuilder, PrimitiveDictionaryBuilder,
+///      UInt8Array, UInt32Array,
+///    };
+///  use arrow::datatypes::{UInt8Type, UInt32Type};
+///
+///  let key_builder = PrimitiveBuilder::<UInt8Type>::new(3);
+///  let value_builder = PrimitiveBuilder::<UInt32Type>::new(2);
+///  let mut builder = PrimitiveDictionaryBuilder::new(key_builder, value_builder);
+///  builder.append(12345678).unwrap();
+///  builder.append_null().unwrap();
+///  builder.append(22345678).unwrap();
+///  let array = builder.finish();
+///
+///  assert_eq!(
+///      array.keys(),
+///      &UInt8Array::from(vec![Some(0), None, Some(1)])
+///  );
+///
+///  // Values are polymorphic and so require a downcast.
+///  let av = array.values();
+///  let ava: &UInt32Array = av.as_any().downcast_ref::<UInt32Array>().unwrap();
+///  let avs: &[u32] = ava.values();
+///
+///  assert!(!array.is_null(0));
+///  assert!(array.is_null(1));
+///  assert!(!array.is_null(2));
+///
+///  assert_eq!(avs, &[12345678, 22345678]);
+/// ```
 #[derive(Debug)]
 pub struct PrimitiveDictionaryBuilder<K, V>
 where