chiark - git - mdw - mLib/blob - dstr.h

   1 /* -*-c-*-
   2  *
   3  * $Id: dstr.h,v 1.3 1999/05/05 18:50:31 mdw Exp $
   4  *
   5  * Handle dynamically growing strings
   6  *
   7  * (c) 1998 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of the mLib utilities library.
  13  *
  14  * mLib is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU Library General Public License as
  16  * published by the Free Software Foundation; either version 2 of the
  17  * License, or (at your option) any later version.
  18  *
  19  * mLib is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with mLib; if not, write to the Free Software
  26  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 /*----- Revision history --------------------------------------------------*
  30  *
  31  * $Log: dstr.h,v $
  32  * Revision 1.3  1999/05/05 18:50:31  mdw
  33  * Change licensing conditions to LGPL.
  34  *
  35  * Revision 1.2  1998/12/15 23:53:23  mdw
  36  * New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
  37  * formatting in a safe way.
  38  *
  39  * Revision 1.1.1.1  1998/06/17 23:44:42  mdw
  40  * Initial version of mLib
  41  *
  42  */
  43
  44 #ifndef DSTR_H
  45 #define DSTR_H
  46
  47 #ifdef __cplusplus
  48   extern "C" {
  49 #endif
  50
  51 /*----- Rationale ---------------------------------------------------------*
  52  *
  53  * This file declares what is hopefully a fairly useful collection of
  54  * primitive string handling functions.  The idea is that the strings
  55  * allocate memory for themselves as required.  The @dstr@ routines don't
  56  * assume any sort of terminator character, so arbitrary binary data can
  57  * be stored in a dynamic string.  With luck, this should put a stop to
  58  * any buffer overflow problems.
  59  */
  60
  61 /*----- Header files ------------------------------------------------------*/
  62
  63 #include <stdarg.h>
  64 #include <stdio.h>
  65
  66 /*----- Data structures ---------------------------------------------------*/
  67
  68 typedef struct dstr {
  69   char *buf;                            /* Pointer to string buffer */
  70   size_t sz;                            /* Size of the buffer */
  71   size_t len;                           /* Length of the string */
  72 } dstr;
  73
  74 /*----- Functions provided ------------------------------------------------*/
  75
  76 /* --- @dstr_create@ --- *
  77  *
  78  * Arguments:   @dstr *d@ = pointer to a dynamic string block
  79  *
  80  * Returns:     ---
  81  *
  82  * Use:         Initialises a dynamic string.
  83  */
  84
  85 extern void dstr_create(dstr */*d*/);
  86
  87 /* --- @dstr_destroy@ --- *
  88  *
  89  * Arguments:   @dstr *d@ = pointer to a dynamic string block
  90  *
  91  * Returns:     ---
  92  *
  93  * Use:         Reclaims the space used by a dynamic string.
  94  */
  95
  96 extern void dstr_destroy(dstr */*d*/);
  97
  98 /* --- @dstr_reset@ --- *
  99  *
 100  * Arguments:   @dstr *d@ = pointer to a dynaimc string block
 101  *
 102  * Returns:     ---
 103  *
 104  * Use:         Resets a string so that new data gets put at the beginning.
 105  */
 106
 107 extern void dstr_reset(dstr */*d*/);
 108
 109 /* --- @dstr_ensure@ --- *
 110  *
 111  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 112  *              @size_t sz@ = amount of free space to ensure
 113  *
 114  * Returns:     ---
 115  *
 116  * Use:         Ensures that at least @sz@ bytes are available in the
 117  *              given string.
 118  */
 119
 120 extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);
 121
 122 #define DENSURE(d, rq) do {                                             \
 123   if ((d)->len + (rq) > (d)->sz) dstr_ensure((d), (rq));                \
 124 } while (0)
 125
 126 /* --- @dstr_putc@ --- *
 127  *
 128  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 129  *              @char ch@ = character to append
 130  *
 131  * Returns:     ---
 132  *
 133  * Use:         Appends a character to a string.
 134  */
 135
 136 extern void dstr_putc(dstr */*d*/, char /*ch*/);
 137
 138 #define DPUTC(d, ch) do {                                               \
 139   DENSURE((d), 1);                                                      \
 140   (d)->buf[(d)->len++] = (ch);                                          \
 141 } while (0)
 142
 143 /* --- @dstr_putz@ --- *
 144  *
 145  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 146  *
 147  * Returns:     ---
 148  *
 149  * Use:         Appends a null byte to a string.  The null byte does not
 150  *              contribute to the string's length, and will be overwritten
 151  *              by subsequent `put' operations.
 152  */
 153
 154 extern void dstr_putz(dstr */*d*/);
 155
 156 #define DPUTZ(d) do {                                                   \
 157   DENSURE((d), 1);                                                      \
 158   (d)->buf[(d)->len] = 0;                                               \
 159 } while (0)
 160
 161 /* --- @dstr_puts@ --- *
 162  *
 163  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 164  *              @const char *s@ = pointer to string to append
 165  *
 166  * Returns:     ---
 167  *
 168  * Use:         Appends a character string to a string.  A trailing null
 169  *              byte is added, as for @dstr_putz@.
 170  */
 171
 172 extern void dstr_puts(dstr */*d*/, const char */*s*/);
 173
 174 #define DPUTS(d, s) do {                                                \
 175   size_t sz = strlen(s);                                                \
 176   DENSURE((d), sz + 1);                                                 \
 177   memcpy((d)->buf + (d)->len, (s), sz + 1);                             \
 178   (d)->len += sz;                                                       \
 179 } while (0)
 180
 181 /* --- @dstr_vputf@ --- *
 182  *
 183  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 184  *              @const char *p@ = pointer to @printf@-style format string
 185  *              @va_list ap@ = argument handle
 186  *
 187  * Returns:     ---
 188  *
 189  * Use:         As for @dstr_putf@, but may be used as a back-end to user-
 190  *              supplied functions with @printf@-style interfaces.
 191  */
 192
 193 extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list /*ap*/);
 194
 195 /* --- @dstr_putf@ --- *
 196  *
 197  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 198  *              @const char *p@ = pointer to @printf@-style format string
 199  *              @...@ = argument handle
 200  *
 201  * Returns:     ---
 202  *
 203  * Use:         Writes a piece of text to a dynamic string, doing @printf@-
 204  *              style substitutions as it goes.  Intended to be robust if
 205  *              faced with malicious arguments, but not if the format string
 206  *              itself is malicious.
 207  */
 208
 209 extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
 210
 211 /* --- @dstr_putd@ --- *
 212  *
 213  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 214  *              @const dstr *s@ = pointer to a dynamic string to append
 215  *
 216  * Returns:     ---
 217  *
 218  * Use:         Appends a dynamic string to a string.  A trailing null
 219  *              byte is added, as for @dstr_putz@.
 220  */
 221
 222 extern void dstr_putd(dstr */*d*/, const dstr */*s*/);
 223
 224 #define DPUTD(d, s) do {                                                \
 225   DENSURE((d), (s)->len + 1);                                           \
 226   memcpy((d)->buf + (d)->len, (s)->buf, (s)->len);                      \
 227   (d)->len += (s)->len;                                                 \
 228   (d)->buf[(d)->len] = 0;                                               \
 229 } while (0)
 230
 231 /* --- @dstr_putm@ --- *
 232  *
 233  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 234  *              @const void *p@ = pointer to a block to append
 235  *              @size_t sz@ = size of the block
 236  *
 237  * Returns:     Appends an arbitrary data block to a string.  No trailing
 238  *              null is appended.
 239  */
 240
 241 extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);
 242
 243 #define DPUTM(d, p, sz) do {                                            \
 244   DENSURE((d), (sz));                                                   \
 245   memcpy((d)->buf + (d)->len, (p), (sz));                               \
 246   (d)->len += (sz);                                                     \
 247 } while (0)
 248
 249 /* --- @dstr_tidy@ --- *
 250  *
 251  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 252  *
 253  * Returns:     ---
 254  *
 255  * Use:         Reduces the amount of memory used by a string.  A trailing
 256  *              null byte is added, as for @dstr_putz@.
 257  */
 258
 259 extern void dstr_tidy(dstr */*d*/);
 260
 261 /* --- @dstr_putline@ --- *
 262  *
 263  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 264  *              @FILE *fp@ = a stream to read from
 265  *
 266  * Returns:     The number of characters read into the buffer, or @EOF@ if
 267  *              end-of-file was reached before any characters were read.
 268  *
 269  * Use:         Appends the next line from the given input stream to the
 270  *              string.  A trailing newline is not added; a trailing null
 271  *              byte is appended, as for @dstr_putz@.
 272  */
 273
 274 extern int dstr_putline(dstr */*d*/, FILE */*fp*/);
 275
 276 /* --- @dstr_write@ --- *
 277  *
 278  * Arguments:   @dstr *d@ = pointer to a dynamic string block
 279  *              @FILE *fp@ = a stream to write on
 280  *
 281  * Returns:     The number of bytes written (as for @fwrite@).
 282  *
 283  * Use:         Writes a dynamic string to a file.
 284  */
 285
 286 extern size_t dstr_write(dstr */*d*/, FILE */*fp*/);
 287
 288 /*----- That's all, folks -------------------------------------------------*/
 289
 290 #ifdef __cplusplus
 291   }
 292 #endif
 293
 294 #endif