SSRCH
Searches a character vector, sorted in ascending ASCII order, for a given string and return its index.
Required Arguments
N — Length of vector CHY. (Input)
Default: N = size (CHX,1) / INCX.
STRING — Character string to be searched for in CHY. (Input)
CHX — Vector of length N * INCX containing character strings. (Input)
CHY is obtained from CHX for I = 1, 2, …, N by CHY(I) = CHX(1 + (I ‑ 1) * INCX). CHY(1), CHY(2), …, CHY(N) must be in ascending ASCII order.
INCX — Displacement between elements of CHX. (Input)
INCX must be greater than zero.
Default: INCX = 1.
INDEX — Index of CHY pointing to STRING. (Output)
If INDEX is positive, STRING is found in CHY. If INDEX is negative, STRING is not found in CHY.
INDEX | Location of STRING |
|---|
1 thru N | STRING = CHY(INDEX) |
‑1 | STRING < CHY(1) or N = 0 |
‑N thru ‑2 | CHY(‑INDEX ‑ 1) < STRING < CHY(‑INDEX) |
‑(N + 1) | STRING > CHY(N) |
FORTRAN 90 Interface
Generic: CALL SSRCH (N, STRING, CHX, INCX, INDEX)
Specific: The specific interface name is SSRCH.
FORTRAN 77 Interface
Single: CALL SSRCH (N, STRING, CHX, INCX, INDEX)
Description
Routine SSRCH searches a vector of character strings x (stored in CHX), whose n elements are sorted in ascending ASCII order, for a character string c (stored in STRING). If c is found in x, its index i (stored in INDEX) is returned so that xi = c. Otherwise, a negative number i is returned for the index.
Specifically,
if 1 ≤ i ≤ n | Then xi = c |
if i = ‑1 | Then c < x1 or n = 0 |
if ‑n ≤ i ≤ ‑2 | Then x–i–1< c < x–i |
if i = ‑(n + 1) | Then c > xn |
Here, “<“ and “>” are in reference to the ASCII collating sequence. For comparisons made between character strings c and xi with different lengths, the shorter string is considered as if it were extended on the right with blanks to the length of the longer string. (SSRCH uses FORTRAN intrinsic functions LLT and LGT.)
The argument INCX is useful if a row of a matrix, for example, row number I of a matrix CHX, must be searched. The elements of row I are assumed to be in ascending ASCII order. In this case, set INCX equal to the leading dimension of CHX exactly as specified in the dimension statement in the calling program. With CHX declared
CHARACTER * 7 CHX(LDCHX,N)
the invocation
CALL SSRCH (N, STRING, CHX(I,1), LDCHX, INDEX)
returns an index that will reference a column number of CHX.
The routine SSRCH performs a binary search. The routine is an implementation of algorithm B discussed by Knuth (1973, pages 407‑411).
Example
This example searches a CHARACTER * 2 vector containing 9 character strings, sorted in ascending ASCII order, for the value ’CC’.
USE SSRCH_INT
USE UMACH_INT
IMPLICIT NONE
INTEGER N, INCX
PARAMETER (N=9)
!
INTEGER INDEX, NOUT
CHARACTER CHX(N)*2, STRING*2
!
DATA CHX/'AA', 'BB', 'CC', 'DD', 'EE', 'FF', 'GG', 'HH', &
'II'/
!
INCX = 1
STRING = 'CC'
CALL SSRCH (N, STRING, CHX, INCX, INDEX)
!
CALL UMACH (2, NOUT)
WRITE (NOUT,*) 'INDEX = ', INDEX
END
Output
INDEX = 3
