Skip to content

Commit b448de7

Browse files
alambjorgecarleitao
authored andcommitted
ARROW-11216: [Rust] add doc example for StringDictionaryBuilder
I find myself trying to remember the exact incantation to create a `StringDictionaryBuilder` so I figured I would add it as a doc example Closes #9169 from alamb/alamb/doc-example Authored-by: Andrew Lamb <[email protected]> Signed-off-by: Jorge C. Leitao <[email protected]>
1 parent 7e0cb0a commit b448de7

File tree

1 file changed

+40
-2
lines changed

1 file changed

+40
-2
lines changed

rust/arrow/src/array/builder.rs

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1854,9 +1854,47 @@ where
18541854
}
18551855
}
18561856

1857-
/// Array builder for `DictionaryArray`. For example to map a set of byte indices
1858-
/// to f32 values. Note that the use of a `HashMap` here will not scale to very large
1857+
/// Array builder for `DictionaryArray` that stores Strings. For example to map a set of byte indices
1858+
/// to String values. Note that the use of a `HashMap` here will not scale to very large
18591859
/// arrays or result in an ordered dictionary.
1860+
///
1861+
/// ```
1862+
/// use arrow::{
1863+
/// array::{
1864+
/// Int8Array, StringArray,
1865+
/// PrimitiveBuilder, StringBuilder, StringDictionaryBuilder,
1866+
/// },
1867+
/// datatypes::Int8Type,
1868+
/// };
1869+
///
1870+
/// // Create a dictionary array indexed by bytes whose values are Strings.
1871+
/// // It can thus hold up to 256 distinct string values.
1872+
///
1873+
/// let key_builder = PrimitiveBuilder::<Int8Type>::new(100);
1874+
/// let value_builder = StringBuilder::new(100);
1875+
/// let mut builder = StringDictionaryBuilder::new(key_builder, value_builder);
1876+
///
1877+
/// // The builder builds the dictionary value by value
1878+
/// builder.append("abc").unwrap();
1879+
/// builder.append_null().unwrap();
1880+
/// builder.append("def").unwrap();
1881+
/// builder.append("def").unwrap();
1882+
/// builder.append("abc").unwrap();
1883+
/// let array = builder.finish();
1884+
///
1885+
/// assert_eq!(
1886+
/// array.keys(),
1887+
/// &Int8Array::from(vec![Some(0), None, Some(1), Some(1), Some(0)])
1888+
/// );
1889+
///
1890+
/// // Values are polymorphic and so require a downcast.
1891+
/// let av = array.values();
1892+
/// let ava: &StringArray = av.as_any().downcast_ref::<StringArray>().unwrap();
1893+
///
1894+
/// assert_eq!(ava.value(0), "abc");
1895+
/// assert_eq!(ava.value(1), "def");
1896+
///
1897+
/// ```
18601898
#[derive(Debug)]
18611899
pub struct StringDictionaryBuilder<K>
18621900
where

0 commit comments

Comments
 (0)