This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/master by this push:
new a040c15 Improve docs for NullArray, new_null_array and
new_empty_array (#240)
a040c15 is described below
commit a040c15fb6eb7353426b0cccaf56c64832121498
Author: Andrew Lamb <[email protected]>
AuthorDate: Mon May 3 10:41:30 2021 -0400
Improve docs for NullArray, new_null_array and new_empty_array (#240)
* Update docs in null_array.rs so they are discoverable
* Add doc examples for new_null_array and new_empty_array
---
arrow/src/array/array.rs | 26 +++++++++++++++++++++++++-
arrow/src/array/null.rs | 40 ++++++++++++++++++++++------------------
2 files changed, 47 insertions(+), 19 deletions(-)
diff --git a/arrow/src/array/array.rs b/arrow/src/array/array.rs
index 95a3117..de87c3d 100644
--- a/arrow/src/array/array.rs
+++ b/arrow/src/array/array.rs
@@ -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 {
diff --git a/arrow/src/array/null.rs b/arrow/src/array/null.rs
index 8e95bb0..40513af 100644
--- a/arrow/src/array/null.rs
+++ b/arrow/src/array/null.rs
@@ -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;
@@ -42,12 +25,33 @@ use crate::array::{Array, ArrayData};
use crate::datatypes::*;
/// An Array where all elements are nulls
+///
+/// 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)
