buffer.h

   1 #ifndef BUFFER_H
   2 #define BUFFER_H
   3
   4 #include <stddef.h>
   5 #include <stdbool.h>
   6 #include "text.h"
   7
   8 /**
   9  * @file
  10  * A dynamically growing buffer storing arbitrary data.
  11  * @rst
  12  * .. note:: Used for Register, *not* Text content.
  13  * @endrst
  14  */
  15
  16 /** A dynamically growing buffer storing arbitrary data. */
  17 typedef struct {
  18         char *data;    /**< Data pointer, ``NULL`` if empty. */
  19         size_t len;    /**< Current length of data. */
  20         size_t size;   /**< Maximal capacity of the buffer. */
  21 } Buffer;
  22
  23 /** Initalize a Buffer object. */
  24 void buffer_init(Buffer*);
  25 /** Release all resources, reinitialize buffer. */
  26 void buffer_release(Buffer*);
  27 /** Set buffer length to zero, keep allocated memory. */
  28 void buffer_clear(Buffer*);
  29 /** Reserve space to store at least ``size`` bytes.*/
  30 bool buffer_reserve(Buffer*, size_t size);
  31 /** Reserve space for at least ``len`` *more* bytes. */
  32 bool buffer_grow(Buffer*, size_t len);
  33 /** If buffer is non-empty, make sure it is ``NUL`` terminated. */
  34 bool buffer_terminate(Buffer*);
  35 /** Set buffer content, growing the buffer as needed. */
  36 bool buffer_put(Buffer*, const void *data, size_t len);
  37 /** Set buffer content to ``NUL`` terminated data. */
  38 bool buffer_put0(Buffer*, const char *data);
  39 /** Remove ``len`` bytes starting at ``pos``. */
  40 bool buffer_remove(Buffer*, size_t pos, size_t len);
  41 /** Insert ``len`` bytes of ``data`` at ``pos``. */
  42 bool buffer_insert(Buffer*, size_t pos, const void *data, size_t len);
  43 /** Insert NUL-terminated data at pos. */
  44 bool buffer_insert0(Buffer*, size_t pos, const char *data);
  45 /** Append further content to the end. */
  46 bool buffer_append(Buffer*, const void *data, size_t len);
  47 /** Append NUl-terminated data. */
  48 bool buffer_append0(Buffer*, const char *data);
  49 /** Insert ``len`` bytes of ``data`` at the begin. */
  50 bool buffer_prepend(Buffer*, const void *data, size_t len);
  51 /** Insert NUL-terminated data at the begin. */
  52 bool buffer_prepend0(Buffer*, const char *data);
  53 /** Set formatted buffer content, ensures NUL termination on success. */
  54 bool buffer_printf(Buffer*, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
  55 /** Append formatted buffer content, ensures NUL termination on success. */
  56 bool buffer_appendf(Buffer*, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
  57 /** Return length of a buffer without trailing NUL byte. */
  58 size_t buffer_length0(Buffer*);
  59 /** Return length of a buffer including possible NUL byte. */
  60 size_t buffer_length(Buffer*);
  61 /** Return current maximal capacity in bytes of this buffer. */
  62 size_t buffer_capacity(Buffer*);
  63 /**
  64  * Get pointer to buffer data.
  65  * Guaranteed to return a NUL terminated string even if buffer is empty.
  66  */
  67 const char *buffer_content0(Buffer*);
  68 /**
  69  * Get pointer to buffer data.
  70  * @rst
  71  * .. warning:: Might be NULL, if empty. Might not be NUL terminated.
  72  * @endrst
  73  */
  74 const char *buffer_content(Buffer*);
  75 /**
  76  * Borrow underlying buffer data.
  77  * @rst
  78  * .. warning:: The caller is responsible to `free(3)` it.
  79  * @endrst
  80  */
  81 char *buffer_move(Buffer*);
  82
  83 #endif