1wcstring(3C)             Standard C Library Functions             wcstring(3C)
2
3
4

NAME

6       wcstring,  wcscat,  wscat,  wcsncat,  wsncat,  wcscmp,  wscmp, wcsncmp,
7       wsncmp, wcscpy, wscpy, wcsncpy, wsncpy, wcslen, wslen,  wcschr,  wschr,
8       wcsrchr,  wsrchr,  windex,  wrindex,  wcspbrk,  wspbrk, wcswcs, wcsspn,
9       wsspn, wcscspn, wscspn, wcstok, wstok -  wide-character  string  opera‐
10       tions
11

SYNOPSIS

13       #include <wchar.h>
14
15       wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);
16
17
18       wchar_t *wcsncat(wchar_t *restrict ws1, const wchar_t *restrict ws2,
19            size_t n);
20
21
22       int wcscmp(const wchar_t *ws1, const wchar_t *ws2);
23
24
25       int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);
26
27
28       wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);
29
30
31       wchar_t *wcsncpy(wchar_t *restrict ws1, const wchar_t *restrict ws2,
32            size_t n);
33
34
35       size_t wcslen(const wchar_t *ws);
36
37
38       wchar_t *wcschr(const wchar_t *ws, wchar_t wc);
39
40
41       wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc);
42
43
44       wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);
45
46
47       wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);
48
49
50       size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);
51
52
53       size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);
54
55
56   XPG4, SUS, SUSv2, SUSv3
57       wchar_t *wcstok(wchar_t *restrict ws1, const wchar_t *restrict ws2);
58
59
60   Default and other standards
61       wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2, wchar_t **ptr);
62
63
64       #include <widec.h>
65
66       wchar_t *wscat(wchar_t *ws1, const wchar_t *ws2);
67
68
69       wchar_t *wsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);
70
71
72       int wscmp(const wchar_t *ws1, const wchar_t *ws2);
73
74
75       int wsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);
76
77
78       wchar_t *wscpy(wchar_t *ws1, const wchar_t *ws2);
79
80
81       wchar_t *wsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);
82
83
84       size_t wslen(const wchar_t *ws);
85
86
87       wchar_t *wschr(const wchar_t *ws, wchat_t wc);
88
89
90       wchar_t *wsrchr(const wchar_t *ws, wchat_t wc);
91
92
93       wchar_t *wspbrk(const wchar_t *ws1, const wchar_t *ws2);
94
95
96       size_t wsspn(const wchar_t *ws1, const wchar_t *ws2);
97
98
99       size_t wscspn(const wchar_t *ws1, const wchar_t *ws2);
100
101
102       wchar_t *wstok(wchar_t *ws1, const wchar_t *ws2);
103
104
105       wchar_t *windex(const wchar_t *ws, wchar_t wc);
106
107
108       wchar_t *wrindex(const wchar_t *ws, wchar_t wc);
109
110
111   ISO C++
112       #include <wchar.h>
113
114       const wchar_t *wcschr(const wchar_t *ws, wchar_t wc);
115
116
117       const wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);
118
119
120       const wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc);
121
122
123       #include <cwchar>
124
125       wchar_t *std::wcschr(wchar_t *ws, wchar_t wc);
126
127
128       wchar_t *std::wcspbrk(wchar_t *ws1, const wchar_t *ws2);
129
130
131       wchar_t *std::wcsrchr(wchar_t *ws, wchar_t wc);
132
133

DESCRIPTION

