stringbuf.h

   1 #ifndef STRINGBUF_H
   2 #define STRINGBUF_H
   3
   4 /* (c) 2017 Workware Systems Pty Ltd  -- All Rights Reserved */
   5
   6 #ifdef __cplusplus
   7 extern "C" {
   8 #endif
   9
  10 /** @file
  11  * A stringbuf is a resizing, null terminated string buffer.
  12  *
  13  * The buffer is reallocated as necessary.
  14  *
  15  * In general it is *not* OK to call these functions with a NULL pointer
  16  * unless stated otherwise.
  17  *
  18  * If USE_UTF8 is defined, supports utf8.
  19  */
  20
  21 /**
  22  * The stringbuf structure should not be accessed directly.
  23  * Use the functions below.
  24  */
  25 typedef struct {
  26         int remaining;  /**< Allocated, but unused space */
  27         int last;               /**< Index of the null terminator (and thus the length of the string) */
  28 #ifdef USE_UTF8
  29         int chars;              /**< Count of characters */
  30 #endif
  31         char *data;             /**< Allocated memory containing the string or NULL for empty */
  32 } stringbuf;
  33
  34 /**
  35  * Allocates and returns a new stringbuf with no elements.
  36  */
  37 stringbuf *sb_alloc(void);
  38
  39 /**
  40  * Frees a stringbuf.
  41  * It is OK to call this with NULL.
  42  */
  43 void sb_free(stringbuf *sb);
  44
  45 /**
  46  * Returns an allocated copy of the stringbuf
  47  */
  48 stringbuf *sb_copy(stringbuf *sb);
  49
  50 /**
  51  * Returns the length of the buffer.
  52  *
  53  * Returns 0 for both a NULL buffer and an empty buffer.
  54  */
  55 static inline int sb_len(stringbuf *sb) {
  56         return sb->last;
  57 }
  58
  59 /**
  60  * Returns the utf8 character length of the buffer.
  61  *
  62  * Returns 0 for both a NULL buffer and an empty buffer.
  63  */
  64 static inline int sb_chars(stringbuf *sb) {
  65 #ifdef USE_UTF8
  66         return sb->chars;
  67 #else
  68         return sb->last;
  69 #endif
  70 }
  71
  72 /**
  73  * Appends a null terminated string to the stringbuf
  74  */
  75 void sb_append(stringbuf *sb, const char *str);
  76
  77 /**
  78  * Like sb_append() except does not require a null terminated string.
  79  * The length of 'str' is given as 'len'
  80  *
  81  * Note that in utf8 mode, characters will *not* be counted correctly
  82  * if a partial utf8 sequence is added with sb_append_len()
  83  */
  84 void sb_append_len(stringbuf *sb, const char *str, int len);
  85
  86 /**
  87  * Returns a pointer to the null terminated string in the buffer.
  88  *
  89  * Note this pointer only remains valid until the next modification to the
  90  * string buffer.
  91  *
  92  * The returned pointer can be used to update the buffer in-place
  93  * as long as care is taken to not overwrite the end of the buffer.
  94  */
  95 static inline char *sb_str(const stringbuf *sb)
  96 {
  97         return sb->data;
  98 }
  99
 100 /**
 101  * Inserts the given string *before* (zero-based) 'index' in the stringbuf.
 102  * If index is past the end of the buffer, the string is appended,
 103  * just like sb_append()
 104  */
 105 void sb_insert(stringbuf *sb, int index, const char *str);
 106
 107 /**
 108  * Delete 'len' bytes in the string at the given index.
 109  *
 110  * Any bytes past the end of the buffer are ignored.
 111  * The buffer remains null terminated.
 112  *
 113  * If len is -1, deletes to the end of the buffer.
 114  */
 115 void sb_delete(stringbuf *sb, int index, int len);
 116
 117 /**
 118  * Clear to an empty buffer.
 119  */
 120 void sb_clear(stringbuf *sb);
 121
 122 /**
 123  * Return an allocated copy of buffer and frees 'sb'.
 124  *
 125  * If 'sb' is empty, returns an allocated copy of "".
 126  */
 127 char *sb_to_string(stringbuf *sb);
 128
 129 #ifdef __cplusplus
 130 }
 131 #endif
 132
 133 #endif