String Buffer

Classes
struct	_wmem_strbuf_t
	Internal structure representing a wmem-allocated string buffer. More...

Macros
#define	wmem_strbuf_create(allocator)    wmem_strbuf_new(allocator, "")
#define	wmem_strbuf_append_unichar_repl(buf)    wmem_strbuf_append_unichar(buf, UNICODE_REPLACEMENT_CHARACTER)

Typedefs
typedef struct _wmem_strbuf_t	wmem_strbuf_t

Functions
WS_DLL_PUBLIC wmem_strbuf_t *	wmem_strbuf_new_sized (wmem_allocator_t *allocator, size_t alloc_size) G_GNUC_MALLOC
	Create a new string buffer with a specified initial allocation size.
WS_DLL_PUBLIC wmem_strbuf_t *	wmem_strbuf_new (wmem_allocator_t *allocator, const char *str) G_GNUC_MALLOC
	Create a new string buffer initialized with a copy of the given string.
WS_DLL_PUBLIC wmem_strbuf_t *	wmem_strbuf_new_len (wmem_allocator_t *allocator, const char *str, size_t len) G_GNUC_MALLOC
	Create a new string buffer initialized with a substring of specified length.
WS_DLL_PUBLIC wmem_strbuf_t *	wmem_strbuf_dup (wmem_allocator_t *allocator, const wmem_strbuf_t *strbuf) G_GNUC_MALLOC
	Duplicate an existing string buffer using the specified memory allocator.
WS_DLL_PUBLIC void	wmem_strbuf_append (wmem_strbuf_t *strbuf, const char *str)
	Append a null-terminated string to the end of a string buffer.
WS_DLL_PUBLIC void	wmem_strbuf_append_len (wmem_strbuf_t *strbuf, const char *str, size_t append_len)
	Append a specified number of bytes from a string to a string buffer.
