Procedure

   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 TRUE 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 either input string pointer is null, the error 
       SPICE(NULLPOINTER) will be signaled.

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,

      if ( eqstr_c ( A, B ) )
         .
         .

   is true whenever

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

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


      if ( !strcmp ( tempa, tempb ) )
         .
         .

   is true. 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 recieved as subprogram arguments
         against strings stored internally within the subprogram.

Examples

    Usage
    --------------------------------------------

       All of the following are TRUE.

          eqstr_c ( "A short string   ",
                    "ashortstring"        );

          eqstr_c ( "Embedded        blanks",
                    "Em be dd ed bl an ks"    );

          eqstr_c ( "Embedded        blanks",
                    "   Embeddedblanks"    );

          eqstr_c ( " ",
                    "          " );


       All of the following are FALSE.

          eqstr_c ( "One word left out",
                    "WORD LEFT OUT"      );

          eqstr_c ( "Extra [] delimiters",
                    "extradelimiters"      );

          eqstr_c ( "Testing 1, 2, 3",
                    "TESTING123"       );


    Use
    --------------------------------------------

       The following illustrates a typical use for eqstr_c.

          #include "SpiceUsr.h"
              .
              .
              .
          SpiceChar * greeting ( SpiceChar *who )
          {

             if ( eqstr_c ( who, "Steve" ) )
             {
                return ( "Yes, sir?" );
             }
             else if ( eqstr_c ( who, "Chuck" ) )
             {
                return ( "What can I do for you?" );
             }
             else
             {
                return ( "Whaddya want?" );
             }
          }

       Note that all of the following calls will elicit the
       greeting "Yes, sir?":

          greeting ( "STEVE" );
          greeting ( "steve" );
          greeting ( "Steve" );
          greeting ( "sTEVE" );
          greeting ( " S T E V E " );

Restrictions

   None.

Literature_References

   1)  "American National Standard for Programming Languages -- C,"
        Published by the American National Standards Institute, 1990.
        Section 7.3.1.9., p. 104.

Author_and_Institution

   N.J. Bachman    (JPL)
   I.M. Underwood  (JPL)

Version

   -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

Link to routine eqstr_c source file eqstr_c.c