DPSORT(3)

SYNOPSIS
SUBROUTINE DPSORT (DX, N, IPERM, KFLAG, IER)

NAME
dpsort - Return the permutation vector generated by sorting a given array and, optionally, rearrange the elements of the array. The array may be sorted in increasing or decreasing order. A slightly modified quicksort algorithm is used.

LIBRARY
SLATEC

CATEGORY
N6A1B, N6A2B

TYPE
DOUBLE PRECISION (SPSORT-S, DPSORT-D, IPSORT-I, HPSORT-H)

KEYWORDS
NUMBER SORTING, PASSIVE SORTING, SINGLETON QUICKSORT, SORT

AUTHOR
Jones, R. E., (SNLA) Rhoads, G. S., (NBS) Wisniewski, J. A., (SNLA)

DESCRIPTION
DPSORT returns the permutation vector IPERM generated by sorting the array DX and, optionally, rearranges the values in DX. DX may be sorted in increasing or decreasing order. A slightly modified quicksort algorithm is used. IPERM is such that DX(IPERM(I)) is the Ith value in the rearrangement of DX. IPERM may be applied to another array by calling IPPERM, SPPERM, DPPERM or HPPERM. The main difference between DPSORT and its active sorting equivalent DSORT is that the data are referenced indirectly rather than directly. Therefore, DPSORT should require approximately twice as long to execute as DSORT. However, DPSORT is more general. Description of Parameters DX - input/output -- double precision array of values to be sorted. If ABS(KFLAG) = 2, then the values in DX will be rearranged on output; otherwise, they are unchanged. N - input -- number of values in array DX to be sorted. IPERM - output -- permutation array such that IPERM(I) is the index of the value in the original order of the DX array that is in the Ith location in the sorted order. KFLAG - input -- control parameter: = 2 means return the permutation vector resulting from sorting DX in increasing order and sort DX also. = 1 means return the permutation vector resulting from sorting DX in increasing order and do not sort DX. = -1 means return the permutation vector resulting from sorting DX in decreasing order and do not sort DX. = -2 means return the permutation vector resulting from sorting DX in decreasing order and sort DX also. IER - output -- error indicator: = 0 if no error, = 1 if N is zero or negative, = 2 if KFLAG is not 2, 1, -1, or -2.

REFERENCES
R. C. Singleton, Algorithm 347, An efficient algorithm for sorting with minimal storage, Communications of the ACM, 12, 3 (1969), pp. 185-187.

ROUTINES CALLED
XERMSG

REVISION HISTORY (YYMMDD)
761101 DATE WRITTEN
761118 Modified by John A. Wisniewski to use the Singleton quicksort algorithm.
870423 Modified by Gregory S. Rhoads for passive sorting with the option for the rearrangement of the original data.
890619 Double precision version of SPSORT created by D. W. Lozier.
890620 Algorithm for rearranging the data vector corrected by R. Boisvert.
890622 Prologue upgraded to Version 4.0 style by D. Lozier.
891128 Error when KFLAG.LT.0 and N=1 corrected by R. Boisvert.
920507 Modified by M. McClain to revise prologue text.
920818 Declarations section rebuilt and code restructured to use IF-THEN-ELSE-ENDIF. (SMR, WRB)