wcsxfrm - Transform wide-character strings for collation
in the current locale
#include <wchar.h>
size_t wcsxfrm(
wchar_t *ws1,
const wchar_t *ws2,
size_t n );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
wcsxfrm(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Contains a pointer to the destination wide-character
string. Contains a pointer to the source wide-character
string. Specifies the maximum number of wide-character
codes to place into the array specified by ws1.
The wcsxfrm() function is used to transform the wide-character
string specified by the ws2 parameter into a string
of wide-character codes based on the collation values of
the wide characters in the current setting of the LC_COLLATE
locale category. No more than n wide characters
(including the terminating null wide character) are copied
into the array specified by the ws1 parameter. When two
transformed wide-character strings are obtained and the
transformed strings are compared using wcscmp(), the
result is the same as that obtained by a direct call to
wcscoll() on the two original wide-character strings.
The application can call wcsxfrm() with ws1 as a null
pointer to determine the number of wide characters to
allocate for the ws1 parameter. For example, the following
expression calculates the size of ws1:
1 + wcsxfrm(NULL, ws2, 0)
As shown in this example, the n parameter must be 0 (zero)
when ws1 is a null pointer.
When operating on overlapping strings, the behavior of the
wcsxfrm() function is unreliable.
If an application does multiple comparisons based on the
current locale's collation values and uses the same set of
text strings, the wcsxfrm() transformation function in
conjunction with the wcscmp() function may be more efficient
than the wcscoll() collation function. This is
because the string is transformed based on the locale
tables only once. However, the transformation function
must convert all characters in the string for each level
of a multilevel collation. In comparison, the collation
function stops comparing characters at the first inequality.
These tradeoffs make the most efficient method for a
specific application dependent on the number of repeated
comparisons of strings within the set, the number of collation
levels for the current locale, and the values of
the strings within the set.
If the ws1 parameter is a wide-character null pointer, the
wcsxfrm() function returns the number of wide-character
elements (not including the terminating null wide character)
required to store the transformed wide-character
string. If the count specified by the n parameter is sufficient
to hold the transformed string in the ws1 parameter
(including the terminating null wide character) the
return value is set to the actual number of wide-character
elements placed in the ws1 parameter, not including the
terminating null wide character. If the return value is
equal to or greater than the value specified by the n
parameter, the contents of the array pointed to by the ws1
parameter are indeterminate.
On error, the wcsxfrm() function returns (size_t)-1 and
sets errno to indicate the error.
If any the following conditions occur, the wcsxfrm() function
sets errno to the corresponding value: The ws2 parameter
contains wide-character codes outside the domain of
the collating sequence defined by the current locale.
[Tru64 UNIX] There was insufficient memory available to
allocate temporary storage for this operation.
Functions: setlocale(3), string(3), wcscmp(3), wcscoll(3)
Standards: standards(5)
wcsxfrm(3)
[ Back ] | 