Procedure

   eqstr_c ( Equivalent strings ) 

   SpiceBoolean eqstr_c ( ConstSpiceChar    * a,
                          ConstSpiceChar    * b )

Abstract

   Determine whether two strings are equivalent.

Required_Reading

   None.

Keywords

   ALPHANUMERIC
   ASCII
   CHARACTER
   COMPARE
   PARSING
   SEARCH
   STRING
   TEXT

Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   a,
   b          I   Arbitrary character strings.

   The function returns SPICETRUE if `a' and `b' are equivalent.

Detailed_Input

   a,
   b           are arbitrary character strings.

Detailed_Output

   The function returns SPICETRUE if `a' and `b' are equivalent: that is,
   if `a' and `b' contain  the same characters in the same order,
   when white space characters are ignored and uppercase and
   lowercase characters are considered equal.

   White space characters are those in the set

      { ' ', '\f', '\n', '\r', '\t', '\v' }

   Note that this specification differs from that of the Fortran version
   of this routine, which considers the blank ( ' ' ) to be the only
   white space character.

Parameters

   None.

Exceptions

   1)  If any of the `a' or `b' input string pointers is null, the
       error SPICE(NULLPOINTER) is signaled. The function returns the
       value SPICEFALSE.

Files

   None.

Particulars

   This routine is provided for those cases in which two strings
   must be compared, and in which allowances are to be made for
   extra (leading, trailing, and embedded) blanks and differences
   in case. For the most part,

      eqstr_c ( a, b )

   is SPICETRUE whenever

      cmprss_c ( " ", 0, a,        MAXLEN, tempa );
      ucase_c  (            tempa, MAXLEN, tempa );

      cmprss_c ( " ", 0, b,        MAXLEN, tempb );
      ucase_c  (            tempb, MAXLEN, tempb );

      eqvlnt = !strncmp ( tempa, tempb, MAXLEN )

   is SPICETRUE. There are two important differences, however.

      1) The single reference to eqstr_c is much simpler to
         write, and simpler to understand.

      2) The reference to eqstr_c does not require any temporary
         storage, nor does it require that the strings `a' and `b'
         be changed. This feature is especially useful when
         comparing strings received as subprogram arguments
         against strings stored internally within the subprogram.

Examples

   The numerical results shown for this example may differ across
   platforms. The results depend on the SPICE kernels used as
   input, the compiler and supporting libraries, and the machine
   specific arithmetic implementation.

   1) This code provides examples of equivalent and non-equivalent
      strings according to the algorithm implemented in eqstr_c.

      Example code begins here.


      /.
         Program eqstr_ex1
      ./
      #include <stdio.h>
      #include "SpiceUsr.h"

      int main( )
      {

         /.
         Local parameters.
         ./
         #define SETSIZ       9
         #define STRLEN       23

         /.
         Local variables.
         ./
         SpiceInt             i;

         /.
         Initialize the two arrays of strings.
         ./
         SpiceChar            str1   [SETSIZ][STRLEN] = {
                                "A short string   ", "Embedded        blanks",
                                "Embedded        blanks", " ",
                                "One word left out", "Extra [] delimiters",
                                "Testing 1, 2, 3", "Case insensitive",
                                "Steve" };

         SpiceChar            str2   [SETSIZ][STRLEN] = {
                                "ashortstring",      "Em be dd ed bl an ks",
                                "   Embeddedblanks", "          ",
                                "WORD LEFT OUT",     "extradelimiters",
                                "TESTING123",        "Case Insensitive",
                                "  S t E v E  " };

         /.
         Compare the two arrays.
         ./
         for ( i = 0; i < SETSIZ; i++ )
         {

            printf( "\n" );
            printf( "STR1 : %s\n", str1[i] );
            printf( "STR2 : %s\n", str2[i] );

            if ( eqstr_c ( str1[i], str2[i] ) )
            {
               printf( "eqstr_c: equivalent.\n" );
            }
            else
            {
               printf( "eqstr_c: NOT equivalent.\n" );
            }

         }

         return ( 0 );
      }


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


      STR1 : A short string
      STR2 : ashortstring
      eqstr_c: equivalent.

      STR1 : Embedded        blanks
      STR2 : Em be dd ed bl an ks
      eqstr_c: equivalent.

      STR1 : Embedded        blanks
      STR2 :    Embeddedblanks
      eqstr_c: equivalent.

      STR1 :
      STR2 :
      eqstr_c: equivalent.

      STR1 : One word left out
      STR2 : WORD LEFT OUT
      eqstr_c: NOT equivalent.

      STR1 : Extra [] delimiters
      STR2 : extradelimiters
      eqstr_c: NOT equivalent.

      STR1 : Testing 1, 2, 3
      STR2 : TESTING123
      eqstr_c: NOT equivalent.

      STR1 : Case insensitive
      STR2 : Case Insensitive
      eqstr_c: equivalent.

      STR1 : Steve
      STR2 :   S t E v E
      eqstr_c: equivalent.

Restrictions

   None.

Literature_References

   [1]  "American National Standard for Programming Languages -- C,"
        Section 7.3.1.9, p.104, American National Standards Institute,
        1990.

Author_and_Institution

   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)

Version

   -CSPICE Version 1.3.1, 02-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard.

       Added complete code example based on existing example fragments.

   -CSPICE Version 1.3.0, 27-AUG-1999 (NJB)

       Added check for null input strings. Added logic to handle the
       case where at least one input string is empty.

   -CSPICE Version 1.2.0, 24-FEB-1999 (NJB)

       Arguments passed to isspace are now cast to unsigned char to
       suppress compilation warnings on some systems.

   -CSPICE Version 1.1.0, 08-FEB-1998 (NJB)

       Initial assignment of return value added to suppress compilation
       warnings on some systems.

   -CSPICE Version 1.0.0, 25-OCT-1997 (NJB)

       Based on SPICELIB Version 1.2.0, 03-AUG-1994 (NJB)

Index_Entries

   equivalent strings