stringbuf.h

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