Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Improvements #4381

Merged
merged 10 commits into from
Jun 9, 2023
Merged

Documentation Improvements #4381

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
dc81b87
Reorder crate documentation
tustvold Jun 7, 2023
46ca2be
Add backlinks
tustvold Jun 7, 2023
2fe7f2a
Merge remote-tracking branch 'upstream/master' into reorder-docs
tustvold Jun 8, 2023
4fefb47
More examples
tustvold Jun 8, 2023
e817527
Merge remote-tracking branch 'upstream/master' into reorder-docs
tustvold Jun 8, 2023
5f801d4
Link from typedefs to generic types
tustvold Jun 8, 2023
3631db0
Restore examples
tustvold Jun 8, 2023
83d62df
Example cleanup
tustvold Jun 8, 2023
d1ca801
Review feedback
tustvold Jun 9, 2023
75d027b
Merge remote-tracking branch 'upstream/master' into reorder-docs
tustvold Jun 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 3 additions & 77 deletions arrow-array/src/array/binary_array.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ use arrow_buffer::{bit_util, Buffer, MutableBuffer};
use arrow_data::ArrayData;
use arrow_schema::DataType;

/// See [`BinaryArray`] and [`LargeBinaryArray`] for storing binary data
/// A [`GenericBinaryArray`] for storing `[u8]`
pub type GenericBinaryArray<OffsetSize> = GenericByteArray<GenericBinaryType<OffsetSize>>;

impl<OffsetSize: OffsetSizeTrait> GenericBinaryArray<OffsetSize> {
Expand Down Expand Up @@ -217,84 +217,10 @@ where
}
}

/// An array of `[u8]` using `i32` offsets
///
/// The byte length of each element is represented by an i32.
tustvold marked this conversation as resolved.
Show resolved Hide resolved
///
/// # Examples
///
/// Create a BinaryArray from a vector of byte slices.
///
/// ```
/// use arrow_array::{Array, BinaryArray};
/// let values: Vec<&[u8]> =
/// vec![b"one", b"two", b"", b"three"];
/// let array = BinaryArray::from_vec(values);
/// assert_eq!(4, array.len());
/// assert_eq!(b"one", array.value(0));
/// assert_eq!(b"two", array.value(1));
/// assert_eq!(b"", array.value(2));
/// assert_eq!(b"three", array.value(3));
/// ```
///
/// Create a BinaryArray from a vector of Optional (null) byte slices.
///
/// ```
/// use arrow_array::{Array, BinaryArray};
/// let values: Vec<Option<&[u8]>> =
/// vec![Some(b"one"), Some(b"two"), None, Some(b""), Some(b"three")];
/// let array = BinaryArray::from_opt_vec(values);
/// assert_eq!(5, array.len());
/// assert_eq!(b"one", array.value(0));
/// assert_eq!(b"two", array.value(1));
/// assert_eq!(b"", array.value(3));
/// assert_eq!(b"three", array.value(4));
/// assert!(!array.is_null(0));
/// assert!(!array.is_null(1));
/// assert!(array.is_null(2));
/// assert!(!array.is_null(3));
/// assert!(!array.is_null(4));
/// ```
///
/// A [`GenericBinaryArray`] of `[u8]` using `i32` offsets
pub type BinaryArray = GenericBinaryArray<i32>;

/// An array of `[u8]` using `i64` offsets
///
/// # Examples
///
/// Create a LargeBinaryArray from a vector of byte slices.
///
/// ```
/// use arrow_array::{Array, LargeBinaryArray};
/// let values: Vec<&[u8]> =
/// vec![b"one", b"two", b"", b"three"];
/// let array = LargeBinaryArray::from_vec(values);
/// assert_eq!(4, array.len());
/// assert_eq!(b"one", array.value(0));
/// assert_eq!(b"two", array.value(1));
/// assert_eq!(b"", array.value(2));
/// assert_eq!(b"three", array.value(3));
/// ```
///
/// Create a LargeBinaryArray from a vector of Optional (null) byte slices.
///
/// ```
/// use arrow_array::{Array, LargeBinaryArray};
/// let values: Vec<Option<&[u8]>> =
/// vec![Some(b"one"), Some(b"two"), None, Some(b""), Some(b"three")];
/// let array = LargeBinaryArray::from_opt_vec(values);
/// assert_eq!(5, array.len());
/// assert_eq!(b"one", array.value(0));
/// assert_eq!(b"two", array.value(1));
/// assert_eq!(b"", array.value(3));
/// assert_eq!(b"three", array.value(4));
/// assert!(!array.is_null(0));
/// assert!(!array.is_null(1));
/// assert!(array.is_null(2));
/// assert!(!array.is_null(3));
/// assert!(!array.is_null(4));
/// ```
///
/// A [`GenericBinaryArray`] of `[u8]` using `i64` offsets
pub type LargeBinaryArray = GenericBinaryArray<i64>;

#[cfg(test)]
Expand Down
64 changes: 30 additions & 34 deletions arrow-array/src/array/boolean_array.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,51 +27,47 @@ use std::sync::Arc;

/// An array of [boolean values](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
///
/// # Examples
/// # Example: From a Vec
///
/// Construction
/// ```
/// # use arrow_array::{Array, BooleanArray};
/// let arr: BooleanArray = vec![true, true, false].into();
/// let values: Vec<_> = arr.iter().collect();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example seems unnecessarily complicated to me - why would we encourage this pattern instead of what was there

let arr =  BooleanArray::from(vec![true, true, false])

/// assert_eq!(&values, &[Some(true), Some(true), Some(false)])
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this assert adds anything to the doc example: I think it is already clear from the docs what the array contains.

