Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page eqstr_c

Table of contents

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

       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

#### Link to routine eqstr_c source file eqstr_c.c

    Fri Dec 31 18:41:06 2021