alamb commented on code in PR #11133:
URL: https://github.com/apache/arrow-rs/pull/11133#discussion_r4052816626
##########
arrow-ord/src/sort.rs:
##########
@@ -934,6 +934,39 @@ pub fn lexsort(columns: &[SortColumn], limit:
Option<usize>) -> Result<Vec<Array
/// Sort elements lexicographically from a list of `ArrayRef` into an unsigned
integer
/// (`UInt32Array`) of indices.
///
+/// # Example
+///
+/// ```
+/// use std::sync::Arc;
Review Comment:
Can you please prefix the `use` statements with `#` so they are hidden from
the example?
So like
```rust
/// # use std::sync::Arc;
..
```
That way they are not displayed in the rendered docs.rs
##########
arrow-ord/src/sort.rs:
##########
@@ -934,6 +934,39 @@ pub fn lexsort(columns: &[SortColumn], limit:
Option<usize>) -> Result<Vec<Array
/// Sort elements lexicographically from a list of `ArrayRef` into an unsigned
integer
/// (`UInt32Array`) of indices.
///
+/// # Example
+///
+/// ```
+/// use std::sync::Arc;
+///
+/// use arrow_array::{ArrayRef, Int32Array, RecordBatch, StringArray};
+/// use arrow_ord::sort::{lexsort_to_indices, SortColumn};
+/// use arrow_select::take::take_record_batch;
+///
+/// let batch = RecordBatch::try_from_iter(vec![
+/// ("a", Arc::new(Int32Array::from(vec![2, 1, 1])) as ArrayRef),
+/// ("b", Arc::new(StringArray::from(vec!["x", "z", "a"])) as ArrayRef),
+/// ])
+/// .unwrap();
+///
+/// let sort_columns = vec![
+/// SortColumn {
+/// values: batch.column(0).clone(),
+/// options: None,
+/// },
+/// SortColumn {
+/// values: batch.column(1).clone(),
+/// options: None,
+/// },
+/// ];
+///
+/// let indices = lexsort_to_indices(&sort_columns, None).unwrap();
Review Comment:
Here it might also be good to show what the contents of indices are too:
```suggestion
/// // indices of the rows of (a,b), in lexographic order
/// let indices = lexsort_to_indices(&sort_columns, None).unwrap();
/// assert_eq!(&indices, [2,1,0]);
```
##########
arrow-ord/src/sort.rs:
##########
@@ -934,6 +934,39 @@ pub fn lexsort(columns: &[SortColumn], limit:
Option<usize>) -> Result<Vec<Array
/// Sort elements lexicographically from a list of `ArrayRef` into an unsigned
integer
/// (`UInt32Array`) of indices.
///
+/// # Example
+///
+/// ```
+/// use std::sync::Arc;
+///
+/// use arrow_array::{ArrayRef, Int32Array, RecordBatch, StringArray};
+/// use arrow_ord::sort::{lexsort_to_indices, SortColumn};
+/// use arrow_select::take::take_record_batch;
+///
+/// let batch = RecordBatch::try_from_iter(vec![
Review Comment:
I personally find examples easier to follow when annotated with more detail
than we might find in normal code where people are familar with the structures
something like
```suggestion
/// // Two columns (a, b). Values (2,x), (1, z), (1(a))
/// let batch = RecordBatch::try_from_iter(vec![
```
##########
arrow-ord/src/sort.rs:
##########
@@ -934,6 +934,39 @@ pub fn lexsort(columns: &[SortColumn], limit:
Option<usize>) -> Result<Vec<Array
/// Sort elements lexicographically from a list of `ArrayRef` into an unsigned
integer
/// (`UInt32Array`) of indices.
///
+/// # Example
+///
+/// ```
+/// use std::sync::Arc;
+///
+/// use arrow_array::{ArrayRef, Int32Array, RecordBatch, StringArray};
+/// use arrow_ord::sort::{lexsort_to_indices, SortColumn};
+/// use arrow_select::take::take_record_batch;
+///
+/// let batch = RecordBatch::try_from_iter(vec![
+/// ("a", Arc::new(Int32Array::from(vec![2, 1, 1])) as ArrayRef),
+/// ("b", Arc::new(StringArray::from(vec!["x", "z", "a"])) as ArrayRef),
+/// ])
+/// .unwrap();
+///
+/// let sort_columns = vec![
Review Comment:
```suggestion
/// // Configure sort by (a, b)
/// let sort_columns = vec![
```
##########
arrow-ord/src/sort.rs:
##########
@@ -934,6 +934,39 @@ pub fn lexsort(columns: &[SortColumn], limit:
Option<usize>) -> Result<Vec<Array
/// Sort elements lexicographically from a list of `ArrayRef` into an unsigned
integer
/// (`UInt32Array`) of indices.
///
+/// # Example
+///
+/// ```
+/// use std::sync::Arc;
+///
+/// use arrow_array::{ArrayRef, Int32Array, RecordBatch, StringArray};
+/// use arrow_ord::sort::{lexsort_to_indices, SortColumn};
+/// use arrow_select::take::take_record_batch;
+///
+/// let batch = RecordBatch::try_from_iter(vec![
+/// ("a", Arc::new(Int32Array::from(vec![2, 1, 1])) as ArrayRef),
+/// ("b", Arc::new(StringArray::from(vec!["x", "z", "a"])) as ArrayRef),
+/// ])
+/// .unwrap();
+///
+/// let sort_columns = vec![
+/// SortColumn {
+/// values: batch.column(0).clone(),
+/// options: None,
+/// },
+/// SortColumn {
+/// values: batch.column(1).clone(),
+/// options: None,
+/// },
+/// ];
+///
+/// let indices = lexsort_to_indices(&sort_columns, None).unwrap();
+/// let sorted = take_record_batch(&batch, &indices).unwrap();
Review Comment:
```suggestion
/// // Create new sorted RecordBatch by copying values at indices
/// let sorted = take_record_batch(&batch, &indices).unwrap();
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
