This section contains the sorting and searching subroutine descriptions.
These subroutines sort the elements of sequence x.
| x | Subroutine |
| Integer | ISORT |
| Short-precision real | SSORT |
| Long-precision real | DSORT |
| Fortran | CALL ISORT | SSORT | DSORT (x, incx, n) |
| C and C++ | isort | ssort | dsort (x, incx, n); |
| PL/I | CALL ISORT | SSORT | DSORT (x, incx, n); |
Specified as: a fullword integer. It can have any value.
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:
By specifying a negative stride for sequence x, the elements of sequence x are assumed to be reversed in the array, (xn, xn-1, ... , x1), thus producing a sort into descending order within the array. If n is 0 or 1 or if incx is 0, no sort is performed. See reference [69].
Unable to allocate internal work area.
None
n < 0
This example shows a sequence x with a positive stride.
X INCX N
| | |
CALL ISORT( X , 2 , 5 )
X = (2, . , -1, . , 5, . , 4, . , -2)
X = (-2, . , -1, . , 2, . , 4, . , 5)
This example shows a sequence x with a negative stride.
X INCX N
| | |
CALL ISORT( X , -1 , 5 )
X = (2, -1, 5, 4, -2)
X = (5, 4, 2, -1, -2)
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.
| Note: | If you need a stable sort, you should use ISORTS, SSORTS, or DSORTS rather than these subroutines. |
| x | Subroutine |
| Integer | ISORTX |
| Short-precision real | SSORTX |
| Long-precision real | DSORTX |
| Fortran | CALL ISORTX | SSORTX | DSORTX (x, incx, n, indx) |
| C and C++ | isortx | ssortx | dsortx (x, incx, n, indx); |
| PL/I | CALL ISORTX | SSORTX | DSORTX (x, incx, n, indx); |
Specified as: a fullword integer. It can have any value.
| 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 the X array is reversed; however, the elements in INDX are not reversed. See "Function". |
Returned as: a one-dimensional array of length n, containing fullword integers; 1 <= (INDX elements) <= n.
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:
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:
The sequence elements of x are stored in your output array by ESSL as follows:
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 [69].
Unable to allocate internal work area.
None
n < 0
This example shows how to sort a sequence x into ascending order by specifying a positive stride.
X INCX N INDX
| | | |
CALL ISORTX( X , 2 , 5 , INDX )
X = (2, . , -1, . , 5, . , 1, . , -2)
X = (-2, . , -1, . , 1, . , 2, . , 5) INDX = (5, 2, 4, 1, 3)
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:
The output sequence is stored by ESSL as follows:
As a result, INDX is defined as follows:
For example, because output sequence element xx4 = 2 is input sequence element x5, then INDX(4) = 5.
X INCX N INDX
| | | |
CALL ISORTX( X , -1 , 5 , INDX )
X = (2, -1, 5, 1, -2)
X = (5, 2, 1, -1, -2) INDX = (1, 4, 2, 5, 3)
These subroutines sort the elements of sequence x using a stable sort; that is, where equal elements occur in the input sequence, they remain in the same relative order in the output sequence. The original positions of the elements in sequence x are returned in the indices array INDX.
| Note: | If you need a stable sort, then you should use these subroutines rather than ISORTX, SSORTX, or DSORTX. |
| x, work | Subroutine |
| Integer | ISORTS |
| Short-precision real | SSORTS |
| Long-precision real | DSORTS |
| Fortran | CALL ISORTS | SSORTS | DSORTS (x, incx, n, indx, work, lwork) |
| C and C++ | isorts | ssorts | dsorts (x, incx, n, indx, work, lwork); |
| PL/I | CALL ISORTS | SSORTS | DSORTS (x, incx, n, indx, work, lwork); |
Specified as: a fullword integer. It can have any value.
| Note: | This is the value to achieve optimal performance. The sort is performed regardless of the value you specify for lwork, but you may receive an attention message. |
| 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 the X array is reversed; however, the elements in INDX are not reversed. See "Function". |
Returned as: a one-dimensional array of length n, containing fullword integers; 1 <= (INDX elements) <= n.
The elements of input sequence x are sorted into ascending order using a partition sort. The sorting is stable; that is, where equal elements occur in the input sequence, they remain in the same relative order in the output sequence. The elements of output sequence x can be expressed as follows:
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:
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:
The sequence elements of x are stored in your output array by ESSL as follows:
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 references [28] and [69].
Unable to allocate internal work area.
None
n < 0
This example shows how to sort a sequence x into ascending order by specifying a positive stride. Because this is a stable sort, the -1 elements remain in the same relative order in the output sequence, indicated by INDX(2) = 2 and INDX(3) = 4.
X INCX N INDX WORK LWORK
| | | | | |
CALL ISORTS( X , 2 , 5 , INDX , WORK , 5 )
X = (2, . , -1, . , 5, . , -1, . , -2)
X = (-2, . , -1, . , -1, . , 2, . , 5) INDX = (5, 2, 4, 1, 3)
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:
The output sequence is stored by ESSL as follows:
As a result, INDX is defined as follows:
For example, because output sequence element xx4 = 2 is input sequence element x5, then INDX(4) = 5. Also, because this is a stable sort, the -1 elements remain in the same relative order in the output sequence, indicated by INDX(2) = 2 and INDX(3) = 4.
X INCX N INDX WORK LWORK
| | | | | |
CALL ISORTS( X , -1 , 5 , INDX , WORK , 5 )
X = (2, -1, 5, -1, -2)
X = (5, 2, -1, -1, -2) INDX = (1, 2, 4, 5, 3)
These subroutines perform a binary search for the locations of the elements
of sequence x in another sequence y, where y
has been sorted into ascending order. The first occurrence of each element is
found. When an exact match is not found, the position of the next larger
element in y is indicated. The locations are returned in the
indices array INDX, and, optionally, return codes indicating
whether the exact elements were found are returned in array RC.
| x, y | Subroutine |
| Integer | IBSRCH |
| Short-precision real | SBSRCH |
| Long-precision real | DBSRCH |
| Fortran | CALL IBSRCH | SBSRCH | DBSRCH (x, incx, n, y, incy, m, indx, rc, iopt) |
| C and C++ | ibsrch | sbsrch | dbsrch (x, incx, n, y, incy, m, indx, rc, iopt); |
| PL/I | CALL IBSRCH | SBSRCH | DBSRCH (x, incx, n, y, incy, m, indx, rc, iopt); |
| Note: | Be careful in specifying the stride for sequence y. A negative stride reverses the direction of the search, because the order of the sequence elements is reversed in the array. |
Specified as: a one-dimensional array of (at least) length 1+(m-1)|incy|, containing numbers of the data type indicated in Table 147.
If iopt = 0, the rc argument is not used in the computation.
If iopt = 1, the rc argument is used in the computation.
Specified as: a fullword integer; iopt = 0 or 1.
Returned as: a one-dimensional array of length n, containing fullword integers; 1 <= (INDX elements) <= m+1.
If iopt = 0, then rc is not used, and its contents remain unchanged.
If iopt = 1, it is the array, referred to as RC, containing the n return codes that indicate whether the elements in sequence x were found in sequence y. For i = 1, n, elements RC(i) = 0 if xi matches an element in sequence y, and RC(i) = 1 if an exact match is not found in sequence y.
Returned as: a one-dimensional array of length n, containing fullword integers; RC(i) = 0 or 1.
These subroutines perform a binary search for the first occurrence (or last occurrence, using negative stride) of the locations of the elements of sequence x in another sequence y, where y must be sorted into ascending order before calling this subroutine. The first occurrence of each element is found. Two arrays are returned, containing the results of the binary searches:
The results returned for the INDX and RC arrays are expressed as follows:
where:
See reference [69]. If n is 0, no search is performed. If m is 0, then:
It is important to note that a negative stride for sequence y reverses the direction of the search, because the order of the sequence elements is reversed in the array. For more details on sorting sequences, see "Function".
None
This example shows a search where sequences x and y have positive strides, and where the optional return codes are returned as part of the output.
X INCX N Y INCY M INDX RC IOPT
| | | | | | | | |
CALL IBSRCH( X , 2 , 5 , Y , 1 , 10 , INDX , RC , 1 )
X = (-3, . , 125, . , 30, . , 20, . , 70)
Y = (10, 20, 30, 30, 40, 50, 60, 80, 90, 100)
INDX = (1, 11, 3, 2, 8) RC = (1, 1, 0, 0, 1)
This example shows the same calling sequence as in Example 1, except that it includes the IOPT argument, specified as 1. This is equivalent to using the calling sequence in Example 1 and gives the same results.
X INCX N Y INCY M INDX RC IOPT
| | | | | | | | |
CALL IBSRCH( X , 2 , 5 , Y , 1 , 10 , INDX , RC , 1 )
This example shows a search where sequence x has a negative stride, and sequence y has a positive stride. The optional return codes are not requested, because IOPT is specified as 0.
X INCX N Y INCY M INDX RC IOPT
| | | | | | | | |
CALL IBSRCH( X , -2 , 5 , Y , 1 , 10 , INDX , RC , 0 )
X = (-3, . , 125, . , 30, . , 20, . , 70)
Y = (10, 20, 30, 30, 40, 50, 60, 80, 90, 100)
INDX = (8, 2, 3, 11, 1) RC = (not relevant)
This example shows a search where sequence x has a positive stride, and sequence y has a negative stride. As shown below, elements of y are in descending order in array Y. The optional return codes are not requested, because IOPT is specified as 0.
X INCX N Y INCY M INDX RC IOPT
| | | | | | | | |
CALL IBSRCH( X , 2 , 5 , Y , -1 , 10 , INDX , RC , 0 )
X = (-3, . , 125, . , 30, . , 20, . , 70) Y = (100, 90, 80, 60, 50, 40, 30, 30, 20, 10) RC =(not relevant)
INDX = (1, 11, 3, 2, 8)
These subroutines perform a sequential search for the locations of the
elements of sequence x in another sequence y. Depending
on the sign of the idir argument, the search direction indicator, the
location of either the first or last occurrence of each element is indicated
in the resulting indices array INDX. When an exact match between
elements is not found, the position is indicated as 0.
| x, y | Subroutine |
| Integer | ISSRCH |
| Short-precision real | SSSRCH |
| Long-precision real | DSSRCH |
| Fortran | CALL ISSRCH | SSSRCH | DSSRCH (x, incx, n, y, incy, m, idir, indx) |
| C and C++ | issrch | sssrch | dssrch (x, incx, n, y, incy, m, idir, indx); |
| PL/I | CALL ISSRCH | SSSRCH | DSSRCH (x, incx, n, y, incy, m, idir, indx); |
| Note: | Be careful in specifying the stride for sequence y. A negative stride reverses the direction of the search, because the order of the sequence elements is reversed in the array. |
Specified as: a one-dimensional array of (at least) length 1+(m-1)|incy|, containing numbers of the data type indicated in Table 148.
If idir >= 0, sequence y is searched from the first element to the last (1, n), thus finding the first occurrence of the element in the sequence.
If idir < 0, sequence y is searched from the last element to the first (n, 1), thus finding the last occurrence of the element in the sequence.
Specified as: a fullword integer. It can have any value.
If idir >= 0, the first occurrence of the element found in sequence y is indicated in array INDX.
If idir < 0, the last occurrence of the element found in sequence y is indicated in array INDX.
In all cases, if no match is found, 0 is indicated in array INDX.
Returned as: a one-dimensional array of length n, containing fullword integers; 0 <= (INDX elements) <= m.
These subroutines perform a sequential search for the first occurrence (or last occurrence, using a negative idir) of the locations of the elements of sequence x in another sequence y. The results of the sequential searches are returned in the indices array INDX, indicating the positions of the elements of sequence x in sequence y. The positions indicated in array INDX are calculated relative to the first sequence element position--that is, the position of y1. When an exact match between values of elements in sequences x and y is not found, 0 is indicated in array INDX for that position.
The results returned in array INDX are expressed as follows:
where:
See reference [69]. If n is 0, no search is performed.
It is important to note that a negative stride for sequence y reverses the direction of the search, because the order of the sequence elements is reversed in the array.
None
This example shows a search where sequences x and y have positive strides, and the search direction indicator, idir, is positive.
X INCX N Y INCY M IDIR INDX
| | | | | | | |
CALL ISSRCH( X , 1 , 3 , Y , 2 , 8 , 1 , INDX )
X = (0, 12, 3)
Y = (0, . , 8, . , 12, . , 0, . , 1, . , 4, . , 0, . , 2)
INDX = (1, 3, 0)
This example shows a search where sequences x and y have positive strides, and the search direction indicator, idir, is negative.
X INCX N Y INCY M IDIR INDX
| | | | | | | |
CALL ISSRCH( X , 2 , 3 , Y , 2 , 8 , -1 , INDX )
X = (0, . , 12, . , 3)
Y = (0, . , 8, . , 12, . , 0, . , 1, . , 4, . , 0, . , 2)
INDX = (7, 3, 0)
This example shows a search where sequences x and y have negative strides, and the search direction indicator, idir, is positive.
X INCX N Y INCY M IDIR INDX
| | | | | | | |
CALL ISSRCH( X , -1 , 3 , Y , -2 , 8 , 1 , INDX )
X = (0, 12, 3)
Y = (0, . , 8, . , 12, . , 0, . , 1, . , 4, . , 0, . , 2)
INDX = (0, 6, 2)
This example shows a search where sequences x and y have negative strides, and the search direction indicator, idir, is negative.
X INCX N Y INCY M IDIR INDX
| | | | | | | |
CALL ISSRCH( X , -2 , 3 , Y , -1 , 8 , -1 , INDX )
X = (0, . , 12, . , 3)
Y = (0, 8, 12, 0, 1, 4, 0, 2)
INDX = (0, 6, 8)