Transforms wide-character strings to wide-character codes of current locale.
Standard C Library (libc.a)
The wcsxfrm and wcsxfrm _l subroutines transform the wide-character string specified by the WcString2 parameter into a string of wide-character codes, based on the collation values of the wide characters in the current locale as specified by the LC_COLLATE category of the current locale or the locale represented by Locale respectively. No more than the number of character codes specified by the Number parameter are copied into the array specified by the WcString1 parameter. When two such transformed wide-character strings are compared using the wcscmp or wcscoll_l subroutine, the result is the same as that obtained by a direct call to the wcscoll or wcscoll_l the subroutine on the two original wide-character strings.
| Item | Description |
|---|---|
| WcString1 | Points to the destination wide-character string. |
| WcString2 | Points to the source wide-character string. |
| Number | Specifies the maximum number of wide-character codes to place into the array specified by WcString1. To determine the necessary size specification, set the Number parameter to a value of 0, so that the WcString1 parameter becomes a null pointer. The return value plus 1 is the size necessary for the conversion. |
| Locale | Specifies the locale in which character has to be converted. |
If the WcString1 parameter is a wide-character null pointer, the wcsxfrm and the wcsxfrm_l subroutine return the number of wide-character elements (not including the wide-character null terminator) required to store the transformed wide character string. If the count specified by the Number parameter is sufficient to hold the transformed string in the WcString1 parameter, including the wide character null terminator, the return value is set to the actual number of wide character elements placed in the WcString1 parameter, not including the wide character null. If the return value is equal to or greater than the value specified by the Number parameter, the contents of the array pointed to by the WcString1 parameter are indeterminate. This occurs whenever the Number value parameter is too small to hold the entire transformed string. If an error occurs, the wcsxfrm subroutine returns the size_t data type with a value of -1 and sets the errno global variable to indicate the error.
If the wide character string pointed to by the WcString2 parameter contains wide character codes outside the domain of the collating sequence defined by the current locale, the wcsxfrm and wcsxfrm_l subroutines return a value of EINVAL.