eqstr_c

Index Page eqstr_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### 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

    Thu Apr 16 08:58:02 2009