135       These functions operate on wide-character strings terminated by wchar_t
136       NULL characters. During appending or copying,  these  routines  do  not
137       check for an overflow condition of the receiving string. In the follow‐
138       ing, ws, ws1, and ws2 point to wide-character strings terminated  by  a
139       wchar_t NULL.
140
141   wcscat(), wscat()
142       The  wcscat() and wscat() functions append a copy of the wide-character
143       string pointed to by ws2 (including the terminating null wide-character
144       code)  to  the  end of the wide-character string pointed to by ws1. The
145       initial wide-character code of ws2 overwrites the  null  wide-character
146       code  at  the  end  of ws1. If copying takes place between objects that
147       overlap, the behavior is undefined. Both functions return s1; no return
148       value is reserved to indicate an error.
149
150   wcsncat(), wsncat()
151       The  wcsncat() and wsncat() functions append not more than n wide-char‐
152       acter codes (a null wide-character code and wide-character  codes  that
153       follow it are not appended) from the array pointed to by ws2 to the end
154       of the wide-character string pointed to by ws1. The initial  wide-char‐
155       acter code of ws2 overwrites the null wide-character code at the end of
156       ws1. A terminating null wide-character code is always appended  to  the
157       result. Both functions return ws1; no return value is reserved to indi‐
158       cate an error.
159
160   wcscmp(), wscmp()
161       The wcscmp() and wscmp() functions compare  the  wide-character  string
162       pointed  to  by ws1 to the wide-character string pointed to by ws2. The
163       sign of a non-zero return value is determined by the sign of  the  dif‐
164       ference  between  the  values of the first pair of wide-character codes
165       that differ in the objects being compared. Upon completion, both  func‐
166       tions  return  an integer greater than, equal to, or less than zero, if
167       the wide-character string pointed to by ws1 is greater than, equal  to,
168       or less than the wide-character string pointed to by ws2.
169
170   wcsncmp(), wsncmp()
171       The wcsncmp() and wsncmp() functions compare not more than n wide-char‐
172       acter codes (wide-character codes that follow  a  null  wide  character
173       code  are  not  compared) from the array pointed to by ws1 to the array
174       pointed to by ws2. The sign of a non-zero return value is determined by
175       the  sign  of  the  difference  between the values of the first pair of
176       wide-character codes that differ in the objects  being  compared.  Upon
177       successful  completion,  both functions return an integer greater than,
178       equal to, or less than zero,  if  the  possibly  null-terminated  array
179       pointed  to by ws1 is greater than, equal to, or less than the possibly
180       null-terminated array pointed to by ws2.
181
182   wcscpy(), wscpy()
183       The wcscpy() and  wscpy()  functions  copy  the  wide-character  string
184       pointed  to by ws2 (including the terminating null wide-character code)
185       into the array pointed to  by  ws1.  If  copying  takes  place  between
186       objects  that overlap, the behavior is undefined. Both functions return
187       ws1; no return value is reserved to indicate an error.
188
189   wcsncpy(), wsncpy()
190       The wcsncpy() and wsncpy() functions  copy not more than n wide-charac‐
191       ter  codes (wide-character codes that follow a null wide character code
192       are not copied) from the array pointed to by ws2 to the  array  pointed
193       to  by  ws1.  If  copying takes place between objects that overlap, the
194       behavior is undefined. If the array pointed to by ws2 is a wide-charac‐
195       ter string that is shorter than n wide-character codes, null wide-char‐
196       acter codes are appended to the copy in the array pointed  to  by  ws1,
197       until a total n wide-character codes are written. Both functions return
198       ws1; no return value is reserved to indicate an error.
199
200   wcslen(), wslen()
201       The wcslen() and wslen() functions compute the number of wide-character
202       codes  in  the  wide-character string to which ws points, not including
203       the terminating null wide-character code. Both functions return ws;  no
204       return value is reserved to indicate an error.
205
206   wcschr(), wschr()
207       The wcschr() and wschr() functions locate the first occurrence of wc in
208       the wide-character string pointed to by ws. The value of wc must  be  a
209       character  representable as a type wchar_t and must be a wide-character
210       code corresponding to a valid character in the current locale. The ter‐
211       minating null wide-character code is considered to be part of the wide-
212       character string. Upon completion, both functions return a  pointer  to
213       the  wide-character  code, or a null pointer if the wide-character code
214       is not found.
215
216   wcsrchr(), wsrchr()
217       The wcsrchr() and wsrchr() functions locate the last occurrence  of  wc
218       in  the wide-character string pointed to by ws. The value of wc must be
219       a character representable as a type wchar_t and must be a  wide-charac‐
220       ter  code corresponding to a valid character in the current locale. The
221       terminating null wide-character code is considered to be  part  of  the
222       wide-character  string.  Upon  successful  completion,  both  functions
223       return a pointer to the wide-character code, or a null  pointer  if  wc
224       does not occur in the wide-character string.
225
226   windex(), wrindex()
227       The  windex()  and  wrindex()  functions behave the same as wschr() and
228       wsrchr(), respectively.
229
230   wcspbrk(), wspbrk()
231       The wcspbrk() and wspbrk() functions locate the first occurrence in the
232       wide character string pointed to by ws1 of any wide-character code from
233       the wide-character string pointed to by ws2.  Upon  successful  comple‐
234       tion,  the  function returns a pointer to the wide-character code, or a
235       null pointer if no wide-character code from ws2 occurs in ws1.
236
237   wcswcs()
238       The wcswcs() function locates the first occurrence in the  wide-charac‐
239       ter  string  pointed  to by ws1 of the sequence of wide-character codes
240       (excluding the terminating null wide-character code) in the  wide-char‐
241       acter  string  pointed to by ws2. Upon successful completion, the func‐
242       tion returns a pointer to the located wide-character string, or a  null
243       pointer  if  the wide-character string is not found. If ws2 points to a
244       wide-character string with zero length, the function returns ws1.
245
246   wcsspn(), wsspn()
247       The wcsspn() and wsspn() functions compute the length  of  the  maximum
248       initial  segment  of  the wide-character string pointed to by ws1 which
249       consists entirely  of  wide-character  codes  from  the  wide-character
250       string  pointed  to  by  ws2.  Both functions return the length ws1; no
251       return value is reserved to indicate an error.
252
253   wcscspn(), wscspn()
254       The wcscspn() and wscspn() functions compute the length of the  maximum
255       initial  segment  of  the wide-character string pointed to by ws1 which
256       consists entirely of wide-character codes not from  the  wide-character
257       string  pointed to by ws2. Both functions return the length of the ini‐
258       tial substring of ws1; no return  value  is  reserved  to  indicate  an
259       error.
260
261   wcstok(), wstok()
262       A  sequence  of  calls  to the wcstok() and wstok() functions break the
263       wide-character string pointed to by ws1 into a sequence of tokens, each
264       of  which is delimited by a wide-character code from the wide-character
265       string pointed to by ws2.
266
267   Default and other standards
268       The third argument points to a  caller-provided  wchar_t  pointer  into
269       which the wcstok() function stores information necessary for it to con‐
270       tinue scanning the same wide-character string.  This  argument  is  not
271       available  with the XPG4 and SUS versions of wcstok(), nor is it avail‐
272       able with the wstok() function.  See standards(5).
273
274
275       The first call in the sequence has ws1 as its first  argument,  and  is
276       followed by calls with a null pointer as their first argument. The sep‐
277       arator string pointed to by ws2 may be different from call to call.
278
279
280       The first call in  the  sequence  searches  the  wide-character  string
281       pointed  to  by  ws1 for the first wide-character code that is not con‐
282       tained in the current separator string pointed to by ws2.  If  no  such
283       wide-character  code  is  found,  then there are no tokens in the wide-
284       character string pointed to by ws1, and wcstok() and wstok()  return  a
285       null  pointer.  If such a wide-character code is found, it is the start
286       of the first token.
287
288
289       The wcstok() and wstok() functions then search from that  point  for  a
290       wide-character  code that is contained in the current separator string.
291       If no such wide-character code is found, the current token  extends  to
292       the  end of the wide-character string pointed to by ws1, and subsequent
293       searches for a token will return a null pointer. If such a wide-charac‐
294       ter  code  is  found, it is overwritten by a null wide character, which
295       terminates the current token. The wcstok() and wstok() functions save a
296       pointer  to  the  following  wide-character  code,  from which the next
297       search for a token will start.
298
299
300       Each subsequent call, with a null pointer as the  value  of  the  first
301       argument,  starts  searching  from  the  saved  pointer  and behaves as
302       described above.
303
304
305       Upon successful completion, both functions  return  a  pointer  to  the
306       first  wide-character code of a token. Otherwise, if there is no token,
307       a null pointer is returned.
308

