Engineering and Scientific Subroutine Library for AIX Version 3 Release 3: Guide and Reference

ISSRCH, SSSRCH, and DSSRCH--Sequential Search for Elements of a Sequence X in the Sequence Y

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.

Table 153. Data Types

Syntax

On Entry

x

is the sequence x of length n, containing the elements for which sequence y is searched. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 153.

incx

is the stride for sequence x. Specified as: a fullword integer. It can have any value.

n

is the number of elements in sequence x and array INDX. Specified as: a fullword integer; n >= 0.

y

is the sequence y of length m to be searched.

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 153.

incy

is the stride for sequence y. Specified as: a fullword integer. It can have any value.

m

is the number of elements in sequence y. Specified as: a fullword integer; m >= 0.

idir

indicates the search direction, where:

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.

indx

See On Return.

On Return

indx

is the array, referred to as INDX, containing the n indices that indicate the positions of the elements of sequence x in sequence y, where:

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.

Function

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 y₁. 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:

For i = 1, n

for all y_j = x_i, j = 1, m

INDX(i) = min(j), if idir >= 0

INDX(i) = max(j), if idir < 0

if all y_j <> x_i, j = 1, m

INDX(i) = 0

where:

x is a sequence of length n, containing the search elements.

y is a sequence of length m to be searched.

INDX is the array of length n of indices.

See reference [75]. 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.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. n < 0
2. m < 0

Example 1

This example shows a search where sequences x and y have positive strides, and the search direction indicator, idir, is positive.

Call Statement and Input

             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)

Output

INDX     =  (1, 3, 0)

Example 2

This example shows a search where sequences x and y have positive strides, and the search direction indicator, idir, is negative.

Call Statement and Input

             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)

Output

INDX     =  (7, 3, 0)

Example 3

This example shows a search where sequences x and y have negative strides, and the search direction indicator, idir, is positive.

Call Statement and Input

             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)

Output

INDX     =  (0, 6, 2)

Example 4

This example shows a search where sequences x and y have negative strides, and the search direction indicator, idir, is negative.

Call Statement and Input

             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)

Output

INDX     =  (0, 6, 8)