strxfrm

Syntax

  #include <string.h> 
   
  size_t strxfrm (
     char         *dst,
     const char   *src,
     size_t        n);
  

Parameters

dst

(OUT) Points to the array into which to place the transformed characters.

src

(IN) Points to the string to be transformed.

n

(IN) Specifies the number of characters to transform plus the null-terminating byte (for example, n = 4 characters + 1).

Return Values

If successful, returns the length of the transformed string (not including the null-terminating byte). If the returned value is n or greater, the contents of the dst array are indeterminate.

Remarks

The strxfrm function transforms, for no more than n characters, the string pointed to by src to the buffer pointed to by dst. The transformation uses the collating sequence selected by setlocale to normalize the string. If successful, the transformed string is null terminated.

The strcoll function normalizes two strings and then returns whether the strings are equal. It does not return the normalized strings. The strxfrm function allows you to normalize string and access the results. If you pass the original string and the same string normalized with strxfrm to strcoll, strcoll would declare them equal.

To determine how much room is needed to store the results of the strxfrm function, set dst to NULL and n to 0 and call the function with src specifying the string to convert.

See Also

strcoll

Example

The following example works only if the example is compiled when the code page is set to 437. The server must also be set to codepage 437 when the NLM is run. The line that is transformed is from Hamlet, “To be or not to be, that is the question!” and is rendered in French to illustrate that the transformation involves more than upper casing the letters.

  #include <stdio.h>
  #include <screen.h>
  #include <stdlib.h>
  #include <string.h>
  
  #define MAX_STR_LEN     255
  #define RULER           "\
            1         2         3         4         5         6         7\n\
  1234567890123456789012345678901234567890123456789012345678901234567890123456789\
  \n"
   
  int main( void )
  {
              // this string is relative only to codepage 437 (us-en)
     char     *src = "être ou ne pas être, c’est là la question !",
              tgt[MAX_STR_LEN+1];
     size_t   rc, count;
   
     setscreenmode(SCR_NO_MODE);
   
     // should tell us how much room is needed...
     count = strxfrm((char *) NULL, src, 0);
   
     printf("%d bytes are needed to hold the transformation of:\n",
            count);
     printf(RULER);
     printf("%s\n", src);
   
     if (!n)
        goto Exit;
   
     // make the transformation...
     rc = strxfrm(tgt, src, count+1);
   
     printf("yielding:\n\t%s\n", tgt);
   
     // prints out: ETRE OU NE PAS ETRE, C’EST LA LA QUESTION !
   
     if (rc != count)
        printf("Unexpected return value (%d)...\n", rc);
     else
        printf("strxfrm() succeeded!\n");
   
     return 0;
  }