lib/string-buffer.h

   1 /* A buffer that accumulates a string by piecewise concatenation.
   2    Copyright (C) 2021-2024 Free Software Foundation, Inc.
   3
   4    This file is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU Lesser General Public License as
   6    published by the Free Software Foundation, either version 3 of the
   7    License, or (at your option) any later version.
   8
   9    This file 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
  12    GNU 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 /* Written by Bruno Haible <bruno@clisp.org>, 2021.  */
  18
  19 #ifndef _STRING_BUFFER_H
  20 #define _STRING_BUFFER_H
  21
  22 /* This file uses _GL_ATTRIBUTE_MALLOC, _GL_ATTRIBUTE_RETURNS_NONNULL,
  23    _GL_ATTRIBUTE_CAPABILITY_TYPE, _GL_ATTRIBUTE_ACQUIRE_CAPABILITY,
  24    _GL_ATTRIBUTE_RELEASE_CAPABILITY.  */
  25 #if !_GL_CONFIG_H_INCLUDED
  26  #error "Please include config.h first."
  27 #endif
  28
  29 #include <stdarg.h>
  30 #include <stdlib.h>
  31
  32 #include "attribute.h"
  33 #include "string-desc.h"
  34
  35 typedef char * _GL_ATTRIBUTE_CAPABILITY_TYPE ("memory resource")
  36         sb_heap_allocated_pointer_t;
  37
  38 /* A string buffer type.  */
  39 struct string_buffer
  40 {
  41   sb_heap_allocated_pointer_t data;
  42   size_t length;     /* used bytes, <= allocated */
  43   size_t allocated;  /* allocated bytes */
  44   bool error;        /* true if there was an error */
  45   char space[1024];  /* stack allocated space */
  46 };
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /* ================== Functions in module 'string-buffer' ================== */
  53
  54 /* Initializes BUFFER to the empty string.  */
  55 extern void sb_init (struct string_buffer *buffer)
  56   _GL_ATTRIBUTE_ACQUIRE_CAPABILITY (buffer->data);
  57
  58 /* Appends the character C to BUFFER.
  59    Returns 0, or -1 in case of out-of-memory error.  */
  60 extern int sb_append1 (struct string_buffer *buffer, char c);
  61
  62 /* Appends the contents of the memory area S to BUFFER.
  63    Returns 0, or -1 in case of out-of-memory error.  */
  64 extern int sb_append_desc (struct string_buffer *buffer, string_desc_t s);
  65
  66 /* Appends the contents of the C string STR to BUFFER.
  67    Returns 0, or -1 in case of out-of-memory error.  */
  68 extern int sb_append_c (struct string_buffer *buffer, const char *str);
  69
  70 /* Appends the result of the printf-compatible FORMATSTRING with the argument
  71    list LIST to BUFFER.
  72    Returns 0, or -1 with errno set in case of error.
  73    Error code EOVERFLOW can only occur when a width > INT_MAX is used.
  74    Therefore, if the format string is valid and does not use %ls/%lc
  75    directives nor widths, the only possible error code is ENOMEM.  */
  76 extern int sb_appendvf (struct string_buffer *buffer,
  77                         const char *formatstring, va_list list)
  78   #if (__GNUC__ + (__GNUC_MINOR__ >= 4) > 4) && !defined __clang__
  79   ATTRIBUTE_FORMAT ((__gnu_printf__, 2, 0))
  80   #else
  81   ATTRIBUTE_FORMAT ((__printf__, 2, 0))
  82   #endif
  83   ;
  84
  85 /* Appends the result of the printf-compatible FORMATSTRING with the following
  86    arguments to BUFFER.
  87    Returns 0, or -1 with errno set in case of error.
  88    Error code EOVERFLOW can only occur when a width > INT_MAX is used.
  89    Therefore, if the format string is valid and does not use %ls/%lc
  90    directives nor widths, the only possible error code is ENOMEM.  */
  91 extern int sb_appendf (struct string_buffer *buffer,
  92                        const char *formatstring, ...)
  93   #if (__GNUC__ + (__GNUC_MINOR__ >= 4) > 4) && !defined __clang__
  94   ATTRIBUTE_FORMAT ((__gnu_printf__, 2, 3))
  95   #else
  96   ATTRIBUTE_FORMAT ((__printf__, 2, 3))
  97   #endif
  98   ;
  99
 100 /* Frees the memory held by BUFFER.  */
 101 extern void sb_free (struct string_buffer *buffer)
 102   _GL_ATTRIBUTE_RELEASE_CAPABILITY (buffer->data);
 103
 104 /* Returns a read-only view of the current contents of BUFFER.
 105    The result is only valid until the next operation on BUFFER.  */
 106 extern string_desc_t sb_contents (struct string_buffer *buffer);
 107
 108 /* Ensures the contents of BUFFER is followed by a NUL byte (without
 109    incrementing the length of the contents).
 110    Then returns a read-only view of the current contents of BUFFER,
 111    that is, the current contents of BUFFER as a C string.
 112    Returns NULL upon out-of-memory error.
 113    The result is only valid until the next operation on BUFFER.  */
 114 extern const char * sb_contents_c (struct string_buffer *buffer);
 115
 116 /* Returns the contents of BUFFER and frees all other memory held by BUFFER.
 117    Returns NULL upon failure or if there was an error earlier.
 118    It is the responsibility of the caller to string_desc_free() the result.  */
 119 extern string_desc_t sb_dupfree (struct string_buffer *buffer)
 120   _GL_ATTRIBUTE_RELEASE_CAPABILITY (buffer->data);
 121
 122 /* Returns the contents of BUFFER (with an added trailing NUL, that is,
 123    as a C string), and frees all other memory held by BUFFER.
 124    Returns NULL upon failure or if there was an error earlier.
 125    It is the responsibility of the caller to free() the result.  */
 126 extern char * sb_dupfree_c (struct string_buffer *buffer)
 127   _GL_ATTRIBUTE_RELEASE_CAPABILITY (buffer->data);
 128
 129 /* ================== Functions in module 'xstring-buffer' ================== */
 130
 131 #if GNULIB_XSTRING_BUFFER
 132
 133 /* The following functions invoke xalloc_die () in case of out-of-memory
 134    error.  */
 135
 136 /* Appends the character C to BUFFER.  */
 137 extern void sb_xappend1 (struct string_buffer *buffer, char c);
 138
 139 /* Appends the contents of the memory area S to BUFFER.  */
 140 extern void sb_xappend_desc (struct string_buffer *buffer, string_desc_t s);
 141
 142 /* Appends the contents of the C string STR to BUFFER.  */
 143 extern void sb_xappend_c (struct string_buffer *buffer, const char *str);
 144
 145 /* Appends the result of the printf-compatible FORMATSTRING with the argument
 146    list LIST to BUFFER.
 147    Returns 0, or -1 in case of error other than out-of-memory error.
 148    Error code EOVERFLOW can only occur when a width > INT_MAX is used.
 149    Therefore, if the format string is valid and does not use %ls/%lc
 150    directives nor widths, no error is possible.  */
 151 extern int sb_xappendvf (struct string_buffer *buffer,
 152                          const char *formatstring, va_list list)
 153   #if (__GNUC__ + (__GNUC_MINOR__ >= 4) > 4) && !defined __clang__
 154   ATTRIBUTE_FORMAT ((__gnu_printf__, 2, 0))
 155   #else
 156   ATTRIBUTE_FORMAT ((__printf__, 2, 0))
 157   #endif
 158   ;
 159
 160 /* Appends the result of the printf-compatible FORMATSTRING with the following
 161    arguments to BUFFER.
 162    Returns 0, or -1 in case of error other than out-of-memory error.
 163    Error code EOVERFLOW can only occur when a width > INT_MAX is used.
 164    Therefore, if the format string is valid and does not use %ls/%lc
 165    directives nor widths, no error is possible.  */
 166 extern int sb_xappendf (struct string_buffer *buffer,
 167                         const char *formatstring, ...)
 168   #if (__GNUC__ + (__GNUC_MINOR__ >= 4) > 4) && !defined __clang__
 169   ATTRIBUTE_FORMAT ((__gnu_printf__, 2, 3))
 170   #else
 171   ATTRIBUTE_FORMAT ((__printf__, 2, 3))
 172   #endif
 173   ;
 174
 175 /* Ensures the contents of BUFFER is followed by a NUL byte (without
 176    incrementing the length of the contents).
 177    Then returns a read-only view of the current contents of BUFFER,
 178    that is, the current contents of BUFFER as a C string.
 179    The result is only valid until the next operation on BUFFER.  */
 180 extern const char * sb_xcontents_c (struct string_buffer *buffer)
 181   _GL_ATTRIBUTE_RETURNS_NONNULL;
 182
 183 /* Returns the contents of BUFFER and frees all other memory held by BUFFER.
 184    Returns (0, NULL) if there was an error earlier.
 185    It is the responsibility of the caller to string_desc_free() the result.  */
 186 extern string_desc_t sb_xdupfree (struct string_buffer *buffer)
 187   _GL_ATTRIBUTE_RELEASE_CAPABILITY (buffer->data);
 188
 189 /* Returns the contents of BUFFER (with an added trailing NUL, that is,
 190    as a C string), and frees all other memory held by BUFFER.
 191    Returns NULL if there was an error earlier.
 192    It is the responsibility of the caller to free() the result.  */
 193 extern char * sb_xdupfree_c (struct string_buffer *buffer)
 194   _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
 195   _GL_ATTRIBUTE_RELEASE_CAPABILITY (buffer->data);
 196
 197 #endif /* GNULIB_XSTRING_BUFFER */
 198
 199 /* ========================================================================== */
 200
 201 #ifdef __cplusplus
 202 }
 203 #endif
 204
 205 #endif /* _STRING_BUFFER_H */