[Dart-dev] DART/branches Revision: 12694

[dart at ucar.edu]

nancy at ucar.edu
2018-06-28 11:19:56 -0600 (Thu, 28 Jun 2018)
376
to the recam branch.  removed slow versions of the sort
routines (why would you ever pick those?); moved the
comments to our normal style; added an additional index
sort routine where the caller provides the compare function
instead of the array.  this allows sorting on things like
arrays of derived types (e.g. observations) where the
comparison might be more complicated.




Modified: DART/branches/recam/assimilation_code/modules/utilities/sort_mod.f90
===================================================================
--- DART/branches/recam/assimilation_code/modules/utilities/sort_mod.f90	2018-06-28 15:40:33 UTC (rev 12693)
+++ DART/branches/recam/assimilation_code/modules/utilities/sort_mod.f90	2018-06-28 17:19:56 UTC (rev 12694)
@@ -4,6 +4,16 @@
 !
 ! $Id$
 
+!> A selection of sorting routines. The simplest version sorts a given array
+!> of values and returns a copy of the array with the items in ascending sorted
+!> order.  This works on integer and real(r8) arrays.
+!> Another version returns an integer index array.  Accessing the original
+!> list using these indices will traverse the array in sorted order.
+!> The final version of the sort routine is similar to the index sort
+!> but a compare routine is supplied by the user, allowing this code
+!> to sort a list of any kinds of items.
+!>
+
 module sort_mod
 
 use     types_mod, only : r8
@@ -12,7 +22,7 @@
 implicit none
 private
 
-public :: slow_sort, slow_index_sort, sort, index_sort
+public :: sort, index_sort
 
 ! version controlled file description for error handling, do not edit
 character(len=256), parameter :: source   = &
@@ -22,22 +32,29 @@
 
 logical, save :: module_initialized = .false.
 
+!> single interface to sort real or integer arrays
+
 interface sort
    module procedure rsort
    module procedure isort
 end interface sort
 
+!> single interface to return indices in sorted order,
+!> leaving the original array in place.
+
 interface index_sort
    module procedure index_sort_real
    module procedure index_sort_int
+   module procedure index_sort_user
 end interface
 
 contains
 
-!=======================================================================
+!-----------------------------------------------------------------------
 
+subroutine initialize_module()
 
-subroutine initialize_module
+if (module_initialized) return
 
    call register_module(source, revision, revdate)
    module_initialized = .true.
@@ -44,84 +61,17 @@
 
 end subroutine initialize_module
 
+!-----------------------------------------------------------------------
 
-!=======================================================================
+!> Uses a heap sort algorithm on real(r8) array x(), returns sorted array.
+!> x() must be allocated or declared to be exactly the intended size; 
+!> all items in x() are sorted.
+!>
+!> @param x the (real) array to sort
+!>
 
-! a silly, inefficient sort for real(r8) array data
-
-function slow_sort(x)
-
-implicit none
-
-real(r8), intent(in) :: x(:)
-real(r8) :: slow_sort(size(x))
-real(r8) :: tmp
-integer j, k
-
-if ( .not. module_initialized ) call initialize_module
-
-! Copy to slow_sort
-slow_sort = x
-
-!  DO A SILLY N^2 SORT
-do j = 1, size(x) - 1
-   do k = j + 1, size(x)
-!  EXCHANGE TWO ELEMENTS IF THEY'RE IN THE WRONG ORDER
-      if(slow_sort(j) .gt. slow_sort(k)) then
-         tmp = slow_sort(k)
-         slow_sort(k) = slow_sort(j)
-         slow_sort(j) = tmp
-      end if