1wcstring(3C) Standard C Library Functions wcstring(3C)
2
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
13 #include <wchar.h>
14 wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);
16 wchar_t *wcsncat(wchar_t *restrict ws1, const wchar_t *restrict ws2,
19 size_t n);
20 int wcscmp(const wchar_t *ws1, const wchar_t *ws2);
23 int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);
26 wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);
29 wchar_t *wcsncpy(wchar_t *restrict ws1, const wchar_t *restrict ws2,
32 size_t n);
33 size_t wcslen(const wchar_t *ws);
36 wchar_t *wcschr(const wchar_t *ws, wchar_t wc);
39 wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc);
42 wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);
45 wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);
48 size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);
51 size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);
54 XPG4, SUS, SUSv2, SUSv3
57 wchar_t *wcstok(wchar_t *restrict ws1, const wchar_t *restrict ws2);
58 Default and other standards
61 wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2, wchar_t **ptr);
62 #include <widec.h>
65 wchar_t *wscat(wchar_t *ws1, const wchar_t *ws2);
67 wchar_t *wsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);
70 int wscmp(const wchar_t *ws1, const wchar_t *ws2);
73 int wsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);
76 wchar_t *wscpy(wchar_t *ws1, const wchar_t *ws2);
79 wchar_t *wsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);
82 size_t wslen(const wchar_t *ws);
85 wchar_t *wschr(const wchar_t *ws, wchat_t wc);
88 wchar_t *wsrchr(const wchar_t *ws, wchat_t wc);
91 wchar_t *wspbrk(const wchar_t *ws1, const wchar_t *ws2);
94 size_t wsspn(const wchar_t *ws1, const wchar_t *ws2);
97 size_t wscspn(const wchar_t *ws1, const wchar_t *ws2);
100 wchar_t *wstok(wchar_t *ws1, const wchar_t *ws2);
103 wchar_t *windex(const wchar_t *ws, wchar_t wc);
106 wchar_t *wrindex(const wchar_t *ws, wchar_t wc);
109 ISO C++
112 #include <wchar.h>
113 const wchar_t *wcschr(const wchar_t *ws, wchar_t wc);
115 const wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);
118 const wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc);
121 #include <cwchar>
124 wchar_t *std::wcschr(wchar_t *ws, wchar_t wc);
126 wchar_t *std::wcspbrk(wchar_t *ws1, const wchar_t *ws2);
129 wchar_t *std::wcsrchr(wchar_t *ws, wchar_t wc);
132
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 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 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 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 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 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 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 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 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 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 windex(), wrindex()
227 The windex() and wrindex() functions behave the same as wschr() and
228 wsrchr(), respectively.
229 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 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 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 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 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 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 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 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 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 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 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
310 See attributes(5) for descriptions of the following attributes:
311 ┌─────────────────────────────┬─────────────────────────────┐
316 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
317 ├─────────────────────────────┼─────────────────────────────┤
318 │CSI │Enabled │
319 ├─────────────────────────────┼─────────────────────────────┤
320 │Interface Stability │See NOTES. │
321 ├─────────────────────────────┼─────────────────────────────┤
322 │MT-Level │MT-Safe │
323 └─────────────────────────────┴─────────────────────────────┘
324
326 malloc(3C), string(3C), wcswidth(3C), wcwidth(3C), attributes(5), stan‐
327 dards(5)
328
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.
335SunOS 5.11 14 Aug 2002 wcstring(3C)