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

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