FINDKEY():
FINDC(),
FIND1(), FIND2(), FIND3(), FIND4(),
FINDR1(), FINDR2(), FINDR3(), FINDR4()

Fortran version:

Fortran-90 generic routine FINDKEY() for I/O API-3.2: compiler selects the appropriate type-specific form depending upon the number and types of the keys and key-lists:
    INTEGER FUNCTION FINDKEY( KEY1[,...,] N, LIST1[,...] )
        INTEGER  N              !   table size
        <type>   KEY1[, ...]
        <type>   LIST1(N)[, ...]

Type-specific forms:

    INTEGER FUNCTION FINDC( KEY,N, CLIST )

    INTEGER FUNCTION FIND1( K1, N, LIST1 )
    INTEGER FUNCTION FIND2( K1, K2, N, LIST1, LIST2 )
    INTEGER FUNCTION FIND3( K1, K2, K3, N, LIST1, LIST2, LIST3 )
    INTEGER FUNCTION FIND4( K1, K2, K3, K4,
 &                          N, LIST1, LIST2, LIST3, LIST4 )

    INTEGER FUNCTION FINDL1( L1, N, LLST1 )
    INTEGER FUNCTION FINDL2( L1, L2, N, LLST1, LLST2 )
    INTEGER FUNCTION FINDL3( L1, L2, L3, N, LLST1, LLST2, LLST3 )
    INTEGER FUNCTION FINDL4( L1, L2, L3, L4,
 &                          N, LLST1, LLST2, LLST3, LLST4 )

    INTEGER FUNCTION FINDR1( X1, N, XLST1 )
    INTEGER FUNCTION FINDR2( X1, X2, N, XLST1, XLST2 )
    INTEGER FUNCTION FINDR3( X1, X2, X3, N, XLST1, XLST2, XLST3 )
    INTEGER FUNCTION FINDR4( X1, X2, X3, X4,
 &                          N, XLST1, XLST2, XLST3, XLST4 )

        CHARACTER*(*), INTENT(IN   ) :: KEY           !  key string
        INTEGER      , INTENT(IN   ) :: K1            !  first  key
        INTEGER      , INTENT(IN   ) :: K2            !  second key
        INTEGER      , INTENT(IN   ) :: K3            !  third  key
        INTEGER      , INTENT(IN   ) :: K4            !  fourth key
        INTEGER(8)   , INTENT(IN   ) :: L1            !  first  Ley
        INTEGER(8)   , INTENT(IN   ) :: L2            !  second Ley
        INTEGER(8)   , INTENT(IN   ) :: L3            !  third  Ley
        INTEGER(8)   , INTENT(IN   ) :: L4            !  fourth Ley
        REAL         , INTENT(IN   ) :: X1            !  first  key
        REAL         , INTENT(IN   ) :: X2            !  second key
        REAL         , INTENT(IN   ) :: X3            !  third  key
        REAL         , INTENT(IN   ) :: X4            !  fourth key
        INTEGER      , INTENT(IN   ) :: N             !  table size
        CHARACTER*(*), INTENT(IN   ) :: CLIST( N )    !  table to search for KEY
        INTEGER      , INTENT(IN   ) :: LIST1( N )    !  table to search for K1
        INTEGER      , INTENT(IN   ) :: LIST2( N )    !  table to search for K2
        INTEGER      , INTENT(IN   ) :: LIST3( N )    !  table to search for K3
        INTEGER      , INTENT(IN   ) :: LIST4( N )    !  table to search for K4
        INTEGER(8)   , INTENT(IN   ) :: LLST1( N )    !  table to search for L1
        INTEGER(8)   , INTENT(IN   ) :: LLST2( N )    !  table to search for L2
        INTEGER(8)   , INTENT(IN   ) :: LLST3( N )    !  table to search for L3
        INTEGER(8)   , INTENT(IN   ) :: LLST4( N )    !  table to search for L4
        REAL         , INTENT(IN   ) :: XLST1( N )    !  table to search for X1
        REAL         , INTENT(IN   ) :: XLST2( N )    !  table to search for X2
        REAL         , INTENT(IN   ) :: XLST3( N )    !  table to search for X3
        REAL         , INTENT(IN   ) :: XLST4( N )    !  table to search for X4

