Debian Codegraph @

libdrgn/string_builder.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * String builder interface.
8 *
9 * See @ref StringBuilding.
10 */
11
12 #ifndef DRGN_STRING_BUILDER_H
13 #define DRGN_STRING_BUILDER_H
14
15 #include <stdarg.h>
16 #include <stdbool.h>
17 #include <stddef.h>
18 #include <stdlib.h>
19 #include <string.h>
20
21 /**
22 * @ingroup Internals
23 *
24 * @defgroup StringBuilding String building
25 *
26 * String builder interface.
27 *
28 * @ref string_builder provides an append-only way to build a string piece by
29 * piece. @ref string_callback provides an alternative to prepending pieces.
30 *
31 * @{
32 */
33
34 /**
35 * String builder.
36 *
37 * A string builder consists of a buffer and a length. The buffer is resized as
38 * needed. The buffer can only be appended to; see @ref string_callback for an
39 * alternative to insertion.
40 */
41 struct string_builder {
42 /**
43 * Current string buffer.
44 *
45 * This may be reallocated when appending.
46 */
47 char *str;
48 /** Length of @c str. */
49 size_t len;
50 /** Allocated size of @c str. */
51 size_t capacity;
52 };
53
54 /** String builder initializer. */
55 #define STRING_BUILDER_INIT { 0 }
56
57 /** Free memory allocated by a @ref string_builder. */
58 static inline void string_builder_deinit(struct string_builder *sb)
59 {
60 free(sb->str);
61 }
62
63 /**
64 * Define and initialize a @ref string_builder named @p sb that is automatically
65 * deinitialized when it goes out of scope.
66 */
67 #define STRING_BUILDER(sb) \
68 __attribute__((__cleanup__(string_builder_deinit))) \
69 struct string_builder sb = STRING_BUILDER_INIT
70
71 /**
72 * Steal the string buffer from a @ref string_builder.
73 *
74 * The string builder can no longer be used except to be passed to @ref
75 * string_builder_deinit(), which will do nothing.
76 *
77 * @return String buffer. This must be freed with @c free().
78 */
79 static inline char *string_builder_steal(struct string_builder *sb)
80 {
81 char *str = sb->str;
82 sb->str = NULL;
83 return str;
84 }
85
86 /**
87 * Null-terminate a @ref string_builder.
88 *
89 * This appends a null character without incrementing @ref string_builder::len.
90 *
91 * @return @c true on success, @c false on error (if we couldn't allocate
92 * memory).
93 */
94 bool string_builder_null_terminate(struct string_builder *sb);
95
96 /**
97 * Resize the buffer of a @ref string_builder to a given capacity.
98 *
99 * On success, the allocated size of the string buffer is at least @p capacity.
100 *
101 * @param[in] sb String builder.
102 * @param[in] capacity New minimum allocated size of the string buffer.
103 * @return @c true on success, @c false on error (if we couldn't allocate
104 * memory).
105 */
106 bool string_builder_reserve(struct string_builder *sb, size_t capacity);
107
108 /**
109 * Resize the buffer of a @ref string_builder to accomodate appending
110 * characters.
111 *
112 * On success, the allocated size of the string buffer is at least
113 * `sb->len + n`. This will also allocate extra space so that appends have
114 * amortized constant time complexity.
115 *
116 * @param[in] sb String builder.
117 * @param[in] n Minimum number of additional characters to reserve.
118 * @return @c true on success, @c false on error (if we couldn't allocate
119 * memory).
120 */
121 bool string_builder_reserve_for_append(struct string_builder *sb, size_t n);
122
123 /**
124 * Append a character to a @ref string_builder.
125 *
126 * @param[in] sb String builder.
127 * @param[in] c Character to append.
128 * @return @c true on success, @c false on error (if we couldn't allocate
129 * memory).
130 */
131 bool string_builder_appendc(struct string_builder *sb, char c);
132
133 /**
134 * Append a number of characters from a string to a @ref string_builder.
135 *
136 * @param[in] sb String builder.
137 * @param[in] str String to append.
138 * @param[in] len Number of characters from @c str to append.
139 * @return @c true on success, @c false on error (if we couldn't allocate
140 * memory).
141 */
142 bool string_builder_appendn(struct string_builder *sb, const char *str,
143 size_t len);
144
145 /**
146 * Append a null-terminated string to a @ref string_builder.
147 *
148 * @param[in] sb String builder.
149 * @param[in] str String to append.
150 * @return @c true on success, @c false on error (if we couldn't allocate
151 * memory).
152 */
153 static inline bool string_builder_append(struct string_builder *sb,
154 const char *str)
155 {
156 return string_builder_appendn(sb, str, strlen(str));
157 }
158
159 /**
160 * Append a string to a @ref string_builder from a printf-style format.
161 *
162 * @param[in] sb String builder.
163 * @param[in] format printf-style format string.
164 * @param[in] ... Arguments for the format string.
165 * @return @c true on success, @c false on error (if we couldn't allocate
166 * memory).
167 */
168 bool string_builder_appendf(struct string_builder *sb, const char *format, ...)
169 __attribute__((__format__(__printf__, 2, 3)));
170
171 /**
172 * Append a string to a @ref string_builder from vprintf-style arguments.
173 *
174 * @sa string_builder_appendf()
175 *
176 * @param[in] sb String builder.
177 * @param[in] format printf-style format string.
178 * @param[in] ap Arguments for the format string.
179 * @return @c true on success, @c false on error (if we couldn't allocate
180 * memory).
181 */
182 bool string_builder_vappendf(struct string_builder *sb, const char *format,
183 va_list ap);
184
185 /**
186 * Append a newline character to a @ref string_builder if the string isn't empty
187 * and doesn't already end in a newline.
188 *
189 * @param[in] sb String builder.
190 * @return @c true on success, @c false on error (if we couldn't allocate
191 * memory).
192 */
193 bool string_builder_line_break(struct string_builder *sb);
194
195 /**
196 * Callback to append to a string later.
197 *
198 * Instead of providing functionality to prepend to a @ref string_builder, we
199 * achieve the same thing by passing around a callback until all prefixes have
200 * been appended, then calling the callback to append the "infix". This avoids
201 * the O(n) array shift required for prepend.
202 */
203 struct string_callback {
204 /** Callback function. */
205 struct drgn_error *(*fn)(struct string_callback *str, void *arg,
206 struct string_builder *sb);
207 /**
208 * Another string callback to be passed to the callback.
209 *
210 * This is useful for strings that need to be built recursively.
211 */
212 struct string_callback *str;
213 /** Callback argument. */
214 void *arg;
215 };
216
217 /**
218 * Call a string callback.
219 *
220 * The callback function will be passed @ref string_callback::str and @ref
221 * string_callback::arg.
222 *
223 * @param[in] str String callback. If @c NULL, this is a no-op.
224 * @param[in] sb String builder to append to.
225 * @return @c true on success, @c false on error (if we couldn't allocate
226 * memory).
227 */
228 static inline struct drgn_error *string_callback_call(struct string_callback *str,
229 struct string_builder *sb)
230 {
231 if (str)
232 return str->fn(str->str, str->arg, sb);
233 else
234 return NULL;
235 }
236
237 /** @} */
238
239 #endif /* DRGN_STRING_BUILDER_H */