Procedure

     MATCHW ( Match string against wildcard template )

     LOGICAL FUNCTION MATCHW ( STRING, TEMPL, WSTR, WCHR )

Abstract

     Determine whether a string is matched by a template containing
     wild cards.

Required_Reading

     None.

Keywords

     CHARACTER
     COMPARE

Declarations

     IMPLICIT NONE

     CHARACTER*(*)    STRING
     CHARACTER*(*)    TEMPL
     CHARACTER*1      WSTR
     CHARACTER*1      WCHR

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     STRING     I   String to be tested.
     TEMPL      I   Template (with wild cards) to test against STRING.
     WSTR       I   Wild string token.
     WCHR       I   Wild character token.

     The function returns .TRUE. if STRING matches TEMPL and otherwise
     returns .FALSE.

Detailed_Input

     STRING   is the input character string to be tested for a match
              against the input template. Leading and trailing blanks
              are ignored.

     TEMPL    is the input template to be tested for a match against
              the input string. TEMPL may contain wild cards. Leading
              and trailing blanks are ignored.

     WSTR     is the wild string token used in the input template. The
              wild string token may represent from zero to any number
              of characters.

     WCHR     is the wild character token used in the input template.
              The wild character token represents exactly one
              character.

Detailed_Output

     The function returns .TRUE. when the input string matches the
     input template, and .FALSE. otherwise. The string and template
     match whenever the template can expand (through replacement of its
     wild cards) to become the input string.

Parameters

     None.

Exceptions

     Error free.

Files

     None.

Particulars

     MATCHW ignores leading and trailing blanks in both the string
     and the template. All of the following are equivalent (they
     all return .TRUE.).

        MATCHW ( 'ALCATRAZ',     'A*Z',      '*', '%' )
        MATCHW ( '  ALCATRAZ  ', 'A*Z',      '*', '%' )
        MATCHW ( 'ALCATRAZ',     '  A*Z  ',  '*', '%' )
        MATCHW ( '  ALCATRAZ  ', '  A*Z  ',  '*', '%' )

     MATCHW is case-sensitive:  uppercase characters do not match
     lowercase characters, and vice versa. Wild characters match
     characters of both cases.

Examples

     Let

        STRING  = '  ABCDEFGHIJKLMNOPQRSTUVWXYZ  '
        WSTR    = '*'
        WCHR    = '%'

     Then

        if TEMPL is  '*A*'        MATCHW is   T
                     'A%D*'                     F
                     'A%C*'                   T
                     '%A*'                      F
                         '%%CD*Z'                 T
                         '%%CD'                     F
                         'A*MN*Y*Z'               T
                         'A*MN*Y*%Z'                F
                         '*BCD*Z*'                T
                         '*bcd*z*'                  F
                         ' *BCD*Z*  '             T

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     H.A. Neilan        (JPL)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 1.4.0, 06-JUL-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard. Removed
        unnecessary entries from $Revisions section.

    SPICELIB Version 1.3.1, 11-NOV-2005 (NJB)

        Corrected example calls in header; made other minor
        edits to header.

    SPICELIB Version 1.3.0, 08-JUN-1999 (WLT)

        Fixed comments in detailed output and example sections.

    SPICELIB Version 1.2.0, 15-MAY-1995 (WLT)

        Direct substring comparisons were replaced with the logical
        function SAMCH in several cases so as to avoid out of range
        errors when examining substrings.

    SPICELIB Version 1.1.0, 17-MAY-1994 (HAN)

        Set the default function value to either 0, 0.0D0, .FALSE.,
        or blank depending on the type of the function.

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (WLT) (IMU)