Library /sys$common/syshlp/helplib.hlb  —  CRTL  strxfrm
    Changes a string such that the changed string can be passed to
    the strcmp function, and produce the same result as passing the
    unchanged string to the strcoll function.

    Format

      #include  <string.h>

      size_t strxfrm  (char *s1, const char *s2, size_t maxchar);

1  –  Arguments

 s1, s2

    Pointers to character strings.

 maxchar

    The maximum number of bytes (including the null terminator) to be
    stored in s1.

2  –  Description

    The strxfrm function transforms the string pointed to by s2,
    and stores the resulting string in the array pointed to by s1.
    No more than maxchar bytes, including the null terminator, are
    placed into the array pointed to by s1.

    If the value of maxchar is less than the required size to store
    the transformed string (including the terminating null), the
    contents of the array pointed to by s1 is indeterminate. In such
    a case, the function returns the size of the transformed string.

    If maxchar is 0, then s1 is allowed to be a NULL pointer, and the
    function returns the required size of the s1 array before making
    the transformation.

    The string comparison functions, strcoll and strcmp, can produce
    different results given the same two strings to compare. The
    reason for this is that strcmp does a straightforward comparison
    of the code point values of the characters in the strings,
    whereas strcoll uses the locale information to do the comparison.
    Depending on the locale, the strcoll comparison can be a
    multipass operation, which is slower than strcmp.

    The purpose of the strxfrm function is to transform strings in
    such a way that if you pass two transformed strings to the strcmp
    function, the result is the same as passing the two original
    strings to the strcoll function. The strxfrm function is useful
    in applications that need to do a large number of comparisons on
    the same strings using strcoll. In this case, it might be more
    efficient (depending on the locale) to transform the strings once
    using strxfrm, and then do comparisons using strcmp.

3  –  Return Value

    x                  Length of the resulting string pointed to
                       by s1, not including the terminating null
                       character.

                       No return value is reserved for error
                       indication. However, the function can set
                       errno to EINVAL - The string pointed to by s2
                       contains characters outside the domain of the
                       collating sequence.

4  –  Example

        /* This program verifies that two transformed strings when      */
        /* passed through strxfrm and then compared, provide the same   */
        /* result as if passed through strcoll without any              */
        /* transformation.

        #include <string.h>
        #include <stdio.h>
        #include <stdlib.h>
        #include <locale.h>

        #define  BUFF_SIZE  256

        main()
        {
           char string1[BUFF_SIZE];
           char string2[BUFF_SIZE];
           int errno;
           int coll_result;
           int strcmp_result;
           size_t strxfrm_result1;
           size_t strxfrm_result2;

           /* setlocale to French locale */

           if (setlocale(LC_ALL, "fr_FR.ISO8859-1") == NULL) {
               perror("setlocale");
               exit(EXIT_FAILURE);
           }

           /* collate string 1 and string 2 and store the result */

           errno = 0;
           coll_result = strcoll("<a`>bcd", "abcz");
           if (errno) {
               perror("strcoll");
               exit(EXIT_FAILURE);
           }

           else {
               /* Transform the strings (using strxfrm) into string1   */
               /* and string2                                          */

               strxfrm_result1 = strxfrm(string1, "<a`>bcd", BUFF_SIZE);

               if (strxfrm_result1 == ((size_t) - 1)) {
                   perror("strxfrm");
                   exit(EXIT_FAILURE);
               }

               else if (strxfrm_result1 > BUFF_SIZE) {
                   perror("\n** String is too long **\n");
                   exit(EXIT_FAILURE);
               }

               else {
                   strxfrm_result2 = strxfrm(string2, "abcz", BUFF_SIZE);
                   if (strxfrm_result2 == ((size_t) - 1)) {
                       perror("strxfrm");
                       exit(EXIT_FAILURE);
                   }

                   else if (strxfrm_result2 > BUFF_SIZE) {
                       perror("\n** String is too long **\n");
                       exit(EXIT_FAILURE);
                   }

                   /* Compare the two transformed strings and verify   */
                   /* that the result is the same as the result from   */
                   /* strcoll on the original strings                  */
                   else {
                       strcmp_result = strcmp(string1, string2);
                       if (strcmp_result == 0 && (coll_result == 0)) {
                           printf("\nReturn value from strcoll() and "
                             "return value from strcmp() are both zero.");
                          printf("\nThe program was successful\n\n");
                       }

                       else if ((strcmp_result < 0) && (coll_result < 0)) {
                           printf("\nReturn value from strcoll() and "
                        "return value from strcmp() are less than zero.");
                           printf("\nThe program successful\n\n");
                       }

                       else if ((strcmp_result > 0) && (coll_result > 0)) {
                           printf("\nReturn value from strcoll() and "
                     "return value from strcmp() are greater than zero.");
                           printf("\nThe program was successful\n\n");
                       }

                       else {
                       printf("** Error **\n");
                       printf("\nReturn values are not of the same type");
                       }
                    }
                }
           }
        }

    Running the example program produces the following result:

    Return value from strcoll() and return value
                   from strcmp() are less than zero.
    The program was successful
Close Help