C version:

    int find1c( int        k1,
                int        n,
                const int *list1 ); /** look up integer in sorted key table **/

    int find2c( int        k1,
                int        k2,
                int        n,
                const int *list1 ,
                const int *list2 ) ; /** look up <K1,K2> in 2-key table **/

    int find3c( int        k1,
                int        k2,
                int        k3,
                int        n,
                const int *list1 ,
                const int *list2 ,
                const int *list3 ) ; /** look up <K1,K2,K3> in 3-key table **/

    int find4c( int        k1,
                int        k2,
                int        k3,
                int        k4,
                int        n,
                const int *list1 ,
                const int *list2 ,
                const int *list3 ,
                const int *list4 ) ; /* look up <K1,K2,K3,K4> in 4-key table */

    int findr1c( float        x1,
                 int          n,
                 const float *xlst1 ); /** look up float in sorted key table **/

    int findr2c( float        x1,
                 float        x2,
                 int          n,
                 const float *xlst1 ,
                 const float *xlst2 ) ; /** look up <X1,X2> in 2-key table **/

    int findr3c( float        x1,
                 float        x2,
                 float        x3,
                 int          n,
                 const float *xlst1 ,
                 const float *xlst2 ,
                 const float *xlst3 ) ; /** look up <X1,X2,X3> in 3-key table **/

    int findr4c( float        x1,
                 float        x2,
                 float        x3,
                 float        x4,
                 int          n,
                 const float *xlst1 ,
                 const float *xlst2 ,
                 const float *xlst3 ,
                 const float *xlst4 ) ; /* look up <X1,X2,X3,X4> in 4-key table */

Summary:

Binary key-tuple search Return subscript at which the target character-string, integer, or real key-tuple appears, or negative number in case of failure.

Fortran version returns Fortran subscript (1, ..., N); C version returns C subscript (0, ..., N-1). No C version of FINDC() because of the differences in Fortran and C character-strings.

See also SORTIC, SORTI1, SORTI2, SORTI3, SORTI4, SORTL1, SORTL2, SORTL3, SORTL4, SORTR1, SORTR2, SORTR3, SORTR4 for sorting key-tuple tables, LOCATC, LOCAT1, LOCAT2, LOCAT3, LOCAT4, LOCATR1, LOCATR2, LOCATR3, LOCATR4 for determining where to insert entries into sorted key-tuple tables, and INDEX1, INDEXILNT1, INDEXL1 for single-key lookups into unsorted tables.

For Fortran-90 generic interface FINDKEY() and declarations and interface checking:

    USE M3UTILIO
    

Preconditions:

#include "iodecl3.h" for C.

Table <N, LIST1, ... > to be searched is sorted in increasing order and does not have duplicates.

Fortran Usage:

    ...
    USE M3UTILIO
    ...
    INTEGER  KEY1, KEY2
    INTEGER  I

    !!       .....here are *already-sorted* paired lists of keys:
    INTEGER  LIST1( 7 ), LIST2( 7 )
    DATA     LIST1 / 1980, 1980, 1983, 1985, 1988, 1988, 1990 /
    DATA     LIST2 /    3,    7,    5,   11,    1,   10,    7 /
    ...

    !!          ...in this case, key will be found at location 2
    KEY1 = 1980
    KEY2 = 7
    I = FIND2( KEY1, KEY2, 7, LIST1, LIST2 )
    IF ( I .LT. 0 ) THEN
        ... KEY not found in LIST1
    END IF
    ...

    !!          ...generic:  compiler will select FIND1()
    !!          ...in this case, key will not not found:
    KEY1 = 1986
    I = FINDKEY( KEY1, 7, LIST1 )
    IF ( I .LT. 0 ) THEN
        ... KEY not found in LIST1
    END IF
    ...

C Usage:

    ...
    #include "iodecl3.h"
    #define  TABLESIZE    ...
    ...
    int  k1, k2, k3, k4 ;
    int  indx ;
    int  tablesize ;
    int  list1[TABLESIZE], list2[TABLESIZE], list3[TABLESIZE], list4[TABLESIZE]
    ...
    /*  Assume tuple-sorted keytables <list1[].list2[].list3[].list4[]>
    ...
    if ( 0 > ( indx = find4( k1, k2, k3, k4,
                             TABLESIZE,
                             list1, list2, list3, list4 ) ) )
        {
        /** <k1,k2,k3,k4&g not found  **/
        ...
        }
    else{
        /** <k1,k2,k3,k4&g found at subscript indx  **/
        ...
        }
    ...


Previous: ENVYN

Next: GCD

SEE ALSO: LOCAT* Binary Search-and-Insert Routines

SEE ALSO: LOCAT*Sort Routines

Up: Utility Routines

To: Models-3/EDSS I/O API: The Help Pages