lib/unistdio.in.h

   1 /* Elementary Unicode string functions.
   2    Copyright (C) 2002, 2005-2007, 2009-2020 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 <https://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
  32 extern "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 *'.  */
  63 extern int
  64        ulc_sprintf (char *_UC_RESTRICT buf,
  65                     const char *format, ...);
  66 extern int
  67        ulc_snprintf (char *_UC_RESTRICT buf, size_t size,
  68                      const char *format, ...);
  69 extern int
  70        ulc_asprintf (char **resultp,
  71                      const char *format, ...);
  72 extern char *
  73        ulc_asnprintf (char *_UC_RESTRICT resultbuf, size_t *lengthp,
  74                       const char *format, ...);
  75 extern int
  76        ulc_vsprintf (char *_UC_RESTRICT buf,
  77                      const char *format, va_list ap);
  78 extern int
  79        ulc_vsnprintf (char *_UC_RESTRICT buf, size_t size,
  80                       const char *format, va_list ap);
  81 extern int
  82        ulc_vasprintf (char **resultp,
  83                       const char *format, va_list ap);
  84 extern char *
  85        ulc_vasnprintf (char *_UC_RESTRICT resultbuf, size_t *lengthp,
  86                        const char *format, va_list ap);
  87
  88 /* ASCII format string, result in UTF-8 format.  */
  89 extern int
  90        u8_sprintf (uint8_t *buf,
  91                    const char *format, ...);
  92 extern int
  93        u8_snprintf (uint8_t *buf, size_t size,
  94                     const char *format, ...);
  95 extern int
  96        u8_asprintf (uint8_t **resultp,
  97                     const char *format, ...);
  98 extern uint8_t *
  99        u8_asnprintf (uint8_t *resultbuf, size_t *lengthp,
 100                      const char *format, ...);
 101 extern int
 102        u8_vsprintf (uint8_t *buf,
 103                     const char *format, va_list ap);
 104 extern int
 105        u8_vsnprintf (uint8_t *buf, size_t size,
 106                      const char *format, va_list ap);
 107 extern int
 108        u8_vasprintf (uint8_t **resultp,
 109                      const char *format, va_list ap);
 110 extern 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.  */
 115 extern int
 116        u8_u8_sprintf (uint8_t *_UC_RESTRICT buf,
 117                       const uint8_t *format, ...);
 118 extern int
 119        u8_u8_snprintf (uint8_t *_UC_RESTRICT buf, size_t size,
 120                        const uint8_t *format, ...);
 121 extern int
 122        u8_u8_asprintf (uint8_t **resultp,
 123                        const uint8_t *format, ...);
 124 extern uint8_t *
 125        u8_u8_asnprintf (uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp,
 126                         const uint8_t *format, ...);
 127 extern int
 128        u8_u8_vsprintf (uint8_t *_UC_RESTRICT buf,
 129                        const uint8_t *format, va_list ap);
 130 extern int
 131        u8_u8_vsnprintf (uint8_t *_UC_RESTRICT buf, size_t size,
 132                         const uint8_t *format, va_list ap);
 133 extern int
 134        u8_u8_vasprintf (uint8_t **resultp,
 135                         const uint8_t *format, va_list ap);
 136 extern uint8_t *
 137        u8_u8_vasnprintf (uint8_t *_UC_RESTRICT resultbuf, size_t *lengthp,
 138                          const uint8_t *format, va_list ap);
 139
 140 /* ASCII format string, result in UTF-16 format.  */
 141 extern int
 142        u16_sprintf (uint16_t *buf,
 143                     const char *format, ...);
 144 extern int
 145        u16_snprintf (uint16_t *buf, size_t size,
 146                      const char *format, ...);
 147 extern int
 148        u16_asprintf (uint16_t **resultp,
 149                      const char *format, ...);
 150 extern uint16_t *
 151        u16_asnprintf (uint16_t *resultbuf, size_t *lengthp,
 152                       const char *format, ...);
 153 extern int
 154        u16_vsprintf (uint16_t *buf,
 155                      const char *format, va_list ap);
 156 extern int
 157        u16_vsnprintf (uint16_t *buf, size_t size,
 158                       const char *format, va_list ap);
 159 extern int
 160        u16_vasprintf (uint16_t **resultp,
 161                       const char *format, va_list ap);
 162 extern 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.  */
 167 extern int
 168        u16_u16_sprintf (uint16_t *_UC_RESTRICT buf,
 169                         const uint16_t *format, ...);
 170 extern int
 171        u16_u16_snprintf (uint16_t *_UC_RESTRICT buf, size_t size,
 172                          const uint16_t *format, ...);
 173 extern int
 174        u16_u16_asprintf (uint16_t **resultp,
 175                          const uint16_t *format, ...);
 176 extern uint16_t *
 177        u16_u16_asnprintf (uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp,
 178                           const uint16_t *format, ...);
 179 extern int
 180        u16_u16_vsprintf (uint16_t *_UC_RESTRICT buf,
 181                          const uint16_t *format, va_list ap);
 182 extern int
 183        u16_u16_vsnprintf (uint16_t *_UC_RESTRICT buf, size_t size,
 184                           const uint16_t *format, va_list ap);
 185 extern int
 186        u16_u16_vasprintf (uint16_t **resultp,
 187                           const uint16_t *format, va_list ap);
 188 extern uint16_t *
 189        u16_u16_vasnprintf (uint16_t *_UC_RESTRICT resultbuf, size_t *lengthp,
 190                            const uint16_t *format, va_list ap);
 191
 192 /* ASCII format string, result in UTF-32 format.  */
 193 extern int
 194        u32_sprintf (uint32_t *buf,
 195                     const char *format, ...);
 196 extern int
 197        u32_snprintf (uint32_t *buf, size_t size,
 198                      const char *format, ...);
 199 extern int
 200        u32_asprintf (uint32_t **resultp,
 201                      const char *format, ...);
 202 extern uint32_t *
 203        u32_asnprintf (uint32_t *resultbuf, size_t *lengthp,
 204                       const char *format, ...);
 205 extern int
 206        u32_vsprintf (uint32_t *buf,
 207                      const char *format, va_list ap);
 208 extern int
 209        u32_vsnprintf (uint32_t *buf, size_t size,
 210                       const char *format, va_list ap);
 211 extern int
 212        u32_vasprintf (uint32_t **resultp,
 213                       const char *format, va_list ap);
 214 extern 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.  */
 219 extern int
 220        u32_u32_sprintf (uint32_t *_UC_RESTRICT buf,
 221                         const uint32_t *format, ...);
 222 extern int
 223        u32_u32_snprintf (uint32_t *_UC_RESTRICT buf, size_t size,
 224                          const uint32_t *format, ...);
 225 extern int
 226        u32_u32_asprintf (uint32_t **resultp,
 227                          const uint32_t *format, ...);
 228 extern uint32_t *
 229        u32_u32_asnprintf (uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp,
 230                           const uint32_t *format, ...);
 231 extern int
 232        u32_u32_vsprintf (uint32_t *_UC_RESTRICT buf,
 233                          const uint32_t *format, va_list ap);
 234 extern int
 235        u32_u32_vsnprintf (uint32_t *_UC_RESTRICT buf, size_t size,
 236                           const uint32_t *format, va_list ap);
 237 extern int
 238        u32_u32_vasprintf (uint32_t **resultp,
 239                           const uint32_t *format, va_list ap);
 240 extern uint32_t *
 241        u32_u32_vasnprintf (uint32_t *_UC_RESTRICT resultbuf, size_t *lengthp,
 242                            const uint32_t *format, va_list ap);
 243
 244 /* ASCII format string, output to FILE in locale dependent encoding.  */
 245 extern int
 246        ulc_fprintf (FILE *stream,
 247                     const char *format, ...);
 248 extern 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 */