Man Wcsxfrm en anglais
WCSXFRM(P)                 POSIX Programmer's Manual                WCSXFRM(P)



 

NAME


       wcsxfrm - wide-character string transformation

 

SYNOPSIS


       #include 

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


 

DESCRIPTION






       The  wcsxfrm()  function  shall  transform  the  wide-character  string
       pointed to by ws2 and place the resulting  wide-character  string  into
       the  array  pointed to by ws1. The transformation shall be such that if
       wcscmp() is applied to two transformed wide strings, it shall return  a
       value  greater  than,  equal  to,  or less than 0, corresponding to the
       result of wcscoll() applied to the  same  two  original  wide-character
       strings.  No  more than n wide-character codes shall be placed into the
       resulting array pointed to by ws1, including the terminating null wide-
       character  code.  If  n is 0, ws1 is permitted to be a null pointer. If
       copying takes place between objects that overlap, the behavior is unde-
       fined.

       The  wcsxfrm()  function  shall not change the setting of errno if suc-
       cessful.

       Since no return value is reserved to indicate an error, an  application
       wishing  to check for error situations should set errno to 0, then call
       wcsxfrm(), then check errno.

 

RETURN VALUE


       The wcsxfrm() function shall return the length of the transformed wide-
       character  string  (not  including  the terminating null wide-character
       code). If the value returned is n or more, the contents  of  the  array
       pointed to by ws1 are unspecified.

       On  error, the wcsxfrm() function may set errno, but no return value is
       reserved to indicate an error.

 

ERRORS


       The wcsxfrm() function may fail if:

       EINVAL The wide-character string pointed to by ws2 contains  wide-char-
              acter codes outside the domain of the collating sequence.


       The following sections are informative.

 

EXAMPLES


       None.

 

APPLICATION USAGE


       The transformation function is such that two transformed wide-character
       strings can be ordered by wcscmp() as appropriate to collating sequence
       information in the program's locale (category LC_COLLATE ).

       The fact that when n is 0 ws1 is permitted to be a null pointer is use-
       ful to determine the size of the ws1 array prior to making  the  trans-
       formation.

 

RATIONALE


       None.

 

FUTURE DIRECTIONS


       None.

 

SEE ALSO


       wcscmp()    ,    wcscoll()   ,   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, 

 

COPYRIGHT


       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                           WCSXFRM(P)