| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
String Buffer
Wireshark Memory Manager

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

## Macros
#define | wmem_strbuf_create(allocator) wmem_strbuf_new(allocator, "")
| Create a new wmem string buffer initialized with an empty string.
#define | wmem_strbuf_append_unichar_repl(buf) wmem_strbuf_append_unichar(buf, UNICODE_REPLACEMENT_CHARACTER)
| Append the Unicode replacement character (U+FFFD) to a wmem string buffer.

## 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)
| 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)
| 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)
| 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)
| 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,...)
| Append formatted text to a string buffer.
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.

## Macro Definition Documentation

## ◆ wmem_strbuf_append_unichar_repl

#define wmem_strbuf_append_unichar_repl | ( |  | buf | ) | wmem_strbuf_append_unichar(buf, UNICODE_REPLACEMENT_CHARACTER)

Append the Unicode replacement character (U+FFFD) to a wmem string buffer.

This macro appends the standard Unicode replacement character to the given `wmem_strbuf_t`, typically used to indicate an unknown or invalid character.

Parameters

  buf | Pointer to the `wmem_strbuf_t` to append to.

## ◆ wmem_strbuf_create

#define wmem_strbuf_create | ( |  | allocator | ) | wmem_strbuf_new(allocator, "")

Create a new wmem string buffer initialized with an empty string.

This macro wraps `wmem_strbuf_new()` with an empty string as the initial value.

Parameters

  allocator | The `wmem_allocator_t` used to manage memory for the buffer.

Returns
  A pointer to the newly created `wmem_strbuf_t`.

## 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 `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.

Warning
  Because this can be used to copy embedded null characters, it can be used for arrays of char that are not strictly null-terminated strings, but conversely it does not check the length of str. The caller must ensure that append_len is not larger than the memory allocated for str.

## ◆ 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 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 `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.

Warning
  Because this can be used to copy embedded null characters, it can be used for arrays of char that are not strictly null-terminated strings, but conversely it does not check the length of str. The caller must ensure that len is not larger than the memory allocated for str.

## ◆ 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.