Changed intent of arguments from inout to out

Walter Spector suggested that several arguments to ord_sort and sort_index
from intent(inout) to intent(in). Jeremie Vandenplas agreed and now so do I.
This involved changing the interfaces in src/stdlib_sorting.fypp, the code in
src/stdlib_sorting_ord_sort.fypp and src/stdlib_sorting_index_sort.fypp, and
and the documentation in doc/specs/stdlib_sorting.md.

[ticket: X]

Author: wclodius2

Diff for: doc/specs/stdlib_sorting.md

@@ -228,7 +228,7 @@ of non-decreasing value.
 
 `work` (optional): shall be a rank one array of the same type as
 array, and shall have at least `size(array)/2` elements. It is an
-`intent(inout)` argument. It is intended to be used as "scratch"
+`intent(out)` argument. It is intended to be used as "scratch"
 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.
@@ -370,14 +370,14 @@ array in the desired direction.
 
 `work` (optional): shall be a rank one array of any of the same type as
 `array`, and shall have at least `size(array)/2` elements. It is an
-`intent(inout)` argument. It is intended to be used as "scratch"
+`intent(out)` argument. It is intended to be used as "scratch"
 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.
 
 `iwork` (optional): shall be a rank one integer array of kind
 `int_size`, and shall have at least `size(array)/2` elements. It
-is an `intent(inout)` argument.  It is intended to be used as "scratch"
+is an `intent(out)` argument.  It is intended to be used as "scratch"
 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.
@@ -411,11 +411,11 @@ Sorting a related rank one array:
 ```Fortran
     subroutine sort_related_data( a, b, work, index, iwork )
         ! Sort `a`, and  also  sort `b` to be reorderd the same way as `a`
-        integer, intent(inout)           :: a(:)
-        integer(int32), intent(inout)    :: b(:) ! The same size as a
-		integer(int32), intent(inout)    :: work(:)
-		integer(int_size), intent(inout) :: index(:)
-		integer(int_size), intent(inout) :: iwork(:)
+        integer, intent(inout)         :: a(:)
+        integer(int32), intent(inout)  :: b(:) ! The same size as a
+		integer(int32), intent(out)    :: work(:)
+		integer(int_size), intent(out) :: index(:)
+		integer(int_size), intent(out) :: iwork(:)
 		! Find the indices to sort a
         call sort_index(a, index(1:size(a)),&
             work(1:size(a)/2), iwork(1:size(a)/2))
@@ -429,12 +429,12 @@ Sorting a rank 2 array based on the data in a column
 ```Fortran
 	subroutine sort_related_data( array, column, work, index, iwork )
 	    ! Reorder rows of `array` such that `array(:, column)` is  sorted
-	    integer, intent(inout)           :: array(:,:)
-		integer(int32), intent(in)       :: column
-		integer(int32), intent(inout)    :: work(:)
-		integer(int_size), intent(inout) :: index(:)
-		integer(int_size), intent(inout) :: iwork(:)
-		integer, allocatable             :: dummy(:)
+	    integer, intent(inout)         :: array(:,:)
+		integer(int32), intent(in)     :: column
+		integer(int32), intent(out)    :: work(:)
+		integer(int_size), intent(out) :: index(:)
+		integer(int_size), intent(out) :: iwork(:)
+		integer, allocatable           :: dummy(:)
 		integer :: i
 		allocate(dummy(size(array, dim=1)))
 		! Extract a column of `array`
@@ -456,9 +456,9 @@ Sorting an array of a derived type based on the data in one component
 	    ! Sort `a_data` in terms or its component `a`
 	    type(a_type), intent(inout)      :: a_data(:)
 		integer(int32), intent(inout)    :: a(:)
-		integer(int32), intent(inout)    :: work(:)
-		integer(int_size), intent(inout) :: index(:)
-		integer(int_size), intent(inout) :: iwork(:)
+		integer(int32), intent(out)    :: work(:)
+		integer(int_size), intent(out) :: index(:)
+		integer(int_size), intent(out) :: iwork(:)
 		! Extract a component of `a_data`
 		a(1:size(a_data)) = a_data(:) % a
 		! Find the indices to sort the component

Diff for: src/stdlib_sorting.fypp

@@ -156,7 +156,7 @@ module stdlib_sorting
 !!
 !! * work (optional): shall be a rank 1 array of the same type as
 !!   `array`, and shall have at least `size(array)/2` elements. It is an
-!!   `intent(inout)` argument to be used as "scratch" memory
+!!   `intent(out)` argument to be used as "scratch" 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 value on return is undefined.
@@ -232,21 +232,21 @@ module stdlib_sorting
 !!   of the `array` and `index` results is undefined. Otherwise it is
 !!   defined to be as specified by reverse.
 !!
