strxfrm(), strxfrm_l()

transform string 

Function


SYNOPSIS

#include <string.h>

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

#include <string.h>

#include <locale.h>

size_t strxfrm_l(char *s1, const char *s2, size_t n, locale_t locale);


DESCRIPTION

The strxfrm() function transforms the string pointed to by s2 so that strcmp() can be used for lexical comparisons, taking into consideration the value of LC_COLLATE. The transformations performed by strxfrm() are such that, if two strings are transformed, the lexical relationship of the transformed strings as determined by strcmp() is the same as the lexical relationship of the original strings as determined by strcoll(). The transformed string is placed into the buffer pointed to by s1.

If n is zero, then s1 may be null. In this case, strxfrm() returns the number of characters in s2 it would transform. The terminating null-character is not included.

For the C locale, strxfrm() is equivalent to:

strncpy(s1, s2, n);
return strlen(s1);

strxfrm_l() behaves in the same way as strxfrm() without the _l suffix, but uses the specified locale rather than the global or per-thread locale. A locale_t is returned by newlocale().


PARAMETERS

s1 

Either NULL, or a pointer to a buffer to receive the transformed string.

s2 

Points to a null-terminated string to be transformed for collating.

n 

Is the maximum number of characters to transform.

locale 

Is a locale_t perhaps returned by newlocale() or LC_GLOBAL_LOCALE or 0 for the current thread locale set with uselocale().


RETURN VALUES

The strxfrm() and strxfrm_l() functions return the length of the transformed string, excluding the terminating null character. If the value returned is n or more, the contents of the array pointed to by s1 are undetermined.

If strxfrm() or strxfrm_l() encounters a character outside of the collating sequence defined for the current locale, it sets errno to EINVAL.


CONFORMANCE

wcsxfrm() conforms to ANSI/ISO 9899:1990 'ISO C90'

wcsxfrm_l() conforms to IEEE Std 1003.1-2008 'POSIX.1'


MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The function strxfrm() is MT-Safe as long as no thread calls setlocale() while this function is executing.

The function strxfrm_l() is MT-Safe as long as no thread calls freelocale() on locale while this function is executing.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
localeconv(), localeconv_l(), newlocale(), setlocale(), strcmp(), strcmp_l(), strcoll(), strcoll_l()


PTC MKS Toolkit 10.3 Documentation Build 39.