97 lines
2.5 KiB
C
97 lines
2.5 KiB
C
|
#ifndef _BOOTSTRAP_STRING_BUF_H
|
||
|
|
#define _BOOTSTRAP_STRING_BUF_H
|
||
|
|
|
||
|
|
#include <stdlib.h>
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief A dynamic character array.
|
||
|
|
*
|
||
|
|
* A `char*` wrapper. Appending `char`s or NUL-terminated strings allocates
|
||
|
|
* additional space as needed.
|
||
|
|
*/
|
||
|
|
struct StringBuf;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Create a new `StringBuf` instance.
|
||
|
|
*
|
||
|
|
* @param capacity
|
||
|
|
* The initial size of the internal array (including the trailing `NUL`
|
||
|
|
* character). To avoid too many reallocations, aim to make this value large
|
||
|
|
* enough to accommodate the size the string is expected to eventually take.
|
||
|
|
* @return
|
||
|
|
* A new `StringBuf` instance. The caller takes ownership of this value.
|
||
|
|
*
|
||
|
|
* @see string_buf_free
|
||
|
|
*/
|
||
|
|
struct StringBuf *string_buf_new(size_t capacity);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return the number of characters contained in the internal buffer.
|
||
|
|
*
|
||
|
|
* @param sb
|
||
|
|
* A valid pointer to a `StringBuf` instance.
|
||
|
|
* @return
|
||
|
|
* The number of characters contained in the internal buffer.
|
||
|
|
*/
|
||
|
|
size_t string_buf_size(struct StringBuf *sb);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Return the internal `NUL`-terminated string buffer.
|
||
|
|
*
|
||
|
|
* @param sb
|
||
|
|
* A valid pointer to a `StringBuf` instance.
|
||
|
|
* @return
|
||
|
|
* The internally managed string.
|
||
|
|
*/
|
||
|
|
const char *string_buf_value(struct StringBuf *sb);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Append a character to the end of a `StringBuf`.
|
||
|
|
*
|
||
|
|
* If appending would cause the internal buffer to overflow, reallocates the
|
||
|
|
* internal array to accommodate.
|
||
|
|
*
|
||
|
|
* @param sb
|
||
|
|
* A valid pointer to a `StringBuf` instance.
|
||
|
|
* @param c
|
||
|
|
* The `char` to append to the end of `sb`.
|
||
|
|
*/
|
||
|
|
void string_buf_cappend(struct StringBuf *sb, char c);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Append a `NUL`-terminated string to the end of a `StringBuf`.
|
||
|
|
*
|
||
|
|
* If appending would cause the internal buffer to overflow, `realloc`s are
|
||
|
|
* performed internally to accommodate.
|
||
|
|
*
|
||
|
|
* @param sb
|
||
|
|
* A valid pointer to a `StringBuf` instance.
|
||
|
|
* @param s
|
||
|
|
* The `char*` to append to the end of `sb`.
|
||
|
|
*/
|
||
|
|
void string_buf_sappend(struct StringBuf *sb, const char s[static 1]);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Convert a `StringBuf` instance into a `char*`.
|
||
|
|
*
|
||
|
|
* @param sb
|
||
|
|
* A valid pointer to a `StringBuf` instance.
|
||
|
|
* @return
|
||
|
|
* A null pointer if `sb` is null. Otherwise a `NUL`-terminated string
|
||
|
|
* corresponding to the value of `sb`. The caller takes ownership of this
|
||
|
|
* value.
|
||
|
|
*/
|
||
|
|
const char *string_buf_convert(struct StringBuf *sb);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Deallocate a previously allocated `StringBuf` instance.
|
||
|
|
*
|
||
|
|
* @param sb
|
||
|
|
* A valid pointer to a `StringBuf` instance.
|
||
|
|
*
|
||
|
|
* @see string_buf_new
|
||
|
|
*/
|
||
|
|
void string_buf_free(struct StringBuf *sb);
|
||
|
|
|
||
|
|
#endif /* _BOOTSTRAP_STRING_BUF_H */
|