add is_sorted tests and optimize sorting suite

doc/specs/stdlib_sorting.md

@@ -24,10 +24,9 @@ module's `string_type` type.
 
 ## Overview of the module
 
-The module `stdlib_sorting` defines several public entities, two
-default integer parameters, `int_index` and `int_index_low`, and four overloaded
-subroutines: `ORD_SORT`, `SORT`, `RADIX_SORT` and `SORT_INDEX`. The
-overloaded subroutines also each have several specific names for
+default integer parameters, `int_index` and `int_index_low`, and five overloaded
+procedures: `ORD_SORT`, `SORT`, `RADIX_SORT`, `SORT_INDEX`, and `IS_SORTED`. The
+overloaded procedures also each have several specific names for
 versions corresponding to different types of array arguments.
 
 ### The parameters `int_index` and `int_index_low`
@@ -57,6 +56,7 @@ data:
   that are effectively unordered before the sort;
 * `RADIX_SORT` is intended to sort fixed width intrinsic data 
   types (integers and reals).
+* `IS_SORTED` is a utility function to check if an array is already sorted, returning a logical scalar.  
 
 #### Licensing
 
@@ -624,6 +624,44 @@ Sorting an array of a derived type based on the data in one component
         ! Sort a_data based on the sorting of that component
         a_data(:) = a_data( index(1:size(a_data)) )
     end subroutine sort_a_data
+    #### `is_sorted` - checks if an input array is sorted
+
+##### Status
+
+Experimental
+
+##### Description
+
+Returns a logical scalar indicating whether the input `array` is sorted in order of increasing, or decreasing, value.
+
+##### Syntax
+
+`result = ` [[stdlib_sorting(module):is_sorted(interface)]] `( array[, reverse] )`
+
+##### Class
+
+Pure generic function.
+
+##### Arguments
+
+`array` : shall be a rank one array of any of the types:
+`integer(int8)`, `integer(int16)`, `integer(int32)`, `integer(int64)`,
+`real(sp)`, `real(dp)`, `real(qp)`, `character(*)`, `type(string_type)`,
+`type(bitset_64)`, or `type(bitset_large)`.
+It is an `intent(in)` argument. 
+
+`reverse` (optional): shall be a scalar of type default logical. It
+is an `intent(in)` argument. If present with a value of `.true.`, the function
+will check if `array` is sorted in order of non-increasing values. Otherwise, it will check if `array` is sorted in order of non-decreasing values.
+
+##### Return Value
+
+The result is a scalar of type default logical. It returns `.true.` if the array is sorted according to the requested order, and `.false.` otherwise. Returns `.true.` for arrays of size 0 or 1. If `array` is of any type `REAL` and contains a `NaN`, the result is `.false.`.
+
+##### Example
+
+```fortran
+{!example/sorting/example_is_sorted.f90!}
 ```
 
 

src/sorting/stdlib_sorting.fypp

@@ -479,6 +479,16 @@ module stdlib_sorting
 !!    end subroutine sort_a_data
 !!```
 
+    public is_sorted
+!! Version: experimental
+!!
+!! The generic function `is_sorted` checks whether an input array is sorted 
+!! in order of (non-)decreasing value. Its use has the syntax:
+!!
+!!     result = is_sorted( array[, reverse] )
+!!
+!! ([Specification](../page/specs/stdlib_sorting.html#is_sorted-checks-if-an-input-array-is-sorted))
+
     interface ord_sort
 !! Version: experimental
 !!
@@ -512,6 +522,7 @@ module stdlib_sorting
 #:endfor
 
     end interface ord_sort
+
     interface radix_sort
 !! Version: experimental
 !!
@@ -653,6 +664,21 @@ module stdlib_sorting
 
     end interface sort_index
 
+    interface is_sorted
+!! Version: experimental
+!!
+!! The generic function interface for `IS_SORTED`. Checks if an array 
+!! is sorted in the specified direction.
+
+#:for t1, t2, name1, cpp1 in IRSCB_TYPES_ALT_NAME
+#:block generate_cpp(cpp_var=cpp1)
+        module procedure ${name1}$_is_sorted
+#:endblock
+#:endfor
+
+    end interface is_sorted
+
+
 contains
 
 #:for ki, ti, namei in INT_INDEX_TYPES_ALT_NAME
@@ -698,4 +724,44 @@ contains
 #:endfor
 
 
-end module stdlib_sorting
+#:for t1, t2, name1, cpp1 in IRSCB_TYPES_ALT_NAME
+#:block generate_cpp(cpp_var=cpp1)
+    pure function ${name1}$_is_sorted( array, reverse ) result(sorted)
+!! Version: experimental
+!!
+!! Checks if the input `ARRAY` of type `${t1}$` is sorted.
+        ${t1}$, intent(in) :: array(0:)
+        logical, intent(in), optional :: reverse
+        logical :: sorted
+
+        integer(int_index) :: i
+        logical :: is_rev
+
+        is_rev = optval(reverse, .false.)
+        sorted = .true.
+
+        if (size(array) <= 1) return
+
+        if (is_rev) then
+            do i = 1, size(array, kind=int_index) - 1
+                ! Using `<` for descending check. If previous is strictly less than current, it's not sorted descending.
+                if (array(i-1) < array(i)) then
+                    sorted = .false.
+                    return
+                end if
+            end do
+        else
+            do i = 1, size(array, kind=int_index) - 1
+                ! Using `>` for ascending check. If previous is strictly greater than current, it's not sorted ascending.
+                if (array(i-1) > array(i)) then
+                    sorted = .false.
+                    return
+                end if
+            end do
+        end if
+    end function ${name1}$_is_sorted
+
+#:endblock
+#:endfor
+
+end module stdlib_sorting