ISORTX, SSORTX, and DSORTX (Sort the Elements of a Sequence and Note the Original Element Positions)
Purpose
These subroutines sort the elements of sequence x. The original positions of the elements in sequence x are returned in the indices array, INDX
. Where equal elements
occur in the input sequence, they do not necessarily remain in the same relative
order in the output sequence.
Data Types | |
---|---|
x | Subroutine |
Integer | ISORTX |
Short-precision real | SSORTX |
Long-precision real | DSORTX |
Syntax
Language | Syntax |
---|---|
Fortran | CALL ISORTX | SSORTX | DSORTX (x, incx, n, indx) |
C and C++ | isortx | ssortx | dsortx (x, incx, n, indx); |
- On Entry
- x
- is the sequence x of length n,
to be sorted.
Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx| elements, containing numbers of the data type indicated in Table 1.
- incx
- is the stride for both the input sequence x and the output sequence x. If it is positive,
elements are sorted into ascending order in the array, and if it is negative,
elements are sorted into descending order in the array.
Specified as: an integer. It can have any value.
- n
- is the number of elements in sequence x. Specified as: an integer; n ≥ 0.
- indx
- See On Return.
- On Return
- x
- is the sequence x of length n, with its elements sorted into designated order in the array. Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 1.
- indx
- is the array, referred to as
INDX
, containing the n indices that indicate, for the elements in the sorted output sequence, the original positions of those elements in input sequence x.Note: It is important to remember that when you specify a negative stride, ESSL assumes that the order of the input and output sequence elements in theX
array is reversed; however, the elements inINDX
are not reversed. See Function.Returned as: a one-dimensional array of length n, containing integers; 1 ≤ (
INDX
elements) ≤ n.
Function
The elements of input sequence x are sorted into ascending order, in place and using a partition sort. The elements of output sequence x can be expressed as follows:
Where equal elements occur in the input sequence, they do not necessarily remain in the same relative order in the output sequence.
By specifying a negative stride for x, the elements of input sequence x are assumed to be reversed in the array, (xn, xn-1, … , x1), thus producing a sort into descending order within the array.
In addition, the INDX
array contains the n indices
that indicate, for the elements in the sorted output sequence, the original
positions of those elements in input sequence x.
(These are not the positions in the array, but rather the positions in the
sequence.) For each element xj in
the input sequence, becoming element xxk in the output sequence, the elements in INDX
are defined
as follows:
INDX
(k) = j for j = 1, n and k = 1, nwhere xxk = xj
To understand INDX
when you specify a negative stride, you should
remember that both the input and output sequences, x, are assumed to be in reverse order in array X
, but INDX
is not affected by stride. The sequence elements of x are assumed to be stored in your input array as follows:
X
= (xn, xn-1, … , x1)The sequence elements of x are stored in your output array by ESSL as follows:
X
= (xxn, xxn-1, … , xx1)where the elements xxk are
the elements xj, sorted into
descending order in X
. As an example of how INDX
is
calculated, if xx1 = xn-1, then INDX
(1) = n-1.
If n is 0, no computation is performed. See reference [91].
Error conditions
- Resource Errors
- Unable to allocate internal work area.
- Computational Errors
- None
- Input-Argument Errors
- n < 0
Examples
- Example 1
-
This example shows how to sort a sequence x into ascending order by specifying a positive stride.
Call Statement and Input:
X INCX N INDX | | | | CALL ISORTX( X , 2 , 5 , INDX ) X = (2, . , -1, . , 5, . , 1, . , -2)
Output:
X = (-2, . , -1, . , 1, . , 2, . , 5) INDX = (5, 2, 4, 1, 3)
- Example 2
-
This example shows how to sort a sequence x into descending order by specifying a negative stride. Therefore, both the input and output sequences are assumed to be reversed in the array
X
. The input sequence is assumed to be stored as follows:X
= (x5, x4, x3, x2, x1) =(2, -1, 5, 1, -2)
The output sequence is stored by ESSL as follows:
X
= (xx5, xx4, xx3, xx2, xx1) =(5, 2, 1, -1, -2)
As a result,
INDX
is defined as follows:INDX
= (indx1, indx2, indx3, indx4, indx5) =(1, 4, 2, 5, 3)
For example, because output sequence element xx4 = 2 is input sequence element x5, then
INDX
(4) = 5.Call Statement and Input:
X INCX N INDX | | | | CALL ISORTX( X , -1 , 5 , INDX ) X = (2, -1, 5, 1, -2)
Output:
X = (5, 2, 1, -1, -2) INDX = (1, 4, 2, 5, 3)