Fix documentation bugs. Declare wcsdup only is __USE_GNU.
[kopensolaris-gnu/glibc.git] / wcsmbs / wchar.h
1 /* Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
2    This file is part of the GNU C Library.
3
4    The GNU C Library is free software; you can redistribute it and/or
5    modify it under the terms of the GNU Library General Public License as
6    published by the Free Software Foundation; either version 2 of the
7    License, or (at your option) any later version.
8
9    The GNU C Library is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12    Library General Public License for more details.
13
14    You should have received a copy of the GNU Library General Public
15    License along with the GNU C Library; see the file COPYING.LIB.  If not,
16    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17    Boston, MA 02111-1307, USA.  */
18
19 /*
20  *      ISO C Standard, Amendment 1, 7.16.4
21  *      General wide-string utilities   <wchar.h>
22  */
23
24 #ifndef _WCHAR_H
25 #define _WCHAR_H 1
26
27 #include <features.h>
28
29 __BEGIN_DECLS
30
31 /* Get size_t, wchar_t, wint_t and NULL from <stddef.h>.  */
32 #define __need_size_t
33 #define __need_wchar_t
34 #define __need_wint_t
35 #define __need_NULL
36 #include <stddef.h>
37
38
39 /* We try to get wint_t from <stddef.h>, but not all GCC versions define it
40    there.  So define it ourselves if it remains undefined.  */
41 #ifndef _WINT_T
42 /* Integral type unchanged by default argument promotions that can
43    hold any value corresponding to members of the extended character
44    set, as well as at least one value that does not correspond to any
45    member of the extended character set.  */
46 # define _WINT_T
47 typedef unsigned int wint_t;
48 #endif
49
50
51 /* Conversion state information.  */
52 typedef struct
53 {
54   int count;            /* Number of bytes needed for the current character. */
55   wint_t value;         /* Value so far.  */
56 } mbstate_t;
57
58 #define WCHAR_MIN ((wchar_t) 0)
59 #define WCHAR_MAX (~WCHAR_MIN)
60
61 #ifndef WEOF
62 # define WEOF (0xffffffffu)
63 #endif
64
65
66 /* Copy SRC to DEST.  */
67 extern wchar_t *wcscpy __P ((wchar_t *__restrict __dest,
68                              __const wchar_t *__restrict __src));
69 /* Copy no more than N wide-characters of SRC to DEST.  */
70 extern wchar_t *wcsncpy __P ((wchar_t *__restrict __dest,
71                               __const wchar_t *__restrict __src, size_t __n));
72
73 /* Append SRC onto DEST.  */
74 extern wchar_t *wcscat __P ((wchar_t *__restrict __dest,
75                              __const wchar_t *__restrict __src));
76 /* Append no more than N wide-characters of SRC onto DEST.  */
77 extern wchar_t *wcsncat __P ((wchar_t *__restrict __dest,
78                               __const wchar_t *__restrict __src, size_t __n));
79
80 /* Compare S1 and S2.  */
81 extern int wcscmp __P ((__const wchar_t *__s1, __const wchar_t *__s2));
82 /* Compare N wide-characters of S1 and S2.  */
83 extern int wcsncmp __P ((__const wchar_t *__s1, __const wchar_t *__s2,
84                          size_t __n));
85
86 #ifdef __USE_GNU
87 /* Compare S1 and S2, ignoring case.  */
88 extern int __wcscasecmp __P ((__const wchar_t *__s1, __const wchar_t *__s2));
89 extern int wcscasecmp __P ((__const wchar_t *__s1, __const wchar_t *__s2));
90
91 /* Compare no more than N chars of S1 and S2, ignoring case.  */
92 extern int __wcsncasecmp __P ((__const wchar_t *__s1, __const wchar_t *__s2,
93                                size_t __n));
94 extern int wcsncasecmp __P ((__const wchar_t *__s1, __const wchar_t *__s2,
95                              size_t __n));
96
97 /* Similar to the two functions above but take the information from
98    the provided locale and not the global locale.  */
99 # include <xlocale.h>
100
101 extern int __wcscasecmp_l __P ((__const wchar_t *__s1, __const wchar_t *__s2,
102                                 __locale_t __loc));
103
104 extern int __wcsncasecmp_l __P ((__const wchar_t *__s1, __const wchar_t *__s2,
105                                  size_t __n, __locale_t __loc));
106 #endif
107
108 /* Compare S1 and S2, both interpreted as appropriate to the
109    LC_COLLATE category of the current locale.  */
110 extern int wcscoll __P ((__const wchar_t *__s1, __const wchar_t *__s2));
111 /* Transform S2 into array pointed to by S1 such that if wcscmp is
112    applied to two transformed strings the result is the as applying
113    `wcscoll' to the original strings.  */
114 extern size_t wcsxfrm __P ((wchar_t *__restrict __s1,
115                             __const wchar_t *__restrict __s2, size_t __n));
116
117 #ifdef __USE_GNU
118 /* Similar to the two functions above but take the information from
119    the provided locale and not the global locale.  */
120
121 /* Compare S1 and S2, both interpreted as appropriate to the
122    LC_COLLATE category of the given locale.  */
123 extern int __wcscoll_l __P ((__const wchar_t *__s1, __const wchar_t *__s2,
124                              __locale_t __loc));
125 /* Transform S2 into array pointed to by S1 such that if wcscmp is
126    applied to two transformed strings the result is the as applying
127    `wcscoll' to the original strings.  */
128 extern size_t __wcsxfrm_l __P ((wchar_t *__s1, __const wchar_t *__s2,
129                                 size_t __n, __locale_t __loc));
130
131 /* Duplicate S, returning an identical malloc'd string.  */
132 extern wchar_t *wcsdup __P ((__const wchar_t *__s));
133 #endif
134
135 /* Find the first occurrence of WC in WCS.  */
136 extern wchar_t *wcschr __P ((__const wchar_t *__wcs, wchar_t __wc));
137 /* Find the last occurrence of WC in WCS.  */
138 extern wchar_t *wcsrchr __P ((__const wchar_t *__wcs, wchar_t __wc));
139
140 /* Return the length of the initial segmet of WCS which
141    consists entirely of wide characters not in REJECT.  */
142 extern size_t wcscspn __P ((__const wchar_t *__wcs,
143                             __const wchar_t *__reject));
144 /* Return the length of the initial segmet of WCS which
145    consists entirely of wide characters in  ACCEPT.  */
146 extern size_t wcsspn __P ((__const wchar_t *__wcs, __const wchar_t *__accept));
147 /* Find the first occurrence in WCS of any character in ACCEPT.  */
148 extern wchar_t *wcspbrk __P ((__const wchar_t *__wcs,
149                               __const wchar_t *__accept));
150 /* Find the first occurrence of NEEDLE in HAYSTACK.  */
151 extern wchar_t *wcsstr __P ((__const wchar_t *__haystack,
152                              __const wchar_t *__needle));
153 /* Divide WCS into tokens separated by characters in DELIM.  */
154 extern wchar_t *wcstok __P ((wchar_t *__restrict __s,
155                              __const wchar_t *__restrict __delim,
156                              wchar_t **__restrict __ptr));
157
158 /* Return the number of wide characters in S.  */
159 extern size_t wcslen __P ((__const wchar_t *__s));
160
161
162 /* Search N wide characters of S for C.  */
163 extern wchar_t *wmemchr __P ((__const wchar_t *__s, wchar_t __c, size_t __n));
164
165 /* Compare N wide characters of S1 and S2.  */
166 extern int wmemcmp __P ((__const wchar_t *__restrict __s1,
167                          __const wchar_t *__restrict __s2, size_t __n));
168
169 /* Copy N wide characters of SRC to DEST.  */
170 extern wchar_t *wmemcpy __P ((wchar_t *__restrict __s1,
171                               __const wchar_t *__restrict __s2, size_t __n));
172
173 /* Copy N wide characters of SRC to DEST, guaranteeing
174    correct behavior for overlapping strings.  */
175 extern wchar_t *wmemmove __P ((wchar_t *__s1, __const wchar_t *__s2,
176                                size_t __n));
177
178 /* Set N wide characters of S to C.  */
179 extern wchar_t *wmemset __P ((wchar_t *__s, wchar_t __c, size_t __n));
180
181
182 /* Determine whether C constitutes a valid (one-byte) multibyte
183    character.  */
184 extern wint_t btowc __P ((int __c));
185
186 /* Determine whether C corresponds to a member of the extended
187    character set whose multibyte representation is a single byte.  */
188 extern int wctob __P ((wint_t __c));
189
190 /* Determine whether PS points to an object representing the initial
191    state.  */
192 extern int mbsinit __P ((__const mbstate_t *__ps));
193
194 /* Write wide character representation of multibyte character pointed
195    to by S to PWC.  */
196 extern size_t __mbrtowc __P ((wchar_t *__restrict __pwc,
197                               __const char *__restrict __s, size_t __n,
198                               mbstate_t *__restrict __p));
199 extern size_t mbrtowc __P ((wchar_t *__restrict __pwc,
200                             __const char *__restrict __s, size_t __n,
201                             mbstate_t *__p));
202
203 /* Write multibyte representation of wide character WC to S.  */
204 extern size_t __wcrtomb __P ((char *__restrict __s, wchar_t __wc,
205                               mbstate_t *__restrict __ps));
206 extern size_t wcrtomb __P ((char *__restrict __s, wchar_t __wc,
207                             mbstate_t *__restrict __ps));
208
209 /* Return number of bytes in multibyte character pointed to by S.  */
210 extern size_t __mbrlen __P ((__const char *__restrict __s, size_t __n,
211                              mbstate_t *__restrict __ps));
212 extern size_t mbrlen __P ((__const char *__restrict __s, size_t __n,
213                            mbstate_t *__restrict __ps));
214
215 #if defined __OPTIMIZE__ \
216     && (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 7))
217 /* Define inline function as optimization.  */
218 extern __inline size_t mbrlen (__const char *__restrict __s, size_t __n,
219                                mbstate_t *__restrict __ps)
220 { return (__ps != NULL
221           ? __mbrtowc (NULL, __s, __n, __ps) : __mbrlen (__s, __n, NULL)); }
222 #endif
223
224 /* Write wide character representation of multibyte character string
225    SRC to DST.  */
226 extern size_t __mbsrtowcs __P ((wchar_t *__restrict __dst,
227                                 __const char **__restrict __src,
228                                 size_t __len, mbstate_t *__restrict __ps));
229 extern size_t mbsrtowcs __P ((wchar_t *__restrict __dst,
230                               __const char **__restrict __src,
231                               size_t __len, mbstate_t *__restrict __ps));
232
233 /* Write multibyte character representation of wide character string
234    SRC to DST.  */
235 extern size_t __wcsrtombs __P ((char *__restrict __dst,
236                                 __const wchar_t **__restrict __src,
237                                 size_t __len, mbstate_t *__restrict __ps));
238 extern size_t wcsrtombs __P ((char *__restrict __dst,
239                               __const wchar_t **__restrict __src,
240                               size_t __len, mbstate_t *__restrict __ps));
241
242
243 #ifdef  __USE_GNU
244 /* Write wide character representation of at most NMC bytes of the
245    multibyte character string SRC to DST.  */
246 extern size_t __mbsnrtowcs __P ((wchar_t *__restrict __dst,
247                                  __const char **__restrict __src, size_t __nmc,
248                                  size_t __len, mbstate_t *__restrict __ps));
249 extern size_t mbsnrtowcs __P ((wchar_t *__restrict __dst,
250                                __const char **__restrict __src, size_t __nmc,
251                                size_t __len, mbstate_t *__restrict __ps));
252
253 /* Write multibyte character representation of at most NWC characters
254    from the wide character string SRC to DST.  */
255 extern size_t __wcsnrtombs __P ((char *__restrict __dst,
256                                  __const wchar_t **__restrict __src,
257                                  size_t __nwc, size_t __len,
258                                  mbstate_t *__restrict __ps));
259 extern size_t wcsnrtombs __P ((char *__restrict __dst,
260                                __const wchar_t **__restrict __src,
261                                size_t __nwc, size_t __len,
262                                mbstate_t *__restrict __ps));
263
264
265 /* The following functions are extensions found in X/Open CAE.  */
266
267 /* Determine number of column positions required for C.  */
268 extern int wcwidth __P ((wint_t __c));
269
270 /* Determine number of column positions required for first N wide
271    characters (or fewer if S ends before this) in S.  */
272 extern int wcswidth __P ((__const wchar_t *__s, size_t __n));
273 #endif  /* use GNU */
274
275
276 /* Convert initial portion of the wide string NPTR to `double'
277    representation.  */
278 extern double wcstod __P ((__const wchar_t *__restrict __nptr,
279                            wchar_t **__restrict __endptr));
280
281 #ifdef __USE_GNU
282 /* Likewise for `float' and `long double' sizes of floating-point numbers.  */
283 extern float wcstof __P ((__const wchar_t *__restrict __nptr,
284                           wchar_t **__restrict __endptr));
285 extern __long_double_t wcstold __P ((__const wchar_t *__restrict __nptr,
286                                      wchar_t **__restrict __endptr));
287 #endif /* GNU */
288
289
290 /* Convert initial portion of wide string NPTR to `long int'
291    representation.  */
292 extern long int wcstol __P ((__const wchar_t *__restrict __nptr,
293                              wchar_t **__restrict __endptr, int __base));
294
295 /* Convert initial portion of wide string NPTR to `unsigned long int'
296    representation.  */
297 extern unsigned long int wcstoul __P ((__const wchar_t *__restrict __nptr,
298                                        wchar_t **__restrict __endptr,
299                                        int __base));
300
301 #if defined __GNUC__ && defined __USE_GNU
302 /* Convert initial portion of wide string NPTR to `long int'
303    representation.  */
304 extern long long int wcstoq __P ((__const wchar_t *__restrict __nptr,
305                                   wchar_t **__restrict __endptr, int __base));
306
307 /* Convert initial portion of wide string NPTR to `unsigned long long int'
308    representation.  */
309 extern unsigned long long int wcstouq __P ((__const wchar_t *__restrict __nptr,
310                                             wchar_t **__restrict __endptr,
311                                             int __base));
312 #endif /* GCC and use GNU.  */
313
314 #if defined __USE_ISOC9X || (defined __GNUC__ && defined __USE_GNU)
315 /* Convert initial portion of wide string NPTR to `long int'
316    representation.  */
317 extern long long int wcstoll __P ((__const wchar_t *__restrict __nptr,
318                                    wchar_t **__restrict __endptr, int __base));
319
320 /* Convert initial portion of wide string NPTR to `unsigned long long int'
321    representation.  */
322 extern unsigned long long int wcstoull __P ((__const wchar_t *
323                                              __restrict __nptr,
324                                              wchar_t **__restrict __endptr,
325                                              int __base));
326 #endif /* ISO C 9X or GCC and GNU.  */
327
328 #ifdef __USE_GNU
329 /* The concept of one static locale per category is not very well
330    thought out.  Many applications will need to process its data using
331    information from several different locales.  Another application is
332    the implementation of the internationalization handling in the
333    upcoming ISO C++ standard library.  To support this another set of
334    the functions using locale data exist which have an additional
335    argument.
336
337    Attention: all these functions are *not* standardized in any form.
338    This is a proof-of-concept implementation.  */
339
340 /* Structure for reentrant locale using functions.  This is an
341    (almost) opaque type for the user level programs.  */
342 # include <xlocale.h>
343
344 /* Special versions of the functions above which take the locale to
345    use as an additional parameter.  */
346 extern long int __wcstol_l __P ((__const wchar_t *__restrict __nptr,
347                                  wchar_t **__restrict __endptr, int __base,
348                                  __locale_t __loc));
349
350 extern unsigned long int __wcstoul_l __P ((__const wchar_t *__restrict __nptr,
351                                            wchar_t **__restrict __endptr,
352                                            int __base, __locale_t __loc));
353
354 extern long long int __wcstoll_l __P ((__const wchar_t *__restrict __nptr,
355                                        wchar_t **__restrict __endptr,
356                                        int __base, __locale_t __loc));
357
358 extern unsigned long long int __wcstoull_l __P ((__const wchar_t *__restrict
359                                                  __nptr,
360                                                  wchar_t **__restrict __endptr,
361                                                  int __base,
362                                                  __locale_t __loc));
363
364 extern double __wcstod_l __P ((__const wchar_t *__restrict __nptr,
365                                wchar_t **__restrict __endptr,
366                                __locale_t __loc));
367
368 extern float __wcstof_l __P ((__const wchar_t *__restrict __nptr,
369                               wchar_t **__restrict __endptr,
370                               __locale_t __loc));
371
372 extern __long_double_t __wcstold_l __P ((__const wchar_t *__restrict __nptr,
373                                          wchar_t **__restrict __endptr,
374                                          __locale_t __loc));
375 #endif /* GNU */
376
377
378 /* The internal entry points for `wcstoX' take an extra flag argument
379    saying whether or not to parse locale-dependent number grouping.  */
380 extern double __wcstod_internal __P ((__const wchar_t *__restrict __nptr,
381                                       wchar_t **__restrict __endptr,
382                                       int __group));
383 extern float __wcstof_internal __P ((__const wchar_t *__restrict __nptr,
384                                      wchar_t **__restrict __endptr,
385                                      int __group));
386 extern __long_double_t __wcstold_internal __P ((__const wchar_t *
387                                                 __restrict __nptr,
388                                                 wchar_t **__restrict __endptr,
389                                                 int __group));
390
391 extern long int __wcstol_internal __P ((__const wchar_t *__restrict __nptr,
392                                         wchar_t **__restrict __endptr,
393                                         int __base, int __group));
394 extern unsigned long int __wcstoul_internal __P ((__const wchar_t *
395                                                   __restrict __nptr,
396                                                   wchar_t **
397                                                   __restrict __endptr,
398                                                   int __base, int __group));
399 #if defined __GNUC__ && defined __USE_GNU
400 extern long long int __wcstoll_internal __P ((__const wchar_t *
401                                               __restrict __nptr,
402                                               wchar_t **__restrict __endptr,
403                                               int __base, int __group));
404 extern unsigned long long int __wcstoull_internal __P ((__const wchar_t *
405                                                         __restrict __nptr,
406                                                         wchar_t **
407                                                         __restrict __endptr,
408                                                         int __base,
409                                                         int __group));
410 #endif /* GCC and use GNU.  */
411
412
413 #if defined __OPTIMIZE__ && __GNUC__ >= 2
414 /* Define inline functions which call the internal entry points.  */
415
416 extern __inline double wcstod (__const wchar_t *__restrict __nptr,
417                                wchar_t **__restrict __endptr)
418 { return __wcstod_internal (__nptr, __endptr, 0); }
419 extern __inline long int wcstol (__const wchar_t *__restrict __nptr,
420                                  wchar_t **__restrict __endptr, int __base)
421 { return __wcstol_internal (__nptr, __endptr, __base, 0); }
422 extern __inline unsigned long int wcstoul (__const wchar_t *__restrict __nptr,
423                                            wchar_t **__restrict __endptr,
424                                            int __base)
425 { return __wcstoul_internal (__nptr, __endptr, __base, 0); }
426
427 # ifdef __USE_GNU
428 extern __inline float wcstof (__const wchar_t *__restrict __nptr,
429                               wchar_t **__restrict __endptr)
430 { return __wcstof_internal (__nptr, __endptr, 0); }
431 extern __inline __long_double_t wcstold (__const wchar_t *__restrict __nptr,
432                                          wchar_t **__restrict __endptr)
433 { return __wcstold_internal (__nptr, __endptr, 0); }
434
435
436 extern __inline long long int wcstoq (__const wchar_t *__restrict __nptr,
437                                       wchar_t **__restrict __endptr,
438                                       int __base)
439 { return __wcstoll_internal (__nptr, __endptr, __base, 0); }
440 extern __inline unsigned long long int wcstouq (__const wchar_t *
441                                                 __restrict __nptr,
442                                                 wchar_t **__restrict __endptr,
443                                                 int __base)
444 { return __wcstoull_internal (__nptr, __endptr, __base, 0); }
445 # endif /* Use GNU.  */
446 #endif /* Optimizing GCC >=2.  */
447
448
449 #ifdef  __USE_GNU
450 /* Copy SRC to DEST, returning the address of the terminating L'\0' in
451    DEST.  */
452 extern wchar_t *__wcpcpy __P ((wchar_t *__dest, __const wchar_t *__src));
453 extern wchar_t *wcpcpy __P ((wchar_t *__dest, __const wchar_t *__src));
454
455 /* Copy no more than N characters of SRC to DEST, returning the address of
456    the last character written into DEST.  */
457 extern wchar_t *__wcpncpy __P ((wchar_t *__dest, __const wchar_t *__src,
458                                 size_t __n));
459 extern wchar_t *wcpncpy __P ((wchar_t *__dest, __const wchar_t *__src,
460                               size_t __n));
461 #endif  /* use GNU */
462
463
464 __END_DECLS
465
466 #endif /* wchar.h  */