lib/unistdio.in.h

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