Skip to content

Update of the specs for stdlib_sorting #3

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 30, 2021
Merged

Update of the specs for stdlib_sorting #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6c4d3e2
update specs
jvdp1 May 29, 2021
18ad979
sort_sign: removed bold sentences
jvdp1 May 30, 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
69 changes: 35 additions & 34 deletions doc/specs/stdlib_sorting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,12 @@ data:

The Fortran Standard Library is distributed under the MIT
License. However components of the library may be based on code with
additional licensing restriction. In particular `ORD_SORT`,
additional licensing restrictions. In particular `ORD_SORT`,
`SORT_INDEX`, and `SORT` are translations of codes with their
own distribution restrictions.

The `ORD_SORT` and `SORT_INDEX` subroutines are essentially
translations to Fortran 2008 of the `"rust" sort` of the Rust Language
translations to Fortran 2008 of the `"Rust" sort` of the Rust Language
distributed as part of
[`slice.rs`](https://github.com/rust-lang/rust/blob/90eb44a5897c39e3dff9c7e48e3973671dcd9496/src/liballoc/slice.rs).
The header of the `slice.rs` file has as its licensing requirements:
Expand All @@ -75,7 +75,7 @@ The header of the `slice.rs` file has as its licensing requirements:
option. This file may not be copied, modified, or distributed
except according to those terms.

so the license for the `slice.rs` code is compatible with the use of
So the license for the `slice.rs` code is compatible with the use of
modified versions of the code in the Fortran Standard Library under
the MIT license.

Expand Down Expand Up @@ -108,17 +108,16 @@ performance than `SORT` on partially sorted data, having O(N)
performance on uniformly increasing or decreasing data.


`ORD_SORT` begins by traversing the array starting in its tail
attempting to identify `runs` in the array, where a run is either a
uniformly decreasing sequence, `ARRAY(i-1) > ARRAY(i)`, or a
non-decreasing, `ARRAY(i-1) <= ARRAY(i)`, sequence. First delimitated
decreasing sequences are reversed in their order. Then, if the
sequence has less than `MIN_RUN` elements, previous elements in the
array are added to the run using `insertion sort` until the run
contains `MIN_RUN` elements or the array is completely processed. As
each run is identified the start and length of the run
are then pushed onto a stack and the stack is then processed using
`merge` until it obeys the stack invariants:
When sorting in an increasing order, `ORD_SORT` begins by traversing the array
starting in its tail attempting to identify `runs` in the array, where a run is
either a uniformly decreasing sequence, `ARRAY(i-1) > ARRAY(i)`, or a
non-decreasing, `ARRAY(i-1) <= ARRAY(i)`, sequence. First delimited decreasing
sequences are reversed in their order. Then, if the sequence has less than
`MIN_RUN` elements, previous elements in the array are added to the run using
`insertion sort` until the run contains `MIN_RUN` elements or the array is
completely processed. As each run is identified the start and length of the run
are then pushed onto a stack and the stack is then processed using `merge` until
it obeys the stack invariants:

1. len(i-2) > len(i-1) + len(i)
2. len(i-1) > len(i)
Expand All @@ -134,6 +133,9 @@ structured data. As a modified `merge sort`, `ORD_SORT` requires the
use of a "scratch" array, that may be provided as an optional `work`
argument or allocated internally on the stack.

Arrays can be also sorted in a decreasing order by providing the argument `reverse
= .true.`.

#### The `SORT_INDEX` subroutine

The `SORT` and `ORD_SORT` subroutines can sort rank 1 isolated
Expand Down Expand Up @@ -205,11 +207,11 @@ Experimental
##### Description

Returns an input `array` with the elements sorted in order of
increasing value.
increasing, or decreasing, value.

##### Syntax

`call [[stdlib_sorting(module):ord_sort(subroutine)]]ord_sort ( array[, work ] )`
`call [[stdlib_sorting(module):ord_sort(subroutine)]]ord_sort ( array[, work, reverse ] )`

##### Class

Expand All @@ -233,6 +235,12 @@ memory for internal record keeping. If associated with an array in
static storage, its use can significantly reduce the stack memory
requirements for the code. Its contents on return are undefined.

`reverse` (optional): shall be a scalar of type default logical. It
is an `intent(in)` argument. If present with a value of `.true.` then
`array` will be sorted in order of non-increasing values in stable
order. Otherwise index will sort `array` in order of non-decreasing
values in stable order.

##### Notes

`ORD_SORT` implements a hybrid sorting algorithm combining
Expand All @@ -246,26 +254,12 @@ non-decreasing arrays. The optional `work` array replaces "scratch"
memory that would otherwise be allocated on the stack. If `array` is of
any type `REAL` the order of its elements on return undefined if any
element of `array` is a `NaN`. Sorting of `CHARACTER(*)` and
`STRING_TYPE` arrays are based on the operator `>`, and not on the
`STRING_TYPE` arrays are based on the operators `>` and `<`, and not on the
function `LGT`.


##### Example

```fortran
...
! Read arrays from sorted files
call read_sorted_file( 'dummy_file1', array1 )
call read_sorted_file( 'dummy_file2', array2 )
! Concatenate the arrays
array = [ array1, array2 ]
! Sort the resulting array
call ord_sort( array, work )
! Process the sorted array
call array_search( array, values )
...
```

```fortran
program demo_ord_sort
use stdlib_sorting, only: ord_sort
Expand All @@ -287,12 +281,12 @@ Experimental

##### Description

Returns an input array with the elements sorted in order of increasing
value.
Returns an input array with the elements sorted in order of increasing, or
decreasing, value.

##### Syntax

`call [[stdlib_sorting(module):sort(subroutine)]]sort ( array )`
`call [[stdlib_sorting(module):sort(subroutine)]]sort ( array, reverse )`

##### Class

Expand All @@ -306,6 +300,13 @@ Pure generic subroutine.
`type(string_type)`. It is an `intent(inout)` argument. On return its
input elements will be sorted in order of non-decreasing value.


`reverse` (optional): shall be a scalar of type default logical. It
is an `intent(in)` argument. If present with a value of `.true.` then
`array` will be sorted in order of non-increasing values in unstable
order. Otherwise index will sort `array` in order of non-decreasing
values in unstable order.

##### Notes

`SORT` implements a hybrid sorting algorithm combining
Expand Down