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 (STRING, CHX(I:,1), INDEX, N=N, INCX=LDCHX)

returns an index that will reference a column number of CHX.

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