From 75f74e6e0d032569b514228c35ac23b651cc02d6 Mon Sep 17 00:00:00 2001 From: "Jorge C. Leitao" Date: Fri, 20 Aug 2021 22:30:33 +0000 Subject: [PATCH] Added more docs. --- src/array/boolean/from.rs | 7 +++++++ src/array/boolean/iterator.rs | 8 ++++---- src/array/boolean/mod.rs | 20 +++++++------------- src/array/boolean/mutable.rs | 3 ++- src/array/primitive/mod.rs | 9 +++++++++ src/array/primitive/mutable.rs | 3 ++- src/array/utf8/mod.rs | 13 ++++++------- 7 files changed, 37 insertions(+), 26 deletions(-) diff --git a/src/array/boolean/from.rs b/src/array/boolean/from.rs index 5134dec092b..cf16d572787 100644 --- a/src/array/boolean/from.rs +++ b/src/array/boolean/from.rs @@ -4,6 +4,13 @@ use crate::trusted_len::TrustedLen; use super::{BooleanArray, MutableBooleanArray}; +impl]>> From

for BooleanArray { + /// Creates a new [`BooleanArray`] out of a slice of Optional `bool`. + fn from(slice: P) -> Self { + MutableBooleanArray::from(slice).into() + } +} + impl BooleanArray { /// Creates a new [`BooleanArray`] from an [`TrustedLen`] of `bool`. #[inline] diff --git a/src/array/boolean/iterator.rs b/src/array/boolean/iterator.rs index d5e0b0c7731..8b5e679fef0 100644 --- a/src/array/boolean/iterator.rs +++ b/src/array/boolean/iterator.rs @@ -14,7 +14,7 @@ impl<'a> IntoIterator for &'a BooleanArray { } impl<'a> BooleanArray { - /// constructs a new iterator + /// Returns an iterator over the optional values of this [`BooleanArray`]. #[inline] pub fn iter(&'a self) -> ZipValidity<'a, bool, BitmapIter<'a>> { zip_validity( @@ -23,7 +23,7 @@ impl<'a> BooleanArray { ) } - /// Returns an iterator of `bool` + /// Returns an iterator over the values of this [`BooleanArray`] #[inline] pub fn values_iter(&'a self) -> BitmapIter<'a> { self.values().iter() @@ -41,7 +41,7 @@ impl<'a> IntoIterator for &'a MutableBooleanArray { } impl<'a> MutableBooleanArray { - /// Returns an iterator over `Option` + /// Returns an iterator over the optional values of this [`MutableBooleanArray`]. #[inline] pub fn iter(&'a self) -> ZipValidity<'a, bool, BitmapIter<'a>> { zip_validity( @@ -50,7 +50,7 @@ impl<'a> MutableBooleanArray { ) } - /// Returns an iterator of `bool` + /// Returns an iterator over the values of this [`MutableBooleanArray`] #[inline] pub fn values_iter(&'a self) -> BitmapIter<'a> { self.values().iter() diff --git a/src/array/boolean/mod.rs b/src/array/boolean/mod.rs index f5e2ece43d2..3679a361ee9 100644 --- a/src/array/boolean/mod.rs +++ b/src/array/boolean/mod.rs @@ -10,8 +10,8 @@ mod mutable; pub use iterator::*; pub use mutable::*; -/// A [`BooleanArray`] is arrow's equivalent to an immutable `Vec>`, i.e. -/// The size of this struct is `O(1)` as all data is stored behind an `Arc`, and +/// The Arrow's equivalent to an immutable `Vec>`, but with `1/16` of its size. +/// Cloning and slicing this struct is `O(1)`. #[derive(Debug, Clone)] pub struct BooleanArray { values: Bitmap, @@ -51,7 +51,7 @@ impl BooleanArray { /// Returns a slice of this [`BooleanArray`]. /// # Implementation - /// This operation is `O(1)` as it amounts to essentially increase two ref counts. + /// This operation is `O(1)` as it amounts to increase two ref counts. /// # Panic /// This function panics iff `offset + length >= self.len()`. #[inline] @@ -64,14 +64,15 @@ impl BooleanArray { } } - /// Returns the element at index `i` as bool + /// Returns the value at index `i` + /// # Panic + /// This function panics iff `i >= self.len()`. #[inline] pub fn value(&self, i: usize) -> bool { self.values.get_bit(i) } /// Returns the element at index `i` as bool - /// /// # Safety /// Caller must be sure that `i < self.len()` #[inline] @@ -79,7 +80,7 @@ impl BooleanArray { self.values.get_bit_unchecked(i) } - /// Returns the values bitmap of this [`BooleanArray`]. + /// Returns the values of this [`BooleanArray`]. #[inline] pub fn values(&self) -> &Bitmap { &self.values @@ -118,10 +119,3 @@ impl std::fmt::Display for BooleanArray { display_fmt(self.iter(), "BooleanArray", f, false) } } - -impl]>> From

for BooleanArray { - /// Creates a new [`BooleanArray`] out of a slice of Optional `bool`. - fn from(slice: P) -> Self { - MutableBooleanArray::from(slice).into() - } -} diff --git a/src/array/boolean/mutable.rs b/src/array/boolean/mutable.rs index 068e595e687..603a30b83b7 100644 --- a/src/array/boolean/mutable.rs +++ b/src/array/boolean/mutable.rs @@ -12,7 +12,8 @@ use crate::{ use super::BooleanArray; -/// The mutable version of [`BooleanArray`]. See [`MutableArray`] for more details. +/// The Arrow's equivalent to `Vec>`, but with `1/16` of its size. +/// Converting a [`MutableBooleanArray`] into a [`BooleanArray`] is `O(1)`. #[derive(Debug)] pub struct MutableBooleanArray { values: MutableBitmap, diff --git a/src/array/primitive/mod.rs b/src/array/primitive/mod.rs index 49033ba9dec..42f5197f51c 100644 --- a/src/array/primitive/mod.rs +++ b/src/array/primitive/mod.rs @@ -20,6 +20,15 @@ pub use mutable::*; /// an array designed for highly performant operations on optionally nullable slots, /// backed by a physical type of a physical byte-width, such as `i32` or `f64`. /// The size of this struct is `O(1)` as all data is stored behind an [`std::sync::Arc`]. +/// # Example +/// ``` +/// use arrow2::array::PrimitiveArray; +/// # fn main() { +/// let array = Utf8Array::::from([Some(1), None, Some(2)]); +/// assert_eq!(array.value(0), 1); +/// assert_eq!(array.values().as_slice(), &[1, 0, 2]); +/// # } +/// ``` #[derive(Debug, Clone)] pub struct PrimitiveArray { data_type: DataType, diff --git a/src/array/primitive/mutable.rs b/src/array/primitive/mutable.rs index a4f771ebe39..aad618bf63a 100644 --- a/src/array/primitive/mutable.rs +++ b/src/array/primitive/mutable.rs @@ -12,7 +12,8 @@ use crate::{ use super::PrimitiveArray; -/// The mutable version of [`PrimitiveArray`]. See [`MutableArray`] for more details. +/// The Arrow's equivalent to `Vec>` where `T` is byte-size (e.g. `i32`). +/// Converting a [`MutablePrimitiveArray`] into a [`PrimitiveArray`] is `O(1)`. #[derive(Debug)] pub struct MutablePrimitiveArray { data_type: DataType, diff --git a/src/array/utf8/mod.rs b/src/array/utf8/mod.rs index a9ed14c6b64..c1aaf8d5f83 100644 --- a/src/array/utf8/mod.rs +++ b/src/array/utf8/mod.rs @@ -13,17 +13,16 @@ mod mutable; pub use iterator::*; pub use mutable::*; -/// A [`Utf8Array`] is arrow's equivalent of `Vec>`, i.e. -/// an array designed for highly performant operations on optionally nullable strings. -/// The size of this struct is `O(1)` as all data is stored behind an `Arc`. +/// A [`Utf8Array`] is arrow's equivalent of an immutable `Vec>`. +/// Cloning and slicing this struct is `O(1)`. /// # Example /// ``` -/// use std::iter::FromIterator; /// use arrow2::array::Utf8Array; /// # fn main() { -/// let data = vec![Some("hello"), None, Some("hello2")]; -/// let array = Utf8Array::::from_iter(data); -/// assert_eq!(array.value(0), "hello"); +/// let array = Utf8Array::::from([Some("hi"), None, Some("there")]); +/// assert_eq!(array.value(0), "hi"); +/// assert_eq!(array.values(), b"hithere"); +/// assert_eq!(array.offsets().as_slice(), &[0, 2, 2, 2 + 5]); /// # } /// ``` #[derive(Debug, Clone)]