*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> wcsxfrm (3)              



NAME    [Toc]    [Back]

       wcsxfrm  -  Transform wide-character strings for collation
       in the current locale

SYNOPSIS    [Toc]    [Back]

       #include <wchar.h>

       size_t wcsxfrm(
               wchar_t *ws1,
               const wchar_t *ws2,
               size_t n );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       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.

PARAMETERS    [Toc]    [Back]

       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.

DESCRIPTION    [Toc]    [Back]

       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.

NOTES    [Toc]    [Back]

       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.

RETURN VALUES    [Toc]    [Back]

       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.

ERRORS    [Toc]    [Back]

       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.

SEE ALSO    [Toc]    [Back]

       Functions: setlocale(3), string(3), wcscmp(3), wcscoll(3)

       Standards: standards(5)

[ Back ]
 Similar pages
Name OS Title
wcscoll FreeBSD compare wide strings according to current collation
wcscoll Tru64 Compare wide-character strings by using collation information
strcoll Tru64 Compares strings using locale collation
strxfrm Tru64 Transforms string for collation in current locale
towctrans Tru64 Convert a wide character according to a property defined in the current locale
wcsxfrm FreeBSD transform a wide string under locale
strcoll FreeBSD compare strings according to current collation
strcoll OpenBSD compare strings according to current collation
strcoll NetBSD compare strings according to current collation
strcoll Linux compare two strings using the current locale
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service