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