/// ```
///
/// # Example: From an optional Vec
///
/// ```
///# use arrow_array::{Array, BooleanArray};
/// // Create from Vec<Option<bool>>
/// let arr = BooleanArray::from(vec![Some(false), Some(true), None, Some(true)]);
/// // Create from Vec<bool>
/// let arr = BooleanArray::from(vec![false, true, true]);
/// // Create from iter/collect
/// let arr: BooleanArray = std::iter::repeat(Some(true)).take(10).collect();
/// # use arrow_array::{Array, BooleanArray};
/// let arr: BooleanArray = vec![Some(true), None, Some(false)].into();
/// let values: Vec<_> = arr.iter().collect();
/// assert_eq!(&values, &[Some(true), None, Some(false)])
/// ```
///
/// Construction and Access
/// # Example: From an iterator
tustvold marked this conversation as resolved.
Show resolved Hide resolved
///
/// ```
/// use arrow_array::{Array, BooleanArray};
/// let arr = BooleanArray::from(vec![Some(false), Some(true), None, Some(true)]);
/// assert_eq!(4, arr.len());
/// assert_eq!(1, arr.null_count());
/// assert!(arr.is_valid(0));
/// assert!(!arr.is_null(0));
/// assert_eq!(false, arr.value(0));
/// assert!(!arr.is_valid(2));
/// assert!(arr.is_null(2));
/// # use arrow_array::{Array, BooleanArray};
/// let arr: BooleanArray = (0..5).map(|x| (x % 2 == 0).then(|| x % 3 == 0)).collect();
/// let values: Vec<_> = arr.iter().collect();
/// assert_eq!(&values, &[Some(true), None, Some(false), None, Some(false)])
/// ```
///
/// Using `collect`
/// # Example: Using Builder
///
/// ```
/// use arrow_array::{Array, BooleanArray};
/// let v = vec![Some(false), Some(true), Some(false), Some(true)];
/// let arr = v.into_iter().collect::<BooleanArray>();
/// assert_eq!(4, arr.len());
/// assert_eq!(0, arr.offset());
/// assert_eq!(0, arr.null_count());
/// assert!(arr.is_valid(0));
/// assert_eq!(false, arr.value(0));
/// assert!(arr.is_valid(1));
/// assert_eq!(true, arr.value(1));
/// assert!(arr.is_valid(2));
/// assert_eq!(false, arr.value(2));
/// assert!(arr.is_valid(3));
/// assert_eq!(true, arr.value(3));
/// # use arrow_array::Array;
/// # use arrow_array::builder::BooleanBuilder;
/// let mut builder = BooleanBuilder::new();
/// builder.append_value(true);
/// builder.append_null();
/// builder.append_value(false);
/// let array = builder.finish();
/// let values: Vec<_> = array.iter().collect();
/// assert_eq!(&values, &[Some(true), None, Some(false)])
tustvold marked this conversation as resolved.
Show resolved Hide resolved
/// ```
///
#[derive(Clone)]
pub struct BooleanArray {
values: BooleanBuffer,
Expand Down
46 changes: 46 additions & 0 deletions arrow-array/src/array/byte_array.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,52 @@ use std::sync::Arc;
///
/// See [`BinaryArray`] and [`LargeBinaryArray`] for storing arbitrary bytes
///
/// # Example: From a Vec
///
/// ```
/// # use arrow_array::{Array, GenericByteArray, types::Utf8Type};
/// let arr: GenericByteArray<Utf8Type> = vec!["hello", "world", ""].into();
tustvold marked this conversation as resolved.
Show resolved Hide resolved
/// assert_eq!(arr.value_data(), b"helloworld");
/// assert_eq!(arr.value_offsets(), &[0, 5, 10, 10]);
/// let values: Vec<_> = arr.iter().collect();
/// assert_eq!(values, &[Some("hello"), Some("world"), Some("")]);
/// ```
///
/// # Example: From an optional Vec
///
/// ```
/// # use arrow_array::{Array, GenericByteArray, types::Utf8Type};
/// let arr: GenericByteArray<Utf8Type> = vec![Some("hello"), Some("world"), Some(""), None].into();
/// assert_eq!(arr.value_data(), b"helloworld");
/// assert_eq!(arr.value_offsets(), &[0, 5, 10, 10, 10]);
/// let values: Vec<_> = arr.iter().collect();
/// assert_eq!(values, &[Some("hello"), Some("world"), Some(""), None]);
/// ```
///
/// # Example: From an iterator of option
///
/// ```
/// # use arrow_array::{Array, GenericByteArray, types::Utf8Type};
/// let arr: GenericByteArray<Utf8Type> = (0..5).map(|x| (x % 2 == 0).then(|| x.to_string())).collect();
/// let values: Vec<_> = arr.iter().collect();
/// assert_eq!(values, &[Some("0"), None, Some("2"), None, Some("4")]);
/// ```
///
/// # Example: Using Builder
///
/// ```
/// # use arrow_array::Array;
/// # use arrow_array::builder::GenericByteBuilder;
/// # use arrow_array::types::Utf8Type;
/// let mut builder = GenericByteBuilder::<Utf8Type>::new();
/// builder.append_value("hello");
/// builder.append_null();
/// builder.append_value("world");
/// let array = builder.finish();
/// let values: Vec<_> = array.iter().collect();
/// assert_eq!(values, &[Some("hello"), None, Some("world")]);
/// ```
///
/// [`StringArray`]: crate::StringArray
/// [`LargeStringArray`]: crate::LargeStringArray
/// [`BinaryArray`]: crate::BinaryArray
Expand Down
Loading