ATTRIBUTES

310       See attributes(5) for descriptions of the following attributes:
311
312
313
314
315       ┌─────────────────────────────┬─────────────────────────────┐
316       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
317       ├─────────────────────────────┼─────────────────────────────┤
318       │CSI                          │Enabled                      │
319       ├─────────────────────────────┼─────────────────────────────┤
320       │Interface Stability          │See NOTES.                   │
321       ├─────────────────────────────┼─────────────────────────────┤
322       │MT-Level                     │MT-Safe                      │
323       └─────────────────────────────┴─────────────────────────────┘
324

SEE ALSO

326       malloc(3C), string(3C), wcswidth(3C), wcwidth(3C), attributes(5), stan‐
327       dards(5)
328

NOTES

330       The  wcscat(),  wcsncat(),  wcscmp(),  wcsncmp(),  wcscpy(), wcsncpy(),
331       wcslen(), wcschr(), wcsrchr(),  wcspbrk(),  wcswcs(),  wcsspn(),  wcsc‐
332       spn(),  and  wcstok()  functions  are  Standard. The wscat(), wsncat(),
333       wscmp(), wsncmp(), wscpy(), wsncpy(), wslen(), wschr(), wsrchr(),  wsp‐
334       brk(), wsspn(), wstok(), windex(), and wrindex() functions are Stable.
335
336
337
338SunOS 5.11                        14 Aug 2002                     wcstring(3C)
Impressum