wsutil/wmem/wmem_strbuf.h

   1 /** @file
   2  * Definitions for the Wireshark Memory Manager String Buffer
   3  * Copyright 2012, Evan Huus <eapache@gmail.com>
   4  *
   5  * Wireshark - Network traffic analyzer
   6  * By Gerald Combs <gerald@wireshark.org>
   7  * Copyright 1998 Gerald Combs
   8  *
   9  * SPDX-License-Identifier: GPL-2.0-or-later
  10  */
  11
  12 #ifndef __WMEM_STRBUF_H__
  13 #define __WMEM_STRBUF_H__
  14
  15 #include <ws_codepoints.h>
  16
  17 #include "wmem_core.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif /* __cplusplus */
  22
  23 /** @addtogroup wmem
  24  *  @{
  25  *    @defgroup wmem-strbuf String Buffer
  26  *
  27  *    A string object implementation on top of wmem.
  28  *
  29  *    @{
  30  */
  31
  32 /* Holds a wmem-allocated string-buffer.
  33  *  len is the length of the string (not counting the null-terminator) and
  34  *      should be the same as strlen(str) unless the string contains embedded
  35  *      nulls.
  36  *  alloc_size is the size of the raw buffer pointed to by str, regardless of
  37  *      what string is actually being stored (i.e. the buffer contents)
  38  *  max_size is the maximum permitted alloc_size (NOT the maximum permitted len,
  39  *      which must be one shorter than alloc_size to permit null-termination).
  40  *      When max_size is 0 (the default), no maximum is enforced.
  41  */
  42 struct _wmem_strbuf_t {
  43     /* read-only fields */
  44     wmem_allocator_t *allocator;
  45     char *str;
  46     size_t len;
  47
  48     /* private fields */
  49     size_t alloc_size;
  50 };
  51
  52 typedef struct _wmem_strbuf_t wmem_strbuf_t;
  53
  54 WS_DLL_PUBLIC
  55 wmem_strbuf_t *
  56 wmem_strbuf_new_sized(wmem_allocator_t *allocator, size_t alloc_size)
  57 G_GNUC_MALLOC;
  58
  59 WS_DLL_PUBLIC
  60 wmem_strbuf_t *
  61 wmem_strbuf_new(wmem_allocator_t *allocator, const char *str)
  62 G_GNUC_MALLOC;
  63
  64 #define wmem_strbuf_create(allocator) \
  65     wmem_strbuf_new(allocator, "")
  66
  67 WS_DLL_PUBLIC
  68 wmem_strbuf_t *
  69 wmem_strbuf_new_len(wmem_allocator_t *allocator, const char *str, size_t len)
  70 G_GNUC_MALLOC;
  71
  72 WS_DLL_PUBLIC
  73 wmem_strbuf_t *
  74 wmem_strbuf_dup(wmem_allocator_t *allocator, const wmem_strbuf_t *strbuf)
  75 G_GNUC_MALLOC;
  76
  77 WS_DLL_PUBLIC
  78 void
  79 wmem_strbuf_append(wmem_strbuf_t *strbuf, const char *str);
  80
  81 /* Appends up to append_len bytes (as allowed by strbuf->max_size) from
  82  * str. Ensures that strbuf is null terminated afterwards but will copy
  83  * embedded nulls. */
  84 WS_DLL_PUBLIC
  85 void
  86 wmem_strbuf_append_len(wmem_strbuf_t *strbuf, const char *str, size_t append_len);
  87
  88 WS_DLL_PUBLIC
  89 void
  90 wmem_strbuf_append_printf(wmem_strbuf_t *strbuf, const char *format, ...)
  91 G_GNUC_PRINTF(2, 3);
  92
  93 WS_DLL_PUBLIC
  94 void
  95 wmem_strbuf_append_vprintf(wmem_strbuf_t *strbuf, const char *fmt, va_list ap);
  96
  97 WS_DLL_PUBLIC
  98 void
  99 wmem_strbuf_append_c(wmem_strbuf_t *strbuf, const char c);
 100
 101 WS_DLL_PUBLIC
 102 void
 103 wmem_strbuf_append_c_count(wmem_strbuf_t *strbuf, const char c, size_t count);
 104
 105 WS_DLL_PUBLIC
 106 void
 107 wmem_strbuf_append_unichar(wmem_strbuf_t *strbuf, const gunichar c);
 108
 109 #define wmem_strbuf_append_unichar_repl(buf) \
 110             wmem_strbuf_append_unichar(buf, UNICODE_REPLACEMENT_CHARACTER)
 111
 112 /* As wmem_strbuf_append_unichar but appends a REPLACEMENT CHARACTER
 113  * instead for any invalid Unicode codepoints.
 114  */
 115 WS_DLL_PUBLIC
 116 void
 117 wmem_strbuf_append_unichar_validated(wmem_strbuf_t *strbuf, const gunichar c);
 118
 119 WS_DLL_PUBLIC
 120 void
 121 wmem_strbuf_append_hex(wmem_strbuf_t *strbuf, uint8_t);
 122
 123 /* Returns the number of characters written (4, 6 or 10). */
 124 WS_DLL_PUBLIC
 125 size_t
 126 wmem_strbuf_append_hex_unichar(wmem_strbuf_t *strbuf, gunichar);
 127
 128 WS_DLL_PUBLIC
 129 void
 130 wmem_strbuf_truncate(wmem_strbuf_t *strbuf, const size_t len);
 131
 132 WS_DLL_PUBLIC
 133 const char *
 134 wmem_strbuf_get_str(const wmem_strbuf_t *strbuf);
 135
 136 WS_DLL_PUBLIC
 137 size_t
 138 wmem_strbuf_get_len(const wmem_strbuf_t *strbuf);
 139
 140 WS_DLL_PUBLIC
 141 int
 142 wmem_strbuf_strcmp(const wmem_strbuf_t *sb1, const wmem_strbuf_t *sb2);
 143
 144 WS_DLL_PUBLIC
 145 const char *
 146 wmem_strbuf_strstr(const wmem_strbuf_t *haystack, const wmem_strbuf_t *needle);
 147
 148 /** Truncates the allocated memory down to the minimal amount, frees the header
 149  *  structure, and returns a non-const pointer to the raw string. The
 150  *  wmem_strbuf_t structure cannot be used after this is called. Basically a
 151  *  destructor for when you still need the underlying C-string.
 152  */
 153 WS_DLL_PUBLIC
 154 char *
 155 wmem_strbuf_finalize(wmem_strbuf_t *strbuf);
 156
 157 WS_DLL_PUBLIC
 158 void
 159 wmem_strbuf_destroy(wmem_strbuf_t *strbuf);
 160
 161 /* Validates the string buffer as UTF-8.
 162  * Unlike g_utf8_validate(), accepts embedded NUL bytes as valid UTF-8.
 163  * If endpptr is non-NULL, then the end of the valid range is stored there
 164  * (i.e. the first invalid character, or the end of the buffer otherwise).
 165  */
 166 WS_DLL_PUBLIC
 167 bool
 168 wmem_strbuf_utf8_validate(wmem_strbuf_t *strbuf, const char **endptr);
 169
 170 WS_DLL_PUBLIC
 171 void
 172 wmem_strbuf_utf8_make_valid(wmem_strbuf_t *strbuf);
 173
 174 /**   @}
 175  *  @} */
 176
 177 #ifdef __cplusplus
 178 }
 179 #endif /* __cplusplus */
 180
 181 #endif /* __WMEM_STRBUF_H__ */
 182
 183 /*
 184  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 185  *
 186  * Local variables:
 187  * c-basic-offset: 4
 188  * tab-width: 8
 189  * indent-tabs-mode: nil
 190  * End:
 191  *
 192  * vi: set shiftwidth=4 tabstop=8 expandtab:
 193  * :indentSize=4:tabSize=8:noTabs=true:
 194  */