[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2

wcsxfrm Subroutine


Transforms wide-character strings to wide-character codes of current locale.


Standard C Library (libc.a)


#include <string.h>

size_t wcsxfrm ( WcString1 WcString2 Number)
wchar_t *WcString1;
const wchar_t *WcString2;
size_t Number;


The wcsxfrm subroutine transforms 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. 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 subroutine, the result is the same as that obtained by a direct call to the wcscoll subroutine on the two original wide-character strings.


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.

Return Values

If the WcString1 parameter is a wide-character null pointer, the wcsxfrm subroutine returns 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 subroutine returns a value of EINVAL.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The wcscmp (wcscat, wcschr, wcscmp, wcscpy, or wcscspn Subroutine) subroutine, wcscoll (wcscoll Subroutine) subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character String Collation Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]