diff options
Diffstat (limited to 'libraries/eina/src/include/eina_strbuf.h')
-rw-r--r-- | libraries/eina/src/include/eina_strbuf.h | 623 |
1 files changed, 0 insertions, 623 deletions
diff --git a/libraries/eina/src/include/eina_strbuf.h b/libraries/eina/src/include/eina_strbuf.h deleted file mode 100644 index 34c200f..0000000 --- a/libraries/eina/src/include/eina_strbuf.h +++ /dev/null | |||
@@ -1,623 +0,0 @@ | |||
1 | #ifndef EINA_STRBUF_H | ||
2 | #define EINA_STRBUF_H | ||
3 | |||
4 | #include <stddef.h> | ||
5 | #include <stdarg.h> | ||
6 | |||
7 | #include "eina_types.h" | ||
8 | |||
9 | |||
10 | /** | ||
11 | * @page tutorial_strbuf Eina_Strbuf example | ||
12 | * @dontinclude eina_strbuf_01.c | ||
13 | * | ||
14 | * First thing always is including Eina: | ||
15 | * @skipline #include | ||
16 | * @until #include | ||
17 | * | ||
18 | * Next we initialize eina and create a string buffer to play with: | ||
19 | * @until strbuf_new | ||
20 | * | ||
21 | * Here you can see two different ways of creating a buffer with the same | ||
22 | * contents. We could create them in simpler ways, but this gives us an | ||
23 | * opportunity to demonstrate several functions in action: | ||
24 | * @until strbuf_reset | ||
25 | * @until strbuf_reset | ||
26 | * | ||
27 | * Next we use the printf family of functions to create a formated string, | ||
28 | * add, remove and replace some content: | ||
29 | * @until strbuf_string_get | ||
30 | * @until strbuf_string_get | ||
31 | * @until strbuf_string_get | ||
32 | * | ||
33 | * Once done we free our string buffer, shut down Eina and end the application: | ||
34 | * @until } | ||
35 | * | ||
36 | * @example eina_strbuf_01.c | ||
37 | */ | ||
38 | /** | ||
39 | * @addtogroup Eina_String_Buffer_Group String Buffer | ||
40 | * | ||
41 | * @brief These functions provide string buffers management. | ||
42 | * | ||
43 | * The String Buffer data type is designed to be a mutable string, | ||
44 | * allowing to append, prepend or insert a string to a buffer. | ||
45 | * | ||
46 | * For more information see @ref tutorial_strbuf "this example". | ||
47 | */ | ||
48 | |||
49 | /** | ||
50 | * @addtogroup Eina_Data_Types_Group Data Types | ||
51 | * | ||
52 | * @{ | ||
53 | */ | ||
54 | |||
55 | /** | ||
56 | * @defgroup Eina_String_Buffer_Group String Buffer | ||
57 | * | ||
58 | * @{ | ||
59 | */ | ||
60 | |||
61 | /** | ||
62 | * @typedef Eina_Strbuf | ||
63 | * Type for a string buffer. | ||
64 | */ | ||
65 | typedef struct _Eina_Strbuf Eina_Strbuf; | ||
66 | |||
67 | /** | ||
68 | * @brief Create a new string buffer. | ||
69 | * | ||
70 | * @return Newly allocated string buffer instance. | ||
71 | * | ||
72 | * This function creates a new string buffer. On error, @c NULL is | ||
73 | * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | ||
74 | * free the resources, use eina_strbuf_free(). | ||
75 | * | ||
76 | * @see eina_strbuf_free() | ||
77 | * @see eina_strbuf_append() | ||
78 | * @see eina_strbuf_string_get() | ||
79 | */ | ||
80 | EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
81 | |||
82 | /** | ||
83 | * @brief Create a new string buffer using the passed string. The passed | ||
84 | * string is used directly as the buffer, it's somehow the opposite function of | ||
85 | * @ref eina_strbuf_string_steal . The passed string must be malloced. | ||
86 | * | ||
87 | * @param str the string to manage | ||
88 | * @return Newly allocated string buffer instance. | ||
89 | * | ||
90 | * This function creates a new string buffer. On error, @c NULL is | ||
91 | * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | ||
92 | * free the resources, use eina_strbuf_free(). | ||
93 | * | ||
94 | * @see eina_strbuf_free() | ||
95 | * @see eina_strbuf_append() | ||
96 | * @see eina_strbuf_string_get() | ||
97 | * @since 1.1.0 | ||
98 | */ | ||
99 | EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
100 | |||
101 | /** | ||
102 | * @brief Create a new string buffer using the passed string. The passed | ||
103 | * string is used directly as the buffer, it's somehow the opposite function of | ||
104 | * @ref eina_strbuf_string_steal . The passed string must be malloced. | ||
105 | * | ||
106 | * @param str the string to manage | ||
107 | * @param length the length of the string. | ||
108 | * @return Newly allocated string buffer instance. | ||
109 | * | ||
110 | * This function creates a new string buffer. On error, @c NULL is | ||
111 | * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | ||
112 | * free the resources, use eina_strbuf_free(). | ||
113 | * | ||
114 | * @see eina_strbuf_manage_new() | ||
115 | * @since 1.2.0 | ||
116 | */ | ||
117 | EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
118 | |||
119 | /** | ||
120 | * @brief Free a string buffer. | ||
121 | * | ||
122 | * @param buf The string buffer to free. | ||
123 | * | ||
124 | * This function frees the memory of @p buf. @p buf must have been | ||
125 | * created by eina_strbuf_new(). | ||
126 | */ | ||
127 | EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
128 | |||
129 | /** | ||
130 | * @brief Reset a string buffer. | ||
131 | * | ||
132 | * @param buf The string buffer to reset. | ||
133 | * | ||
134 | * This function reset @p buf: the buffer len is set to 0, and the | ||
135 | * string is set to '\\0'. No memory is free'd. | ||
136 | */ | ||
137 | EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
138 | |||
139 | /** | ||
140 | * @brief Append a string to a buffer, reallocating as necessary. | ||
141 | * | ||
142 | * @param buf The string buffer to append to. | ||
143 | * @param str The string to append. | ||
144 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
145 | * | ||
146 | * This function appends @p str to @p buf. It computes the length of | ||
147 | * @p str, so is slightly slower than eina_strbuf_append_length(). If | ||
148 | * the length is known beforehand, consider using that variant. If | ||
149 | * @p buf can't append it, #EINA_FALSE is returned, otherwise | ||
150 | * #EINA_TRUE is returned. | ||
151 | * | ||
152 | * @see eina_strbuf_append() | ||
153 | * @see eina_strbuf_append_length() | ||
154 | */ | ||
155 | EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); | ||
156 | |||
157 | /** | ||
158 | * @brief Append an escaped string to a buffer, reallocating as necessary. | ||
159 | * | ||
160 | * @param buf The string buffer to append to. | ||
161 | * @param str The string to append. | ||
162 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
163 | * | ||
164 | * This function escapes and then appends the string @p str to @p buf. If @p str | ||
165 | * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is | ||
166 | * returned. | ||
167 | */ | ||
168 | EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); | ||
169 | |||
170 | /** | ||
171 | * @brief Append a string to a buffer, reallocating as necessary, | ||
172 | * limited by the given length. | ||
173 | * | ||
174 | * @param buf The string buffer to append to. | ||
175 | * @param str The string to append. | ||
176 | * @param maxlen The maximum number of characters to append. | ||
177 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
178 | * | ||
179 | * This function appends at most @p maxlen characters of @p str to | ||
180 | * @p buf. It can't append more than the length of @p str. It | ||
181 | * computes the length of @p str, so it is slightly slower than | ||
182 | * eina_strbuf_append_length(). If the length is known beforehand, | ||
183 | * consider using that variant (@p maxlen should then be checked so | ||
184 | * that it is greater than the size of @p str). If @p str can not be | ||
185 | * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is | ||
186 | * returned. | ||
187 | * | ||
188 | * @see eina_strbuf_append() | ||
189 | * @see eina_strbuf_append_length() | ||
190 | */ | ||
191 | EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2); | ||
192 | |||
193 | /** | ||
194 | * @brief Append a string of exact length to a buffer, reallocating as necessary. | ||
195 | * | ||
196 | * @param buf The string buffer to append to. | ||
197 | * @param str The string to append. | ||
198 | * @param length The exact length to use. | ||
199 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
200 | * | ||
201 | * This function appends @p str to @p buf. @p str must be of size at | ||
202 | * most @p length. It is slightly faster than eina_strbuf_append() as | ||
203 | * it does not compute the size of @p str. It is useful when dealing | ||
204 | * with strings of known size, such as eina_stringshare. If @p buf | ||
205 | * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
206 | * returned. | ||
207 | * | ||
208 | * @see eina_stringshare_length() | ||
209 | * @see eina_strbuf_append() | ||
210 | * @see eina_strbuf_append_n() | ||
211 | */ | ||
212 | EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size_t length) EINA_ARG_NONNULL(1, 2); | ||
213 | |||
214 | /** | ||
215 | * @brief Append a character to a string buffer, reallocating as | ||
216 | * necessary. | ||
217 | * | ||
218 | * @param buf The string buffer to append to. | ||
219 | * @param c The char to append. | ||
220 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
221 | * | ||
222 | * This function inserts @p c to @p buf. If it can not insert it, | ||
223 | * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. | ||
224 | */ | ||
225 | EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1); | ||
226 | |||
227 | /** | ||
228 | * @brief Append a string to a buffer, reallocating as necessary. | ||
229 | * | ||
230 | * @param buf The string buffer to append to. | ||
231 | * @param fmt The string to append. | ||
232 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
233 | * | ||
234 | * This function appends the string defined by the format @p fmt to @p buf. @p | ||
235 | * fmt must be of a valid format for printf family of functions. If it can't | ||
236 | * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. | ||
237 | * | ||
238 | * @see eina_strbuf_append() | ||
239 | */ | ||
240 | EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); | ||
241 | |||
242 | /** | ||
243 | * @brief Append a string to a buffer, reallocating as necessary. | ||
244 | * | ||
245 | * @param buf The string buffer to append to. | ||
246 | * @param fmt The string to append. | ||
247 | * @param args The variable arguments. | ||
248 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
249 | * | ||
250 | * @see eina_strbuf_append_printf() | ||
251 | */ | ||
252 | EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2); | ||
253 | |||
254 | /** | ||
255 | * @brief Insert a string to a buffer, reallocating as necessary. | ||
256 | * | ||
257 | * @param buf The string buffer to insert. | ||
258 | * @param str The string to insert. | ||
259 | * @param pos The position to insert the string. | ||
260 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
261 | * | ||
262 | * This function inserts @p str to @p buf at position @p pos. It | ||
263 | * computes the length of @p str, so is slightly slower than | ||
264 | * eina_strbuf_insert_length(). If the length is known beforehand, | ||
265 | * consider using that variant. If @p buf can't insert it, #EINA_FALSE | ||
266 | * is returned, otherwise #EINA_TRUE is returned. | ||
267 | */ | ||
268 | EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
269 | |||
270 | /** | ||
271 | * @brief Insert an escaped string to a buffer, reallocating as | ||
272 | * necessary. | ||
273 | * | ||
274 | * @param buf The string buffer to insert to. | ||
275 | * @param str The string to insert. | ||
276 | * @param pos The position to insert the string. | ||
277 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
278 | * | ||
279 | * This function escapes and inserts the string @p str to @p buf at | ||
280 | * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is | ||
281 | * returned, otherwise #EINA_TRUE is returned. | ||
282 | */ | ||
283 | EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
284 | |||
285 | /** | ||
286 | * @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen. | ||
287 | * | ||
288 | * @param buf The string buffer to insert to. | ||
289 | * @param str The string to insert. | ||
290 | * @param maxlen The maximum number of chars to insert. | ||
291 | * @param pos The position to insert the string. | ||
292 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
293 | * | ||
294 | * This function inserts @p str to @p buf at position @p pos, with at | ||
295 | * most @p maxlen bytes. The number of inserted characters can not be | ||
296 | * greater than the length of @p str. It computes the length of | ||
297 | * @p str, so is slightly slower than eina_strbuf_insert_length(). If the | ||
298 | * length is known beforehand, consider using that variant (@p maxlen | ||
299 | * should then be checked so that it is greater than the size of | ||
300 | * @p str). If @p str can not be inserted, #EINA_FALSE is returned, | ||
301 | * otherwise, #EINA_TRUE is returned. | ||
302 | */ | ||
303 | EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
304 | |||
305 | /** | ||
306 | * @brief Insert a string of exact length to a buffer, reallocating as necessary. | ||
307 | * | ||
308 | * @param buf The string buffer to insert to. | ||
309 | * @param str The string to insert. | ||
310 | * @param length The exact length to use. | ||
311 | * @param pos The position to insert the string. | ||
312 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
313 | * | ||
314 | * This function inserts @p str to @p buf. @p str must be of size at | ||
315 | * most @p length. It is slightly faster than eina_strbuf_insert() as | ||
316 | * it does not compute the size of @p str. It is useful when dealing | ||
317 | * with strings of known size, such as eina_strngshare. If @p buf | ||
318 | * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
319 | * returned. | ||
320 | * | ||
321 | * @see eina_stringshare_length() | ||
322 | * @see eina_strbuf_insert() | ||
323 | * @see eina_strbuf_insert_n() | ||
324 | */ | ||
325 | EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
326 | |||
327 | /** | ||
328 | * @brief Insert a character to a string buffer, reallocating as | ||
329 | * necessary. | ||
330 | * | ||
331 | * @param buf The string buffer to insert to. | ||
332 | * @param c The char to insert. | ||
333 | * @param pos The position to insert the char. | ||
334 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
335 | * | ||
336 | * This function inserts @p c to @p buf at position @p pos. If @p buf | ||
337 | * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
338 | * returned. | ||
339 | */ | ||
340 | EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1); | ||
341 | |||
342 | /** | ||
343 | * @brief Insert a string to a buffer, reallocating as necessary. | ||
344 | * | ||
345 | * @param buf The string buffer to insert. | ||
346 | * @param fmt The string to insert. | ||
347 | * @param pos The position to insert the string. | ||
348 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
349 | * | ||
350 | * This function insert a string as described by the format @p fmt to @p buf at | ||
351 | * the position @p pos. @p fmt must be of a valid format for printf family of | ||
352 | * functions. If it can't insert it, #EINA_FALSE is returned, otherwise | ||
353 | * #EINA_TRUE is returned. | ||
354 | */ | ||
355 | EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4); | ||
356 | |||
357 | /** | ||
358 | * @brief Insert a string to a buffer, reallocating as necessary. | ||
359 | * | ||
360 | * @param buf The string buffer to insert. | ||
361 | * @param fmt The string to insert. | ||
362 | * @param pos The position to insert the string. | ||
363 | * @param args The variable arguments. | ||
364 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
365 | * | ||
366 | * @see eina_strbuf_insert_printf | ||
367 | */ | ||
368 | EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, size_t pos, va_list args) EINA_ARG_NONNULL(1, 2); | ||
369 | |||
370 | /** | ||
371 | * @def eina_strbuf_prepend(buf, str) | ||
372 | * @brief Prepend the given string to the given buffer | ||
373 | * | ||
374 | * @param buf The string buffer to prepend to. | ||
375 | * @param str The string to prepend. | ||
376 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
377 | * | ||
378 | * This macro is calling eina_strbuf_insert() at position 0. If @p buf | ||
379 | * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
380 | * returned. | ||
381 | */ | ||
382 | #define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf, str, 0) | ||
383 | |||
384 | /** | ||
385 | * @def eina_strbuf_prepend_escaped(buf, str) | ||
386 | * @brief Prepend the given escaped string to the given buffer | ||
387 | * | ||
388 | * @param buf The string buffer to prepend to. | ||
389 | * @param str The string to prepend. | ||
390 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
391 | * | ||
392 | * This macro is calling eina_strbuf_insert_escaped() at position 0. If | ||
393 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
394 | * #EINA_TRUE is returned. | ||
395 | */ | ||
396 | #define eina_strbuf_prepend_escaped(buf, str) eina_strbuf_insert_escaped(buf, str, 0) | ||
397 | |||
398 | /** | ||
399 | * @def eina_strbuf_prepend_n(buf, str) | ||
400 | * @brief Prepend the given escaped string to the given buffer | ||
401 | * | ||
402 | * @param buf The string buffer to prepend to. | ||
403 | * @param str The string to prepend. | ||
404 | * @param maxlen The maximum number of chars to prepend. | ||
405 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
406 | * | ||
407 | * This macro is calling eina_strbuf_insert_n() at position 0. If | ||
408 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
409 | * #EINA_TRUE is returned. | ||
410 | */ | ||
411 | #define eina_strbuf_prepend_n(buf, str, maxlen) eina_strbuf_insert_n(buf, str, maxlen, 0) | ||
412 | |||
413 | /** | ||
414 | * @def eina_strbuf_prepend_length(buf, str) | ||
415 | * @brief Prepend the given escaped string to the given buffer | ||
416 | * | ||
417 | * @param buf The string buffer to prepend to. | ||
418 | * @param str The string to prepend. | ||
419 | * @param length The exact length to use. | ||
420 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
421 | * | ||
422 | * This macro is calling eina_strbuf_insert_length() at position 0. If | ||
423 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
424 | * #EINA_TRUE is returned. | ||
425 | */ | ||
426 | #define eina_strbuf_prepend_length(buf, str, length) eina_strbuf_insert_length(buf, str, length, 0) | ||
427 | |||
428 | /** | ||
429 | * @def eina_strbuf_prepend_char(buf, str) | ||
430 | * @brief Prepend the given character to the given buffer | ||
431 | * | ||
432 | * @param buf The string buffer to prepend to. | ||
433 | * @param c The character to prepend. | ||
434 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
435 | * | ||
436 | * This macro is calling eina_strbuf_insert_char() at position 0. If | ||
437 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
438 | * #EINA_TRUE is returned. | ||
439 | */ | ||
440 | #define eina_strbuf_prepend_char(buf, c) eina_strbuf_insert_char(buf, c, 0) | ||
441 | |||
442 | /** | ||
443 | * @def eina_strbuf_prepend_printf(buf, fmt, ...) | ||
444 | * @brief Prepend the given string to the given buffer | ||
445 | * | ||
446 | * @param buf The string buffer to prepend to. | ||
447 | * @param fmt The string to prepend. | ||
448 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
449 | * | ||
450 | * This macro is calling eina_strbuf_insert_printf() at position 0.If @p buf | ||
451 | * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
452 | * returned. | ||
453 | */ | ||
454 | #define eina_strbuf_prepend_printf(buf, fmt, ...) eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__) | ||
455 | |||
456 | /** | ||
457 | * @def eina_strbuf_prepend_vprintf(buf, fmt, args) | ||
458 | * @brief Prepend the given string to the given buffer | ||
459 | * | ||
460 | * @param buf The string buffer to prepend to. | ||
461 | * @param fmt The string to prepend. | ||
462 | * @param args The variable arguments. | ||
463 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
464 | * | ||
465 | * This macro is calling eina_strbuf_insert_vprintf() at position 0.If @p buf | ||
466 | * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
467 | * returned. | ||
468 | */ | ||
469 | #define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args) | ||
470 | |||
471 | /** | ||
472 | * @brief Remove a slice of the given string buffer. | ||
473 | * | ||
474 | * @param buf The string buffer to remove a slice. | ||
475 | * @param start The initial (inclusive) slice position to start | ||
476 | * removing, in bytes. | ||
477 | * @param end The final (non-inclusive) slice position to finish | ||
478 | * removing, in bytes. | ||
479 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
480 | * | ||
481 | * This function removes a slice of @p buf, starting at @p start | ||
482 | * (inclusive) and ending at @p end (non-inclusive). Both values are | ||
483 | * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. | ||
484 | */ | ||
485 | |||
486 | EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); | ||
487 | |||
488 | /** | ||
489 | * @brief Retrieve a pointer to the contents of a string buffer | ||
490 | * | ||
491 | * @param buf The string buffer. | ||
492 | * @return The current string in the string buffer. | ||
493 | * | ||
494 | * This function returns the string contained in @p buf. The returned | ||
495 | * value must not be modified and will no longer be valid if @p buf is | ||
496 | * modified. In other words, any eina_strbuf_append() or similar will | ||
497 | * make that pointer invalid. The pointer returned by this function <b>must | ||
498 | * not</b> be freed. | ||
499 | * | ||
500 | * @see eina_strbuf_string_steal() | ||
501 | */ | ||
502 | EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
503 | |||
504 | /** | ||
505 | * @brief Steal the contents of a string buffer. | ||
506 | * | ||
507 | * @param buf The string buffer to steal. | ||
508 | * @return The current string in the string buffer. | ||
509 | * | ||
510 | * This function returns the string contained in @p buf. @p buf is | ||
511 | * then initialized and does not own the returned string anymore. The | ||
512 | * caller must release the memory of the returned string by calling | ||
513 | * free(). | ||
514 | * | ||
515 | * @see eina_strbuf_string_get() | ||
516 | */ | ||
517 | EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | ||
518 | |||
519 | /** | ||
520 | * @brief Free the contents of a string buffer but not the buffer. | ||
521 | * | ||
522 | * @param buf The string buffer to free the string of. | ||
523 | * | ||
524 | * This function frees the string contained in @p buf without freeing | ||
525 | * @p buf. | ||
526 | */ | ||
527 | EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
528 | |||
529 | /** | ||
530 | * @brief Retrieve the length of the string buffer content. | ||
531 | * | ||
532 | * @param buf The string buffer. | ||
533 | * @return The current length of the string, in bytes. | ||
534 | * | ||
535 | * This function returns the length of @p buf. | ||
536 | */ | ||
537 | EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
538 | |||
539 | |||
540 | /** | ||
541 | * @brief Replace the n-th string with an other string. | ||
542 | * | ||
543 | * @param buf The string buffer to work with. | ||
544 | * @param str The string to replace. | ||
545 | * @param with The replaceing string. | ||
546 | * @param n The number of the fitting string. | ||
547 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
548 | * | ||
549 | * This function replaces the n-th occurrence of @p str in @p buf with | ||
550 | * @p with. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. | ||
551 | */ | ||
552 | EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3); | ||
553 | |||
554 | /** | ||
555 | * @def eina_strbuf_replace_first(buf, str, with) | ||
556 | * @brief Prepend the given character to the given buffer | ||
557 | * | ||
558 | * @param buf The string buffer to work with. | ||
559 | * @param str The string to replace. | ||
560 | * @param with The replaceing string. | ||
561 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
562 | * | ||
563 | * This macro is calling eina_strbuf_replace() with the n-th occurrence | ||
564 | * equal to @c 1. If @p buf can't replace it, #EINA_FALSE is returned, | ||
565 | * otherwise #EINA_TRUE is returned. | ||
566 | */ | ||
567 | #define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf, str, with, 1) | ||
568 | |||
569 | |||
570 | /** | ||
571 | * @brief Replace all strings with an other string. | ||
572 | |||
573 | * @param buf the string buffer to work with. | ||
574 | * @param str The string to replace. | ||
575 | * @param with The replaceing string. | ||
576 | * @return How often the string was replaced. | ||
577 | * | ||
578 | * This function replaces all the occurrences of @p str in @p buf with | ||
579 | * the string @p with. This function returns the number of times @p str | ||
580 | * has been replaced. On failure, it returns 0. | ||
581 | */ | ||
582 | EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3); | ||
583 | |||
584 | /** | ||
585 | * @brief Trim the string buffer | ||
586 | |||
587 | * @param buf the string buffer to work with. | ||
588 | * | ||
589 | * This function skips whitespaces in the beginning and the end of the buffer. | ||
590 | */ | ||
591 | EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
592 | |||
593 | /** | ||
594 | * @brief Left trim the string buffer | ||
595 | |||
596 | * @param buf the string buffer to work with. | ||
597 | * | ||
598 | * This function skips whitespaces in the beginning of the buffer. | ||
599 | */ | ||
600 | EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
601 | |||
602 | /** | ||
603 | * @brief Right trim the string buffer | ||
604 | |||
605 | * @param buf the string buffer to work with. | ||
606 | * | ||
607 | * This function skips whitespaces in the end of the buffer. | ||
608 | */ | ||
609 | EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
610 | |||
611 | /** | ||
612 | * @} | ||
613 | */ | ||
614 | |||
615 | /** | ||
616 | * @} | ||
617 | */ | ||
618 | |||
619 | /** | ||
620 | * @} | ||
621 | */ | ||
622 | |||
623 | #endif /* EINA_STRBUF_H */ | ||