-!! * index: a rank 1 array of sorting indices. It is an `intent(inout)`
+!! * index: a rank 1 array of sorting indices. It is an `intent(out)`
 !!   argument of the type `integer(int_size)`. Its size shall be the
 !!   same as `array`. On return, if defined, its elements would
 !!   sort the input `array` in the direction specified by `reverse`.
 !!
 !! * work (optional): shall be a rank 1 array of the same type as
 !!   `array`, and shall have at least `size(array)/2` elements. It is an
-!!   `intent(inout)` argument to be used as "scratch" memory
+!!   `intent(out)` argument to be used as "scratch" 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 value on return is undefined.
 !!
 !! * iwork (optional): shall be a rank 1 integer array of kind `int_size`,
 !!   and shall have at least `size(array)/2` elements. It is an
-!!   `intent(inout)` argument to be used as "scratch" memory
+!!   `intent(out)` argument to be used as "scratch" 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 value on return is undefined.
@@ -264,11 +264,11 @@ module stdlib_sorting
 !!```Fortran
 !!    subroutine sort_related_data( a, b, work, index, iwork )
 !!        ! Sort `b` in terms or its related array `a`
-!!        integer, intent(inout)           :: a(:)
-!!        integer(int32), intent(inout)    :: b(:) ! The same size as a
-!!        integer(int32), intent(inout)    :: work(:)
-!!        integer(int_size), intent(inout) :: index(:)
-!!        integer(int_size), intent(inout) :: iwork(:)
+!!        integer, intent(inout)         :: a(:)
+!!        integer(int32), intent(inout)  :: b(:) ! The same size as a
+!!        integer(int32), intent(out)    :: work(:)
+!!        integer(int_size), intent(out) :: index(:)
+!!        integer(int_size), intent(out) :: iwork(:)
 !!    ! Find the indices to sort a
 !!        call sort_index(a, index(1:size(a)),&
 !!            work(1:size(a)/2), iwork(1:size(a)/2))
@@ -282,12 +282,12 @@ module stdlib_sorting
 !!```Fortran
 !!    subroutine sort_related_data( array, column, work, index, iwork )
 !!    ! Sort `a_data` in terms or its component `a`
-!!        integer, intent(inout)           :: a(:,:)
-!!        integer(int32), intent(in)       :: column
-!!        integer(int32), intent(inout)    :: work(:)
-!!        integer(int_size), intent(inout) :: index(:)
-!!        integer(int_size), intent(inout) :: iwork(:)
-!!        integer, allocatable             :: dummy(:)
+!!        integer, intent(inout)         :: a(:,:)
+!!        integer(int32), intent(in)     :: column
+!!        integer(int32), intent(out)    :: work(:)
+!!        integer(int_size), intent(out) :: index(:)
+!!        integer(int_size), intent(out) :: iwork(:)
+!!        integer, allocatable           :: dummy(:)
 !!        integer :: i
 !!        allocate(dummy(size(a, dim=1)))
 !!    ! Extract a component of `a_data`
@@ -306,11 +306,11 @@ module stdlib_sorting
 !!```fortran
 !!    subroutine sort_a_data( a_data, a, work, index, iwork )
 !!    ! Sort `a_data` in terms or its component `a`
-!!        type(a_type), intent(inout)      :: a_data(:)
-!!        integer(int32), intent(inout)    :: a(:)
-!!        integer(int32), intent(inout)    :: work(:)
-!!        integer(int_size), intent(inout) :: index(:)
-!!        integer(int_size), intent(inout) :: iwork(:)
+!!        type(a_type), intent(inout)    :: a_data(:)
+!!        integer(int32), intent(inout)  :: a(:)
+!!        integer(int32), intent(out)    :: work(:)
+!!        integer(int_size), intent(out) :: index(:)
+!!        integer(int_size), intent(out) :: iwork(:)
 !!    ! Extract a component of `a_data`
 !!        a(1:size(a_data)) = a_data(:) % a
 !!    ! Find the indices to sort the component
@@ -341,8 +341,8 @@ module stdlib_sorting
 !!
 !! `${k1}$_ord_sort( array )` sorts the input `ARRAY` of type `${t1}$`
 !! using a hybrid sort based on the `'Rust" sort` algorithm found in `slice.rs`
-            ${t1}$, intent(inout)           :: array(0:)
-            ${t1}$, intent(inout), optional :: work(0:)
+            ${t1}$, intent(inout)         :: array(0:)
+            ${t1}$, intent(out), optional :: work(0:)
         end subroutine ${k1}$_ord_sort
 
 #:endfor
@@ -352,8 +352,8 @@ module stdlib_sorting
 !!
 !! `char_ord_sort( array )` sorts the input `ARRAY` of type `CHARACTER(*)`
 !! using a hybrid sort based on the `'Rust" sort` algorithm found in `slice.rs`
-            character(len=*), intent(inout)                    :: array(0:)
-            character(len=len(array)), intent(inout), optional :: work(0:)
+            character(len=*), intent(inout)                  :: array(0:)
+            character(len=len(array)), intent(out), optional :: work(0:)
         end subroutine char_ord_sort
 
     end interface ord_sort
