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.git
The following commit(s) were added to refs/heads/master by this push:
new 7865589 ARROW-11977: [Rust] Add documentation examples for sort kernel
7865589 is described below
commit 78655890ad8814e79fc9e70ad87994379e849bc6
Author: Andrew Lamb <[email protected]>
AuthorDate: Thu Mar 18 06:27:55 2021 -0400
ARROW-11977: [Rust] Add documentation examples for sort kernel
# Rationale
Examples in the docs serve as both tests and makes the library easier to use
I figured this would be helpful the wake of the very helpful
https://github.com/apache/arrow/pull/9602 by @sundy-li
I think I am in a documenting kind of mood this week
Closes #9721 from alamb/alamb/sort_doc_examples
Authored-by: Andrew Lamb <[email protected]>
Signed-off-by: Andrew Lamb <[email protected]>
---
rust/arrow/src/compute/kernels/sort.rs | 49 ++++++++++++++++++++++++++++++++--
1 file changed, 47 insertions(+), 2 deletions(-)
diff --git a/rust/arrow/src/compute/kernels/sort.rs
b/rust/arrow/src/compute/kernels/sort.rs
index f547273..738178f 100644
--- a/rust/arrow/src/compute/kernels/sort.rs
+++ b/rust/arrow/src/compute/kernels/sort.rs
@@ -35,14 +35,59 @@ use TimeUnit::*;
///
/// Returns an `ArrowError::ComputeError(String)` if the array type is either
unsupported by `sort_to_indices` or `take`.
///
+/// # Example
+/// ```rust
+/// # use std::sync::Arc;
+/// # use arrow::array::{Int32Array, ArrayRef};
+/// # use arrow::error::Result;
+/// # use arrow::compute::kernels::sort::sort;
+/// # fn main() -> Result<()> {
+/// let array: ArrayRef = Arc::new(Int32Array::from(vec![5, 4, 3, 2, 1]));
+/// let sorted_array = sort(&array, None).unwrap();
+/// let sorted_array =
sorted_array.as_any().downcast_ref::<Int32Array>().unwrap();
+/// assert_eq!(sorted_array, &Int32Array::from(vec![1, 2, 3, 4, 5]));
+/// # Ok(())
+/// # }
+/// ```
pub fn sort(values: &ArrayRef, options: Option<SortOptions>) ->
Result<ArrayRef> {
let indices = sort_to_indices(values, options, None)?;
take(values.as_ref(), &indices, None)
}
/// Sort the `ArrayRef` partially.
-/// It's unstable_sort, may not preserve the order of equal elements
-/// Return an sorted `ArrayRef`, discarding the data after limit.
+///
+/// If `limit` is specified, the resulting array will contain only
+/// first `limit` in the sort order. Any data data after the limit
+/// will be discarded.
+///
+/// Note: this is an unstable_sort, meaning it may not preserve the
+/// order of equal elements.
+///
+/// # Example
+/// ```rust
+/// # use std::sync::Arc;
+/// # use arrow::array::{Int32Array, ArrayRef};
+/// # use arrow::error::Result;
+/// # use arrow::compute::kernels::sort::{sort_limit, SortOptions};
+/// # fn main() -> Result<()> {
+/// let array: ArrayRef = Arc::new(Int32Array::from(vec![5, 4, 3, 2, 1]));
+///
+/// // Find the the top 2 items
+/// let sorted_array = sort_limit(&array, None, Some(2)).unwrap();
+/// let sorted_array =
sorted_array.as_any().downcast_ref::<Int32Array>().unwrap();
+/// assert_eq!(sorted_array, &Int32Array::from(vec![1, 2]));
+///
+/// // Find the bottom top 2 items
+/// let options = Some(SortOptions {
+/// descending: true,
+/// ..Default::default()
+/// });
+/// let sorted_array = sort_limit(&array, options, Some(2)).unwrap();
+/// let sorted_array =
sorted_array.as_any().downcast_ref::<Int32Array>().unwrap();
+/// assert_eq!(sorted_array, &Int32Array::from(vec![5, 4]));
+/// # Ok(())
+/// # }
+/// ```
pub fn sort_limit(
values: &ArrayRef,
options: Option<SortOptions>,
