strxfrm() — Transform string
Standards
| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C
XPG4 XPG4.2 C99 Single UNIX Specification, Version 3 |
both |
Format
#include <string.h>
size_t strxfrm(char * __restrict__ s1, const char * __restrict__ s2, size_t n);General description
Transforms the string pointed to by s2 and places the resulting string into the array pointed to by s1. The transformation is determined by the program's locale. The transformed string is not necessarily readable, but can be used with the strcmp() or strncmp() functions.
The transformation is such that, if strcmp() or strncmp() were applied to the two transformed strings, the results would be the same as applying the strcoll() function to the two corresponding untransformed strings.
No more than n bytes are placed into the area pointed to by s1, including the terminating NULL byte. If n is zero, s1 is allowed to be a NULL pointer.
Returned value
If successful, strxfrm() returns the length of the transformed string (excluding the NULL byte). When n is zero and s1 is a NULL pointer, the length returned is the number of bytes minus one required to contain the transformed string.
If unsuccessful, strxfrm() returns (size_t)-1 and sets errno to indicate the error.
- The string returned by strxfrm() contains the weights for each order of the characters within the string. As a result, the string returned may be longer than the input string, and does not contain printable characters.
- strxfrm() issues a malloc() when the LC_COLLATE category specifies backward on the order_start keyword, the substitute keyword is specified, or the locale has one-to-many mapping. The strxfrm() function will fail if the malloc() fails.
- If the locale supports double-byte characters (
MB_CUR_MAXspecified as 4), the strxfrm() function validates the multibyte characters, whereas previously the strxfrm() function did not validate the string. The strxfrm() function will fail if the string contains invalid multibyte characters. - If MB_CUR_MAX is defined as 4, and no collation is defined for DBCS chars in the current locale, the DBCS characters will collate after the single-byte characters.
Example
/* CELEBS57
This example prompts the user to input a string of characters, then
uses strxfrm() to transform the string and return its length.
*/
#include <collate.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
int main(void)
{
char *string1="string1", *string2="string2";
char *newstring1, *newstring2;
int length1, length2;
length1=strxfrm(NULL, string1, 0);
length2=strxfrm(NULL, string2, 0);
if (((newstring1=(char *)calloc(length1+1, 1))==NULL) ||
((newstring2=(char *)calloc(length2+1, 1))==NULL))
{
printf("insufficient memory\n");
exit(99);
}
if ((strxfrm(newstring1, string1, length1+1) != length1) ||
(strxfrm(newstring2, string2, length2+1) != length2))
{
printf("error in string processing\n");
exit(99);
}
if (strcoll(string1, string2) != strcmp(newstring1, newstring2))
{
printf("wrong results\n");
exit(99);
}
printf("correct results\n");
exit(0);
}