@@ -411,11 +411,11 @@ module stdlib_sorting
 !! using a hybrid sort based on the `'Rust" sort` algorithm found in `slice.rs`
 !! and returns the sorted `ARRAY` and an array `INDEX of indices in the
 !! order that would sort the input `ARRAY` in the desired direction.
-            ${t1}$, intent(inout)                      :: array(0:)
-            integer(int_size), intent(inout)           :: index(0:)
-            ${t1}$, intent(inout), optional            :: work(0:)
-            integer(int_size), intent(inout), optional :: iwork(0:)
-            logical, intent(in), optional              :: reverse
+            ${t1}$, intent(inout)                    :: array(0:)
+            integer(int_size), intent(out)           :: index(0:)
+            ${t1}$, intent(out), optional            :: work(0:)
+            integer(int_size), intent(out), optional :: iwork(0:)
+            logical, intent(in), optional            :: reverse
         end subroutine ${k1}$_sort_index
 
 #:endfor
@@ -428,11 +428,11 @@ module stdlib_sorting
 !! using a hybrid sort based on the `'Rust" sort` algorithm found in `slice.rs`
 !! and returns the sorted `ARRAY` and an array `INDEX of indices in the
 !! order that would sort the input `ARRAY` in the desired direction.
-            character(len=*), intent(inout)                    :: array(0:)
-            integer(int_size), intent(inout)                   :: index(0:)
-            character(len=len(array)), intent(inout), optional :: work(0:)
-            integer(int_size), intent(inout), optional         :: iwork(0:)
-            logical, intent(in), optional                      :: reverse
+            character(len=*), intent(inout)                  :: array(0:)
+            integer(int_size), intent(out)                   :: index(0:)
+            character(len=len(array)), intent(out), optional :: work(0:)
+            integer(int_size), intent(out), optional         :: iwork(0:)
+            logical, intent(in), optional                    :: reverse
         end subroutine char_sort_index
 
     end interface sort_index

Diff for: src/stdlib_sorting_ord_sort.fypp

@@ -78,8 +78,8 @@ contains
 ! estimation of the optimal `run size` as suggested in Tim Peters'
 ! original `listsort.txt`, and an optional `work` array to be used as
 ! scratch memory.
-        ${t1}$, intent(inout)           :: array(0:)
-        ${t1}$, intent(inout), optional :: work(0:)
+        ${t1}$, intent(inout)         :: array(0:)
+        ${t1}$, intent(out), optional :: work(0:)
 
         ${t1}$, allocatable :: buf(:)
         integer(int_size) :: array_size
@@ -417,8 +417,8 @@ contains
 ! estimation of the optimal `run size` as suggested in Tim Peters'
 ! original `listsort.txt`, and an optional `work` array to be used as
 ! scratch memory.
-        character(len=*), intent(inout)                    :: array(0:)
-        character(len=len(array)), intent(inout), optional :: work(0:)
+        character(len=*), intent(inout)                  :: array(0:)
+        character(len=len(array)), intent(out), optional :: work(0:)
 
         character(len=:), allocatable :: buf(:)
         integer(int_size) :: array_size

Diff for: src/stdlib_sorting_sort_index.fypp

@@ -83,11 +83,11 @@ contains
 ! original listsort.txt, and the optional `work` and `iwork` arraya to be
 ! used as scratch memory.
 
-        ${t1}$, intent(inout)                      :: array(0:)
-        integer(int_size), intent(inout)           :: index(0:)
-        ${t1}$, intent(inout), optional            :: work(0:)
-        integer(int_size), intent(inout), optional :: iwork(0:)
-        logical, intent(in), optional              :: reverse
+        ${t1}$, intent(inout)                    :: array(0:)
+        integer(int_size), intent(out)           :: index(0:)
+        ${t1}$, intent(out), optional            :: work(0:)
+        integer(int_size), intent(out), optional :: iwork(0:)
+        logical, intent(in), optional            :: reverse
 
         integer(int_size) :: array_size, i, stat
         ${t1}$, allocatable :: buf(:)
@@ -490,11 +490,11 @@ contains
 ! original listsort.txt, and the optional `work` and `iwork` arraya to be
 ! used as scratch memory.
 
-        character(len=*), intent(inout)                      :: array(0:)
-        integer(int_size), intent(inout)                     :: index(0:)
-        character(len=len(array)), intent(inout), optional   :: work(0:)
-        integer(int_size), intent(inout), optional           :: iwork(0:)
-        logical, intent(in), optional                        :: reverse
+        character(len=*), intent(inout)                    :: array(0:)
+        integer(int_size), intent(out)                     :: index(0:)
+        character(len=len(array)), intent(out), optional   :: work(0:)
+        integer(int_size), intent(out), optional           :: iwork(0:)
+        logical, intent(in), optional                      :: reverse
 
         integer(int_size) :: array_size, i, stat
         character(len=:), allocatable :: buf(:)