Skip to content

Improve docs for NullArray, new_null_array and new_empty_array #240

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

Merged
merged 2 commits into from
May 3, 2021
Merged

Improve docs for NullArray, new_null_array and new_empty_array #240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f7d81f4
Update docs in null_array.rs so they are discoverable
alamb Apr 29, 2021
fea52de
Add doc examples for new_null_array and new_empty_array
alamb Apr 29, 2021
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
26 changes: 25 additions & 1 deletion arrow/src/array/array.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,11 +324,35 @@ pub fn make_array(data: ArrayData) -> ArrayRef {
}

/// Creates a new empty array
///
/// ```
/// use std::sync::Arc;
/// use arrow::datatypes::DataType;
/// use arrow::array::{ArrayRef, Int32Array, new_empty_array};
///
/// let empty_array = new_empty_array(&DataType::Int32);
/// let array: ArrayRef = Arc::new(Int32Array::from(vec![] as Vec<i32>));
///
/// assert_eq!(&array, &empty_array);
/// ```
pub fn new_empty_array(data_type: &DataType) -> ArrayRef {
let data = ArrayData::new_empty(data_type);
make_array(data)
}
/// Creates a new array of `data_type` of length `length` filled entirely of `NULL` values

/// Creates a new array of `data_type` of length `length` filled
/// entirely of `NULL` values
///
/// ```
/// use std::sync::Arc;
/// use arrow::datatypes::DataType;
/// use arrow::array::{ArrayRef, Int32Array, new_null_array};
///
/// let null_array = new_null_array(&DataType::Int32, 3);
/// let array: ArrayRef = Arc::new(Int32Array::from(vec![None, None, None]));
///
/// assert_eq!(&array, &null_array);
/// ```
pub fn new_null_array(data_type: &DataType, length: usize) -> ArrayRef {
// context: https://github.com/apache/arrow/pull/9469#discussion_r574761687
match data_type {
Expand Down
40 changes: 22 additions & 18 deletions arrow/src/array/null.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,23 +16,6 @@
// under the License.

//! Contains the `NullArray` type.
//!
//! A `NullArray` is a simplified array where all values are null.
//!
//! # Example: Create an array
//!
//! ```
//! use arrow::array::{Array, NullArray};
//!
//! # fn main() -> arrow::error::Result<()> {
//! let array = NullArray::new(10);
//!
//! assert_eq!(array.len(), 10);
//! assert_eq!(array.null_count(), 10);
//!
//! # Ok(())
//! # }
//! ```

use std::any::Any;
use std::fmt;
Expand All @@ -42,12 +25,33 @@ use crate::array::{Array, ArrayData};
use crate::datatypes::*;

/// An Array where all elements are nulls
///
Copy link
Contributor Author

@alamb alamb Apr 29, 2021

Choose a reason for hiding this comment

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

By moving the description to the struct, the documentation is now on the doc page I would expect (not the module level). Here is what it looks like now:

Screen Shot 2021-04-29 at 12 54 51 PM

/// A `NullArray` is a simplified array where all values are null.
///
/// # Example: Create an array
///
/// ```
/// use arrow::array::{Array, NullArray};
///
/// # fn main() -> arrow::error::Result<()> {
/// let array = NullArray::new(10);
///
/// assert_eq!(array.len(), 10);
/// assert_eq!(array.null_count(), 10);
///
/// # Ok(())
/// # }
/// ```
pub struct NullArray {
data: ArrayData,
}

impl NullArray {
/// Create a new null array of the specified length
/// Create a new [`NullArray`] of the specified length
///
/// *Note*: Use [`crate::array::new_null_array`] if you need an array of some
/// other [`DataType`].
///
pub fn new(length: usize) -> Self {
let array_data = ArrayData::builder(DataType::Null).len(length).build();
NullArray::from(array_data)
Expand Down