1WCSXFRM(P)                 POSIX Programmer's Manual                WCSXFRM(P)
2
3
4

NAME

6       wcsxfrm - wide-character string transformation
7

SYNOPSIS

9       #include <wchar.h>
10
11       size_t wcsxfrm(wchar_t *restrict ws1, const wchar_t *restrict ws2,
12              size_t n);
13
14

DESCRIPTION

16       The  wcsxfrm()  function  shall  transform  the  wide-character  string
17       pointed to by ws2 and place the resulting  wide-character  string  into
18       the  array  pointed to by ws1. The transformation shall be such that if
19       wcscmp() is applied to two transformed wide strings, it shall return  a
20       value  greater  than,  equal  to,  or less than 0, corresponding to the
21       result of wcscoll() applied to the  same  two  original  wide-character
22       strings.  No  more than n wide-character codes shall be placed into the
23       resulting array pointed to by ws1, including the terminating null wide-
24       character  code.  If  n is 0, ws1 is permitted to be a null pointer. If
25       copying takes place between objects that overlap, the behavior is unde‐
26       fined.
27
28       The  wcsxfrm()  function  shall not change the setting of errno if suc‐
29       cessful.
30
31       Since no return value is reserved to indicate an error, an  application
32       wishing  to check for error situations should set errno to 0, then call
33       wcsxfrm(), then check errno.
34

RETURN VALUE

36       The wcsxfrm() function shall return the length of the transformed wide-
37       character  string  (not  including  the terminating null wide-character
38       code). If the value returned is n or more, the contents  of  the  array
39       pointed to by ws1 are unspecified.
40
41       On  error, the wcsxfrm() function may set errno, but no return value is
42       reserved to indicate an error.
43

ERRORS

45       The wcsxfrm() function may fail if:
46
47       EINVAL The wide-character string pointed to by ws2 contains  wide-char‐
48              acter codes outside the domain of the collating sequence.
49
50
51       The following sections are informative.
52

EXAMPLES

54       None.
55

APPLICATION USAGE

57       The transformation function is such that two transformed wide-character
58       strings can be ordered by wcscmp() as appropriate to collating sequence
59       information in the program's locale (category LC_COLLATE ).
60
61       The fact that when n is 0 ws1 is permitted to be a null pointer is use‐
62       ful to determine the size of the ws1 array prior to making  the  trans‐
63       formation.
64

RATIONALE

66       None.
67

FUTURE DIRECTIONS

69       None.
70

SEE ALSO

72       wcscmp()    ,    wcscoll()   ,   the   Base   Definitions   volume   of
73       IEEE Std 1003.1-2001, <wchar.h>
74

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