WS_DLL_PUBLIC void	wmem_strbuf_append_printf (wmem_strbuf_t *strbuf, const char *format,...) G_GNUC_PRINTF(2
	Append formatted text to a string buffer.
WS_DLL_PUBLIC void WS_DLL_PUBLIC void	wmem_strbuf_append_vprintf (wmem_strbuf_t *strbuf, const char *fmt, va_list ap)
	Append formatted text to a string buffer using a va_list.
WS_DLL_PUBLIC void	wmem_strbuf_append_c (wmem_strbuf_t *strbuf, const char c)
	Append a single character to a string buffer.
WS_DLL_PUBLIC void	wmem_strbuf_append_c_count (wmem_strbuf_t *strbuf, const char c, size_t count)
	Append a character to a string buffer multiple times.
WS_DLL_PUBLIC void	wmem_strbuf_append_unichar (wmem_strbuf_t *strbuf, const gunichar c)
	Append a Unicode character to a string buffer.
WS_DLL_PUBLIC void	wmem_strbuf_append_unichar_validated (wmem_strbuf_t *strbuf, const gunichar c)
	Append a validated Unicode character to a string buffer.
WS_DLL_PUBLIC void	wmem_strbuf_append_hex (wmem_strbuf_t *strbuf, uint8_t ch)
	Append a hexadecimal representation of a byte to a wmem string buffer.
WS_DLL_PUBLIC size_t	wmem_strbuf_append_hex_unichar (wmem_strbuf_t *strbuf, gunichar ch)
	Append a hexadecimal representation of a Unicode character to a wmem string buffer.
WS_DLL_PUBLIC void	wmem_strbuf_truncate (wmem_strbuf_t *strbuf, const size_t len)
	Truncate a wmem string buffer to a specified length.
WS_DLL_PUBLIC const char *	wmem_strbuf_get_str (const wmem_strbuf_t *strbuf)
	Retrieve the current string content from a wmem string buffer.
WS_DLL_PUBLIC size_t	wmem_strbuf_get_len (const wmem_strbuf_t *strbuf)
	Retrieve the current length of a wmem string buffer.
WS_DLL_PUBLIC int	wmem_strbuf_strcmp (const wmem_strbuf_t *sb1, const wmem_strbuf_t *sb2)
	Compare the contents of two wmem string buffers.
WS_DLL_PUBLIC const char *	wmem_strbuf_strstr (const wmem_strbuf_t *haystack, const wmem_strbuf_t *needle)
	Search for a substring within a wmem string buffer.
WS_DLL_PUBLIC char *	wmem_strbuf_finalize (wmem_strbuf_t *strbuf)
	Finalize a wmem string buffer and extract its raw string.
WS_DLL_PUBLIC void	wmem_strbuf_destroy (wmem_strbuf_t *strbuf)
	Destroy a wmem string buffer and release its associated memory.
WS_DLL_PUBLIC bool	wmem_strbuf_utf8_validate (wmem_strbuf_t *strbuf, const char **endptr)
	Validate the contents of a wmem string buffer as UTF-8.
WS_DLL_PUBLIC void	wmem_strbuf_utf8_make_valid (wmem_strbuf_t *strbuf)
	Ensure the contents of a wmem string buffer are valid UTF-8.

Detailed Description

A string object implementation on top of wmem.

Function Documentation

wmem_strbuf_append()

WS_DLL_PUBLIC void wmem_strbuf_append	(	wmem_strbuf_t *	strbuf,
		const char *	str
	)

Append a null-terminated string to the end of a string buffer.

Adds the contents of str to the end of the given wmem_strbuf_t buffer, resizing the buffer if necessary to accommodate the new data.

Parameters

strbuf	Pointer to the string buffer to append to.
str	Null-terminated string to append.

wmem_strbuf_append_c()

WS_DLL_PUBLIC void wmem_strbuf_append_c	(	wmem_strbuf_t *	strbuf,
		const char	c
	)

Append a single character to a string buffer.

Adds the character c to the end of the given wmem_strbuf_t buffer, resizing the buffer if necessary. The buffer remains null-terminated.

Parameters

strbuf	Pointer to the string buffer to append to.
c	Character to append.

wmem_strbuf_append_c_count()

WS_DLL_PUBLIC void wmem_strbuf_append_c_count	(	wmem_strbuf_t *	strbuf,
		const char	c,
		size_t	count
	)

Append a character to a string buffer multiple times.

Appends the character c to the end of the given wmem_strbuf_t buffer count times. The buffer is resized if necessary and remains null-terminated.

Parameters

strbuf	Pointer to the string buffer to append to.
c	Character to append.
count	Number of times to append the character.

wmem_strbuf_append_hex()

WS_DLL_PUBLIC void wmem_strbuf_append_hex	(	wmem_strbuf_t *	strbuf,
		uint8_t	ch
	)

Append a hexadecimal representation of a byte to a wmem string buffer.

Converts the given 8-bit unsigned integer into a two-character hexadecimal string and appends it to the specified wmem_strbuf_t. For example, passing the value 123 will append the string "7B" (in uppercase) to the buffer.

Parameters

strbuf	Pointer to the wmem_strbuf_t to append to.
ch	The 8-bit unsigned integer to convert and append as hexadecimal.

wmem_strbuf_append_hex_unichar()

WS_DLL_PUBLIC size_t wmem_strbuf_append_hex_unichar	(	wmem_strbuf_t *	strbuf,
		gunichar	ch
	)

Append a hexadecimal representation of a Unicode character to a wmem string buffer.

Converts the given Unicode character (gunichar) into its hexadecimal representation and appends it to the specified wmem_strbuf_t.

Parameters

strbuf	Pointer to the string buffer to append to.
ch	Unicode character to convert and append.

Returns

Number of characters appended to the buffer (4, 6, or 10).

wmem_strbuf_append_len()

WS_DLL_PUBLIC void wmem_strbuf_append_len	(	wmem_strbuf_t *	strbuf,
		const char *	str,
		size_t	append_len
	)

Append a specified number of bytes from a string to a string buffer.

Appends up to append_len bytes from the string str to the end of the given wmem_strbuf_t buffer. Embedded null characters in str will be copied, and the resulting buffer will be null-terminated.

Parameters

strbuf	Pointer to the string buffer to append to.
str	Source string to copy bytes from.
append_len	Number of bytes to append from the source string.

wmem_strbuf_append_printf()

WS_DLL_PUBLIC void wmem_strbuf_append_printf	(	wmem_strbuf_t *	strbuf,
		const char *	format,
			...
	)

Append formatted text to a string buffer.

Formats a string using printf-style formatting and appends it to the end of the given wmem_strbuf_t buffer. The buffer is resized if necessary to accommodate the new content.

Parameters

strbuf	Pointer to the string buffer to append to.
format	Format string (as used in printf).
...	Additional arguments to format into the string.

wmem_strbuf_append_unichar()

WS_DLL_PUBLIC void wmem_strbuf_append_unichar	(	wmem_strbuf_t *	strbuf,
		const gunichar	c
	)

Append a Unicode character to a string buffer.

Converts the given Unicode character c to its UTF-8 representation and appends it to the end of the specified wmem_strbuf_t buffer. The buffer is resized if necessary and remains null-terminated.

Parameters

strbuf	Pointer to the string buffer to append to.
c	Unicode character (gunichar) to append.

wmem_strbuf_append_unichar_validated()

WS_DLL_PUBLIC void wmem_strbuf_append_unichar_validated	(	wmem_strbuf_t *	strbuf,
		const gunichar	c
	)

Append a validated Unicode character to a string buffer.

Converts the given Unicode character c to its UTF-8 representation and appends it to the end of the specified wmem_strbuf_t buffer. If c is not a valid Unicode codepoint, a standard replacement character (U+FFFD) is appended instead. The buffer is resized if necessary and remains null-terminated.

Parameters

strbuf	Pointer to the string buffer to append to.
c	Unicode character (gunichar) to validate and append.

wmem_strbuf_append_vprintf()

WS_DLL_PUBLIC void WS_DLL_PUBLIC void wmem_strbuf_append_vprintf	(	wmem_strbuf_t *	strbuf,
		const char *	fmt,
		va_list	ap
	)

Append formatted text to a string buffer using a va_list.

Formats a string using a printf-style format string and a va_list of arguments, then appends the result to the end of the given wmem_strbuf_t buffer. The buffer is resized if necessary to accommodate the new content.

Parameters

strbuf	Pointer to the string buffer to append to.
fmt	Format string (as used in printf).
ap	va_list containing the arguments to format into the string.

wmem_strbuf_destroy()

WS_DLL_PUBLIC void wmem_strbuf_destroy

(

wmem_strbuf_t *

strbuf

)

Destroy a wmem string buffer and release its associated memory.

Frees all memory allocated for the given wmem_strbuf_t, including its internal string storage. After this call, the buffer is no longer valid and must not be used.

Note

This function should be used when the buffer is no longer needed and its contents do not need to be retained.

If you need to keep the final string, use wmem_strbuf_finalize() instead.

Parameters

strbuf

Pointer to the string buffer to destroy.

wmem_strbuf_dup()

WS_DLL_PUBLIC wmem_strbuf_t * wmem_strbuf_dup	(	wmem_allocator_t *	allocator,
		const wmem_strbuf_t *	strbuf
	)

Duplicate an existing string buffer using the specified memory allocator.

Creates a new wmem_strbuf_t instance by copying the contents of the given strbuf, allocating memory for the duplicate using the provided allocator.

Parameters

allocator	Pointer to the memory allocator to use.
strbuf	Pointer to the source string buffer to duplicate.

Returns

Pointer to the newly created duplicate string buffer, or NULL on failure.

wmem_strbuf_finalize()

WS_DLL_PUBLIC char * wmem_strbuf_finalize

(

wmem_strbuf_t *

strbuf

)

Finalize a wmem string buffer and extract its raw string.

Truncates the allocated memory of the given wmem_strbuf_t to the minimal required size, frees the internal buffer structure, and returns a non-const pointer to the resulting null-terminated C string. After this call, the original wmem_strbuf_t is no longer valid and must not be used.

This function is typically used when the caller needs to retain ownership of the final string but no longer requires the dynamic buffer interface.

Parameters

strbuf

Pointer to the string buffer to finalize.

Returns

Pointer to the raw, null-terminated C string. The caller assumes ownership.

wmem_strbuf_get_len()

WS_DLL_PUBLIC size_t wmem_strbuf_get_len

(

const wmem_strbuf_t *

strbuf

)

Retrieve the current length of a wmem string buffer.

Returns the number of characters currently stored in the given wmem_strbuf_t, excluding the null terminator. This reflects the logical length of the string content in the buffer.

Parameters

strbuf

Pointer to the string buffer to query.

Returns

The length of the string content in the buffer.

wmem_strbuf_get_str()

WS_DLL_PUBLIC const char * wmem_strbuf_get_str

(

const wmem_strbuf_t *

strbuf

)

Retrieve the current string content from a wmem string buffer.

Returns a pointer to the internal null-terminated string stored in the given wmem_strbuf_t. This string reflects all content appended to the buffer so far.

Parameters

strbuf

Pointer to the string buffer to query.

Returns

Pointer to the internal null-terminated string.

wmem_strbuf_new()

WS_DLL_PUBLIC wmem_strbuf_t * wmem_strbuf_new	(	wmem_allocator_t *	allocator,
		const char *	str
	)

Create a new string buffer initialized with a copy of the given string.

Allocates and initializes a new wmem_strbuf_t structure using the specified memory allocator, and copies the contents of the null-terminated string str into the buffer.

Parameters

allocator	Pointer to the memory allocator to use.
str	Null-terminated string to initialize the buffer with.

Returns

Pointer to the newly created string buffer, or NULL on failure.

wmem_strbuf_new_len()

WS_DLL_PUBLIC wmem_strbuf_t * wmem_strbuf_new_len	(	wmem_allocator_t *	allocator,
		const char *	str,
		size_t	len
	)

Create a new string buffer initialized with a substring of specified length.

Allocates and initializes a new wmem_strbuf_t structure using the specified memory allocator, and copies up to len bytes from the string str into the buffer. The resulting buffer is null-terminated.

Parameters

allocator	Pointer to the memory allocator to use.
str	Source string to copy into the buffer.
len	Number of bytes to copy from the source string.

Returns

Pointer to the newly created string buffer, or NULL on failure.

wmem_strbuf_new_sized()

WS_DLL_PUBLIC wmem_strbuf_t * wmem_strbuf_new_sized	(	wmem_allocator_t *	allocator,
		size_t	alloc_size
	)

Create a new string buffer with a specified initial allocation size.

Allocates and initializes a new wmem_strbuf_t structure using the given memory allocator, with space preallocated for alloc_size bytes.

Parameters

allocator	Pointer to the memory allocator to use.
alloc_size	Initial number of bytes to allocate for the buffer.

Returns

Pointer to the newly created string buffer, or NULL on failure.

wmem_strbuf_strcmp()

WS_DLL_PUBLIC int wmem_strbuf_strcmp	(	const wmem_strbuf_t *	sb1,
		const wmem_strbuf_t *	sb2
	)

Compare the contents of two wmem string buffers.

Performs a string comparison between the contents of sb1 and sb2, similar to strcmp(). Returns an integer less than, equal to, or greater than zero if the string in sb1 is found, respectively, to be less than, to match, or be greater than the string in sb2.

Note

The comparison is case-sensitive and uses standard C string semantics.

Parameters

sb1	Pointer to the first wmem_strbuf_t to compare.
sb2	Pointer to the second wmem_strbuf_t to compare.

Returns

An integer indicating the lexical relationship between the two strings.

wmem_strbuf_strstr()

WS_DLL_PUBLIC const char * wmem_strbuf_strstr	(	const wmem_strbuf_t *	haystack,
		const wmem_strbuf_t *	needle
	)

Search for a substring within a wmem string buffer.

Searches for the contents of needle within the contents of haystack, both represented as wmem_strbuf_t structures. If the substring is found, a pointer to its first occurrence within the haystack string is returned. If not found, the function returns NULL.

Parameters

haystack	Pointer to the string buffer to search within.
needle	Pointer to the string buffer containing the substring to search for.

Returns

Pointer to the first occurrence of needle in haystack, or NULL if not found.

wmem_strbuf_truncate()

WS_DLL_PUBLIC void wmem_strbuf_truncate	(	wmem_strbuf_t *	strbuf,
		const size_t	len
	)

Truncate a wmem string buffer to a specified length.

Reduces the length of the given wmem_strbuf_t to len characters. If the buffer currently contains more than len characters, the excess characters are removed. If the buffer contains fewer than len characters, no changes are made.

Note

This operation does not reallocate the buffer; it simply adjusts the logical length.

Parameters

strbuf	Pointer to the string buffer to truncate.
len	The target length to truncate the buffer to.

wmem_strbuf_utf8_make_valid()

WS_DLL_PUBLIC void wmem_strbuf_utf8_make_valid

(

wmem_strbuf_t *

strbuf

)

Ensure the contents of a wmem string buffer are valid UTF-8.

Replaces any invalid UTF-8 sequences in the given wmem_strbuf_t with the Unicode replacement character (U+FFFD). This guarantees that the resulting buffer contains only valid UTF-8.

Note

This function modifies the buffer in-place.

Parameters

strbuf

Pointer to the string buffer to sanitize.

wmem_strbuf_utf8_validate()

WS_DLL_PUBLIC bool wmem_strbuf_utf8_validate	(	wmem_strbuf_t *	strbuf,
		const char **	endptr
	)

Validate the contents of a wmem string buffer as UTF-8.

Checks whether the contents of the given wmem_strbuf_t form a valid UTF-8 sequence. Unlike g_utf8_validate(), this function accepts embedded NUL (\0) bytes as valid. If endptr is non-NULL, it will be set to point to the first invalid byte in the buffer, or to the end of the buffer if the entire content is valid.

Parameters

strbuf	Pointer to the string buffer to validate.
endptr	Optional pointer to receive the end of the valid range.

Returns

true if the buffer contains valid UTF-8, false otherwise.