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