Abstract

   CSPICE_MATCHW returns a boolean indicating whether a string is matched by
   a template containing wild cards. The pattern comparison is case-sensitive.

I/O

   Given:

      string   the input character string to be tested for a match against the
               input template.

               help, string
                  STRING = Scalar

               Leading and trailing blanks are ignored.

      templ    the input template to be tested for a match against the input
               string.

               help, templ
                  STRING = Scalar

               `templ' may contain wild cards. Leading and trailing blanks are
               ignored.

      wstr     the wild string token used in the input template.

               help, wstr
                  STRING = Scalar

               The wild string token may represent from zero to any number of
               characters.

      wchr     the wild character token used in the input template.

               help, wchr
                  STRING = Scalar

               The wild character token represents exactly one character.

   the call:

      matchw = cspice_matchw( string, templ, wstr, wchr )

   returns:

      matchw   True when the input string matches the input template, and False
               otherwise.

               help, matchw
                  BOOLEAN = Scalar

               The string and template match whenever the template can expand
               (through replacement of its wild cards) to become the input
               string.

Parameters

   None.

Examples

   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Determine, from a set of character strings, which ones match
      a particular template containing wildcards, taking into
      consideration their case.

      Example code begins here.


      PRO matchw_ex1

         ;;
         ;; Determine if a string has the form
         ;;
         ;;     'ABC' + a single character + 'E' + anything 'Z'
         ;;
         ;; where '%' indicates a single character wildcard
         ;; and '*' indicates the glob wildcard.
         ;;
         single_char = '%'
         glob_char   = '*'
         template    = 'ABC%E*Z'

         strings = [ 'ABCDEZ', 'ABCEZ', 'ABC E12345Z', 'ABC e12345Z' ]

         ;;
         ;; A match to the template. Note, the glob wildcard '*' matches
         ;; a null condition, in this case no characters between 'E'
         ;; 'Z'.
         ;;
         for i=0, n_elements(strings)-1 do begin

            match  = cspice_matchw( strings(i), template,   $
                                    glob_char,  single_char )

            if( match ) then begin

               print, "String " + strings(i) + " matches the template "  $
                      + template

            endif else begin

               print, "String " + strings(i) +                   $
                      " does not match the template " + template
            endelse

         endfor

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      String ABCDEZ matches the template ABC%E*Z
      String ABCEZ does not match the template ABC%E*Z
      String ABC E12345Z matches the template ABC%E*Z
      String ABC e12345Z does not match the template ABC%E*Z


      Note that the match respects the case of the characters being
      matched, and '%' matches on a space.

      'ABCEZ' does not match since no character exists between
      'C' and 'E'. The single char match matches only on a single
       character.

Particulars

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

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

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

Exceptions

   1)  If any of the input arguments, `string', `templ', `wstr' or
       `wchr', is undefined, an error is signaled by the IDL error
       handling system.

   2)  If any of the input arguments, `string', `templ', `wstr' or
       `wchr', is not of the expected type, or it does not have the
       expected dimensions and size, an error is signaled by the Icy
       interface.

Files

   None.

Restrictions

   None.

Required_Reading

   ICY.REQ

Literature_References

   None.

Author_and_Institution

   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version

   -Icy Version 1.0.1, 10-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard. Added example's problem
       statement, and combined all examples into a single one.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections, and
       completed -Particulars section.

       Edited the -I/O section to match standard format.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries

   match string against wildcard template
   test whether a string matches a wildcard template