Mercurial > libbuf
comparison buf.h @ 0:b1991ee4451d
misc: initial import
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 29 Oct 2020 17:24:30 +0100 |
parents | |
children | 9c6b686f797d |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:b1991ee4451d |
---|---|
1 /* | |
2 * buf.h -- simple string buffer for C | |
3 * | |
4 * Copyright (c) 2019-2020 David Demelier <markand@malikania.fr> | |
5 * | |
6 * Permission to use, copy, modify, and/or distribute this software for any | |
7 * purpose with or without fee is hereby granted, provided that the above | |
8 * copyright notice and this permission notice appear in all copies. | |
9 * | |
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
17 */ | |
18 | |
19 #ifndef BUF_H | |
20 #define BUF_H | |
21 | |
22 /** | |
23 * \file buf.h | |
24 * \brief Simple string buffer for C | |
25 * | |
26 * This module is meant to be copied directly into your source code and adapted | |
27 * to your needs. | |
28 * | |
29 * # Portability | |
30 * | |
31 * This module uses almost pure C99 functions without extensions but uses a few | |
32 * POSIX macros: ENOMEM. The errno global value won't be set if those macros | |
33 * are not present. | |
34 * | |
35 * It also requires the C99 features: `vsnprintf`, `va_copy`. | |
36 * | |
37 * # Allocation strategy | |
38 * | |
39 * This module will always try to allocate twice the existing buffer capacity | |
40 * unless it reaches an overflow. If overflow occurs, it will try to reallocate | |
41 * only the required portion instead. In any case, on 64-bits machine the | |
42 * maximum number is usually around 18.5PB which is far from what the system | |
43 * will allow. | |
44 * | |
45 * Functions use standard `malloc(3)`, `realloc(3)` and `free(3)` functions, if | |
46 * custom allocations are desired, simply edit buf.c and adapt BUF_ macros | |
47 * at the top of the file or set them at compile time. | |
48 */ | |
49 | |
50 #include <stdarg.h> | |
51 #include <stdbool.h> | |
52 #include <stddef.h> | |
53 | |
54 /* | |
55 * User/developer options. | |
56 * | |
57 * These macros are only used at compile time and can be redefined using | |
58 * preprocessor directives. | |
59 * | |
60 * - BUF_MALLOC: defaults to malloc | |
61 * - BUF_REALLOC: defaults to realloc | |
62 * - BUF_FREE: defaults to free | |
63 */ | |
64 | |
65 #if !defined(BUF_MALLOC) | |
66 # define BUF_MALLOC malloc | |
67 #endif | |
68 | |
69 #if !defined(BUF_REALLOC) | |
70 # define BUF_REALLOC realloc | |
71 #endif | |
72 | |
73 #if !defined(BUF_FREE) | |
74 # define BUF_FREE free | |
75 #endif | |
76 | |
77 /** | |
78 * \brief Buffer structure. | |
79 * | |
80 * You can initialize this structure with 0 before use. | |
81 * | |
82 * You may modify the data member yourself but make sure length member is set | |
83 * accordingly if you change its length. | |
84 * | |
85 * The capacity member contains the available size **without** including the | |
86 * null terminator, this means that a capacity of 5 means you can write 5 | |
87 * characters plus the null terminator as every function always allocate one | |
88 * more byte to terminate strings. | |
89 */ | |
90 struct buf { | |
91 char *data; /*!< String data. */ | |
92 size_t length; /*!< String length */ | |
93 size_t capacity; /*!< Capacity **not** including null */ | |
94 }; | |
95 | |
96 /** | |
97 * Initialize the string. | |
98 * | |
99 * This is equivalent to `memset(b, 0, sizeof (*b))`. | |
100 * | |
101 * \pre b != NULL | |
102 * \param b the buffer to initialize to 0 | |
103 */ | |
104 void | |
105 buf_init(struct buf *b); | |
106 | |
107 /** | |
108 * Reserve more storage to avoid reallocations. | |
109 * | |
110 * This function only change capacity and may reallocate the buffer, length | |
111 * is unchanged. | |
112 * | |
113 * \pre b != NULL | |
114 * \param b the buffer to grow | |
115 * \param desired the additional space to request | |
116 * \return false on error and sets errno | |
117 */ | |
118 bool | |
119 buf_reserve(struct buf *b, size_t desired); | |
120 | |
121 /** | |
122 * Resize the string and sets character into the new storage area if needed. | |
123 * | |
124 * In contrast to \ref buf_reserve, this function change the string length | |
125 * and update the new storage with the given character. if the new size is | |
126 * smaller then only length is updated, otherwise new memory can be reallocated | |
127 * if needed. | |
128 * | |
129 * Use '\0' if you only want to change the length but still have a NUL | |
130 * terminated string. | |
131 * | |
132 * \pre b != NULL | |
133 * \param b the buffer to grow | |
134 * \param desired the additional space to request | |
135 * \param c the character to fill (use '\0' if not needed) | |
136 * \return false on error and sets errno | |
137 */ | |
138 bool | |
139 buf_resize(struct buf *b, size_t size, char c); | |
140 | |
141 /** | |
142 * Reallocate the string to the string's length. | |
143 * | |
144 * If the function could not reallocate the memory, the old string buffer is | |
145 * kept so it is not strictly necessary to check the result. | |
146 * | |
147 * \pre b != NULL | |
148 * \param b the buffer to grow | |
149 * \return true if the string buffer was actually shrinked | |
150 */ | |
151 bool | |
152 buf_shrink(struct buf *b); | |
153 | |
154 /** | |
155 * Erase a portion of the string. | |
156 * | |
157 * \pre b != NULL | |
158 * \pre pos <= b->length | |
159 * \param b the string buffer | |
160 * \param pos the beginning of the portion | |
161 * \param count the number of characters to remove or -1 to remove up to the end | |
162 */ | |
163 void | |
164 buf_erase(struct buf *b, size_t pos, size_t count); | |
165 | |
166 /** | |
167 * Put a single character. | |
168 * | |
169 * \note This function can be slow for large amount of data. | |
170 * \pre b != NULL | |
171 * \param b the string buffer | |
172 * \param c the character to append | |
173 * \return false on error and sets errno | |
174 */ | |
175 bool | |
176 buf_putc(struct buf *b, char c); | |
177 | |
178 /** | |
179 * Put a string. | |
180 * | |
181 * \pre b != NULL | |
182 * \pre s != NULL | |
183 * \param b the string buffer | |
184 * \param s the string to append | |
185 * \return false on error and sets errno | |
186 */ | |
187 bool | |
188 buf_puts(struct buf *b, const char *s); | |
189 | |
190 /** | |
191 * Append to the string using printf(3) format. | |
192 * | |
193 * \pre b != NULL | |
194 * \pre fmt != NULL | |
195 * \param b the string buffer | |
196 * \param fmt the printf(3) format string | |
197 * \param ... additional arguments | |
198 * \return false on error and sets errno | |
199 */ | |
200 bool | |
201 buf_printf(struct buf *b, const char *fmt, ...); | |
202 | |
203 /** | |
204 * Similar to \ref buf_printf but using `va_list`. | |
205 * | |
206 * \pre b != NULL | |
207 * \pre fmt != NULL | |
208 * \param b the string buffer | |
209 * \param fmt the printf(3) format string | |
210 * \param ap the variadic arguments pointer | |
211 * \return false on error and sets errno | |
212 */ | |
213 bool | |
214 buf_vprintf(struct buf *b, const char *fmt, va_list ap); | |
215 | |
216 /** | |
217 * Cut a portion of the string pointed by src into b. | |
218 * | |
219 * The pointer b must not contain data as it will be overriden and may be let | |
220 * uninitialized. | |
221 * | |
222 * \pre b != NULL | |
223 * \pre src != NULL | |
224 * \pre pos <= b->length | |
225 * \param b the string buffer | |
226 * \param src the source origin | |
227 * \param pos the beginning of the portion | |
228 * \param count the number of characters to remove or -1 to split up to the end | |
229 * \return false on error and sets errno | |
230 */ | |
231 bool | |
232 buf_sub(struct buf *b, const struct buf *src, size_t pos, size_t count); | |
233 | |
234 /** | |
235 * Duplicate a string buffer. | |
236 * | |
237 * The pointer b must not contain data as it will be overriden and may be let | |
238 * uninitialized. | |
239 * | |
240 * \pre b != NULL | |
241 * \pre src != NULL | |
242 * \param b the string buffer | |
243 * \param src the source origin | |
244 * \return false on error and sets errno | |
245 */ | |
246 bool | |
247 buf_dup(struct buf *b, const struct buf *src); | |
248 | |
249 /** | |
250 * Clear the buffer. | |
251 * | |
252 * This function only change the string length, use \ref buf_shrink if you | |
253 * want to reduce memory usage. | |
254 * | |
255 * \pre b != NULL | |
256 * \param b the string to update | |
257 */ | |
258 void | |
259 buf_clear(struct buf *b); | |
260 | |
261 /** | |
262 * Clear the buffer. | |
263 * | |
264 * This function will effectively free the data member and set all members to | |
265 * 0. | |
266 * | |
267 * \pre b != NULL | |
268 * \param b the buffer to clear | |
269 */ | |
270 void | |
271 buf_finish(struct buf *b); | |
272 | |
273 #endif /* !BUF_H */ |