Added example.

examples/growable.rs

@@ -0,0 +1,38 @@
+use arrow2::array::growable::{Growable, GrowablePrimitive};
+use arrow2::array::{Array, PrimitiveArray};
+
+fn main() {
+    // say we have two sorted arrays
+    let array0 = PrimitiveArray::<i64>::from_slice(&[1, 2, 5]);
+    let array1 = PrimitiveArray::<i64>::from_slice(&[3, 4, 6]);
+
+    // and we found a way to compute the slices that sort them:
+    // (array_index, start of the slice, length of the slice)
+    let slices = &[
+        // [1, 2] from array0
+        (0, 0, 2),
+        // [3, 4] from array1
+        (1, 0, 2),
+        // [5] from array0
+        (0, 2, 1),
+        // [6] from array1
+        (1, 2, 1),
+    ];
+
+    // we can build a new array out of these slices as follows:
+    // first, declare the growable out of the arrays. Since we are not extending with nulls,
+    // we use `false`. We also pre-allocate, as we know that we will need all entries.
+    let capacity = array0.len() + array1.len();
+    let use_validity = false;
+    let mut growable = GrowablePrimitive::new(vec![&array0, &array1], use_validity, capacity);
+
+    // next, extend the growable:
+    for slice in slices {
+        growable.extend(slice.0, slice.1, slice.2);
+    }
+    // finally, convert it to the array (this is `O(1)`)
+    let result: PrimitiveArray<i64> = growable.into();
+
+    let expected = PrimitiveArray::<i64>::from_slice(&[1, 2, 3, 4, 5, 6]);
+    assert_eq!(result, expected);
+}

guide/src/high_level.md

@@ -267,3 +267,13 @@ Some notes:
 
 3. We used `op` on the array's values irrespectively of their validity,
 and cloned its validity. This approach is suitable for operations whose branching off is more expensive than operating over all values. If the operation is expensive, then using `PrimitiveArray::<O>::from_trusted_len_iter` is likely faster.
+
+## Growable API
+
+In `arrow2::array::growable` you can find the growable API; a set of structs used to create
+an array out of existing arrays. You can find an example of how to use this API in `examples`,
+which is reproduced here:
+
+```rust
+{{#include ../../examples/growable.rs}}
+```

src/array/growable/primitive.rs

@@ -155,15 +155,14 @@ mod tests {
 
     #[test]
     fn test_primitive_joining_arrays() {
-        let b = PrimitiveArray::<u8>::from(vec![Some(1), Some(2), Some(3)]).to(DataType::UInt8);
-        let c = PrimitiveArray::<u8>::from(vec![Some(4), Some(5), Some(6)]).to(DataType::UInt8);
+        let b = PrimitiveArray::<u8>::from(vec![Some(1), Some(2), Some(3)]);
+        let c = PrimitiveArray::<u8>::from(vec![Some(4), Some(5), Some(6)]);
         let mut a = GrowablePrimitive::new(vec![&b, &c], false, 4);
         a.extend(0, 0, 2);
         a.extend(1, 1, 2);
         let result: PrimitiveArray<u8> = a.into();
 
-        let expected = PrimitiveArray::<u8>::from(vec![Some(1), Some(2), Some(5), Some(6)])
-            .to(DataType::UInt8);
+        let expected = PrimitiveArray::<u8>::from(vec![Some(1), Some(2), Some(5), Some(6)]);
         assert_eq!(result, expected);
     }
 }