1/* Elementary Unicode string functions.
2   Copyright (C) 2002, 2005-2007, 2009-2010 Free Software Foundation, Inc.
3
4   This program is free software: you can redistribute it and/or modify it
5   under the terms of the GNU Lesser General Public License as published
6   by the Free Software Foundation; either version 3 of the License, or
7   (at your option) any later version.
8
9   This program 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   Lesser General Public License for more details.
13
14   You should have received a copy of the GNU Lesser General Public License
15   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
16
17#ifndef _UNISTDIO_H
18#define _UNISTDIO_H
19
20#include "unitypes.h"
21
22/* Get size_t.  */
23#include <stddef.h>
24
25/* Get FILE.  */
26#include <stdio.h>
27
28/* Get va_list.  */
29#include <stdarg.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/* These work like the printf function family.
36   In the format string:
37   The format directive 'U' takes an UTF-8 string (const uint8_t *).
38   The format directive 'lU' takes an UTF-16 string (const uint16_t *).
39   The format directive 'llU' takes an UTF-32 string (const uint32_t *).
40
41   The prefix (ulc_, u8_, u16_, u16_) indicates the type of the resulting
42   string.  The prefix 'ulc' stands for "locale encoded".
43
44   An infix 'v' indicates that a va_list is passed instead of multiple
45   arguments.
46
47   The functions *sprintf have a 'buf' argument that is assumed to be large
48   enough.  (DANGEROUS!  Overflowing the buffer will crash the program.)
49   The functions *snprintf have a 'buf' argument that is assumed to be 'size'
50   units large.  (DANGEROUS!  The resulting string might be truncated in the
51   middle of a multibyte character.)
52   The functions *asprintf have a 'resultp' argument.  The result will be
53   freshly allocated and stored in *resultp.
54   The functions *asnprintf have a (resultbuf, lengthp) argument pair.  If
55   resultbuf is not NULL and the result fits into *lengthp units, it is put
56   in resultbuf, and resultbuf is returned.  Otherwise, a freshly allocated
57   string is returned.  In both cases, *lengthp is set to the length (number
58   of units) of the returned string.  In case of error, NULL is returned and
59   errno is set.
60 */
61
62/* ASCII format string, result in locale dependent encoded 'char *'.  */
63extern int
64       ulc_sprintf (char *buf,
65                    const char *format, ...);
66extern int
67       ulc_snprintf (char *buf, size_t size,
68                     const char *format, ...);
69extern int
70       ulc_asprintf (char **resultp,
71                     const char *format, ...);
72extern char *
73       ulc_asnprintf (char *resultbuf, size_t *lengthp,
74                      const char *format, ...);
75extern int
76       ulc_vsprintf (char *buf,
77                     const char *format, va_list ap);
78extern int
79       ulc_vsnprintf (char *buf, size_t size,
80                      const char *format, va_list ap);
81extern int
82       ulc_vasprintf (char **resultp,
83                      const char *format, va_list ap);
84extern char *
85       ulc_vasnprintf (char *resultbuf, size_t *lengthp,
86                       const char *format, va_list ap);
87
88/* ASCII format string, result in UTF-8 format.  */
89extern int
90       u8_sprintf (uint8_t *buf,
91                   const char *format, ...);
92extern int
93       u8_snprintf (uint8_t *buf, size_t size,
94                    const char *format, ...);
95extern int
96       u8_asprintf (uint8_t **resultp,
97                    const char *format, ...);
98extern uint8_t *
99       u8_asnprintf (uint8_t *resultbuf, size_t *lengthp,
100                     const char *format, ...);
101extern int
102       u8_vsprintf (uint8_t *buf,
103                    const char *format, va_list ap);
104extern int
105       u8_vsnprintf (uint8_t *buf, size_t size,
106                     const char *format, va_list ap);
107extern int
108       u8_vasprintf (uint8_t **resultp,
109                     const char *format, va_list ap);
110extern uint8_t *
111       u8_vasnprintf (uint8_t *resultbuf, size_t *lengthp,
112                      const char *format, va_list ap);
113
114/* UTF-8 format string, result in UTF-8 format.  */
115extern int
116       u8_u8_sprintf (uint8_t *buf,
117                      const uint8_t *format, ...);
118extern int
119       u8_u8_snprintf (uint8_t *buf, size_t size,
120                       const uint8_t *format, ...);
121extern int
122       u8_u8_asprintf (uint8_t **resultp,
123                       const uint8_t *format, ...);
124extern uint8_t *
125       u8_u8_asnprintf (uint8_t *resultbuf, size_t *lengthp,
126                        const uint8_t *format, ...);
127extern int
128       u8_u8_vsprintf (uint8_t *buf,
129                       const uint8_t *format, va_list ap);
130extern int
131       u8_u8_vsnprintf (uint8_t *buf, size_t size,
132                        const uint8_t *format, va_list ap);
133extern int
134       u8_u8_vasprintf (uint8_t **resultp,
135                        const uint8_t *format, va_list ap);
136extern uint8_t *
137       u8_u8_vasnprintf (uint8_t *resultbuf, size_t *lengthp,
138                         const uint8_t *format, va_list ap);
139
140/* ASCII format string, result in UTF-16 format.  */
141extern int
142       u16_sprintf (uint16_t *buf,
143                    const char *format, ...);
144extern int
145       u16_snprintf (uint16_t *buf, size_t size,
146                     const char *format, ...);
147extern int
148       u16_asprintf (uint16_t **resultp,
149                     const char *format, ...);
150extern uint16_t *
151       u16_asnprintf (uint16_t *resultbuf, size_t *lengthp,
152                      const char *format, ...);
153extern int
154       u16_vsprintf (uint16_t *buf,
155                     const char *format, va_list ap);
156extern int
157       u16_vsnprintf (uint16_t *buf, size_t size,
158                      const char *format, va_list ap);
159extern int
160       u16_vasprintf (uint16_t **resultp,
161                      const char *format, va_list ap);
162extern uint16_t *
163       u16_vasnprintf (uint16_t *resultbuf, size_t *lengthp,
164                       const char *format, va_list ap);
165
166/* UTF-16 format string, result in UTF-16 format.  */
167extern int
168       u16_u16_sprintf (uint16_t *buf,
169                        const uint16_t *format, ...);
170extern int
171       u16_u16_snprintf (uint16_t *buf, size_t size,
172                         const uint16_t *format, ...);
173extern int
174       u16_u16_asprintf (uint16_t **resultp,
175                         const uint16_t *format, ...);
176extern uint16_t *
177       u16_u16_asnprintf (uint16_t *resultbuf, size_t *lengthp,
178                          const uint16_t *format, ...);
179extern int
180       u16_u16_vsprintf (uint16_t *buf,
181                         const uint16_t *format, va_list ap);
182extern int
183       u16_u16_vsnprintf (uint16_t *buf, size_t size,
184                          const uint16_t *format, va_list ap);
185extern int
186       u16_u16_vasprintf (uint16_t **resultp,
187                          const uint16_t *format, va_list ap);
188extern uint16_t *
189       u16_u16_vasnprintf (uint16_t *resultbuf, size_t *lengthp,
190                           const uint16_t *format, va_list ap);
191
192/* ASCII format string, result in UTF-32 format.  */
193extern int
194       u32_sprintf (uint32_t *buf,
195                    const char *format, ...);
196extern int
197       u32_snprintf (uint32_t *buf, size_t size,
198                     const char *format, ...);
199extern int
200       u32_asprintf (uint32_t **resultp,
201                     const char *format, ...);
202extern uint32_t *
203       u32_asnprintf (uint32_t *resultbuf, size_t *lengthp,
204                      const char *format, ...);
205extern int
206       u32_vsprintf (uint32_t *buf,
207                     const char *format, va_list ap);
208extern int
209       u32_vsnprintf (uint32_t *buf, size_t size,
210                      const char *format, va_list ap);
211extern int
212       u32_vasprintf (uint32_t **resultp,
213                      const char *format, va_list ap);
214extern uint32_t *
215       u32_vasnprintf (uint32_t *resultbuf, size_t *lengthp,
216                       const char *format, va_list ap);
217
218/* UTF-32 format string, result in UTF-32 format.  */
219extern int
220       u32_u32_sprintf (uint32_t *buf,
221                        const uint32_t *format, ...);
222extern int
223       u32_u32_snprintf (uint32_t *buf, size_t size,
224                         const uint32_t *format, ...);
225extern int
226       u32_u32_asprintf (uint32_t **resultp,
227                         const uint32_t *format, ...);
228extern uint32_t *
229       u32_u32_asnprintf (uint32_t *resultbuf, size_t *lengthp,
230                          const uint32_t *format, ...);
231extern int
232       u32_u32_vsprintf (uint32_t *buf,
233                         const uint32_t *format, va_list ap);
234extern int
235       u32_u32_vsnprintf (uint32_t *buf, size_t size,
236                          const uint32_t *format, va_list ap);
237extern int
238       u32_u32_vasprintf (uint32_t **resultp,
239                          const uint32_t *format, va_list ap);
240extern uint32_t *
241       u32_u32_vasnprintf (uint32_t *resultbuf, size_t *lengthp,
242                           const uint32_t *format, va_list ap);
243
244/* ASCII format string, output to FILE in locale dependent encoding.  */
245extern int
246       ulc_fprintf (FILE *stream,
247                    const char *format, ...);
248extern int
249       ulc_vfprintf (FILE *stream,
250                     const char *format, va_list ap);
251
252#ifdef __cplusplus
253}
254#endif
255
256#endif /* _UNISTDIO_H */
257