lib/unistdio.h

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