diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_strbuf.h | 605 |
1 files changed, 605 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_strbuf.h b/libraries/eina/src/include/eina_strbuf.h new file mode 100644 index 0000000..7043575 --- /dev/null +++ b/libraries/eina/src/include/eina_strbuf.h | |||
@@ -0,0 +1,605 @@ | |||
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 Free a string buffer. | ||
103 | * | ||
104 | * @param buf The string buffer to free. | ||
105 | * | ||
106 | * This function frees the memory of @p buf. @p buf must have been | ||
107 | * created by eina_strbuf_new(). | ||
108 | */ | ||
109 | EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
110 | |||
111 | /** | ||
112 | * @brief Reset a string buffer. | ||
113 | * | ||
114 | * @param buf The string buffer to reset. | ||
115 | * | ||
116 | * This function reset @p buf: the buffer len is set to 0, and the | ||
117 | * string is set to '\\0'. No memory is free'd. | ||
118 | */ | ||
119 | EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
120 | |||
121 | /** | ||
122 | * @brief Append a string to a buffer, reallocating as necessary. | ||
123 | * | ||
124 | * @param buf The string buffer to append to. | ||
125 | * @param str The string to append. | ||
126 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
127 | * | ||
128 | * This function appends @p str to @p buf. It computes the length of | ||
129 | * @p str, so is slightly slower than eina_strbuf_append_length(). If | ||
130 | * the length is known beforehand, consider using that variant. If | ||
131 | * @p buf can't append it, #EINA_FALSE is returned, otherwise | ||
132 | * #EINA_TRUE is returned. | ||
133 | * | ||
134 | * @see eina_strbuf_append() | ||
135 | * @see eina_strbuf_append_length() | ||
136 | */ | ||
137 | EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); | ||
138 | |||
139 | /** | ||
140 | * @brief Append an escaped 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 escapes and then appends the string @p str to @p buf. If @p str | ||
147 | * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is | ||
148 | * returned. | ||
149 | */ | ||
150 | EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); | ||
151 | |||
152 | /** | ||
153 | * @brief Append a string to a buffer, reallocating as necessary, | ||
154 | * limited by the given length. | ||
155 | * | ||
156 | * @param buf The string buffer to append to. | ||
157 | * @param str The string to append. | ||
158 | * @param maxlen The maximum number of characters to append. | ||
159 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
160 | * | ||
161 | * This function appends at most @p maxlen characters of @p str to | ||
162 | * @p buf. It can't append more than the length of @p str. It | ||
163 | * computes the length of @p str, so it is slightly slower than | ||
164 | * eina_strbuf_append_length(). If the length is known beforehand, | ||
165 | * consider using that variant (@p maxlen should then be checked so | ||
166 | * that it is greater than the size of @p str). If @p str can not be | ||
167 | * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is | ||
168 | * returned. | ||
169 | * | ||
170 | * @see eina_strbuf_append() | ||
171 | * @see eina_strbuf_append_length() | ||
172 | */ | ||
173 | EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2); | ||
174 | |||
175 | /** | ||
176 | * @brief Append a string of exact length to a buffer, reallocating as necessary. | ||
177 | * | ||
178 | * @param buf The string buffer to append to. | ||
179 | * @param str The string to append. | ||
180 | * @param length The exact length to use. | ||
181 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
182 | * | ||
183 | * This function appends @p str to @p buf. @p str must be of size at | ||
184 | * most @p length. It is slightly faster than eina_strbuf_append() as | ||
185 | * it does not compute the size of @p str. It is useful when dealing | ||
186 | * with strings of known size, such as eina_stringshare. If @p buf | ||
187 | * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
188 | * returned. | ||
189 | * | ||
190 | * @see eina_stringshare_length() | ||
191 | * @see eina_strbuf_append() | ||
192 | * @see eina_strbuf_append_n() | ||
193 | */ | ||
194 | EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size_t length) EINA_ARG_NONNULL(1, 2); | ||
195 | |||
196 | /** | ||
197 | * @brief Append a character to a string buffer, reallocating as | ||
198 | * necessary. | ||
199 | * | ||
200 | * @param buf The string buffer to append to. | ||
201 | * @param c The char to append. | ||
202 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
203 | * | ||
204 | * This function inserts @p c to @p buf. If it can not insert it, | ||
205 | * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. | ||
206 | */ | ||
207 | EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1); | ||
208 | |||
209 | /** | ||
210 | * @brief Append a string to a buffer, reallocating as necessary. | ||
211 | * | ||
212 | * @param buf The string buffer to append to. | ||
213 | * @param fmt The string to append. | ||
214 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
215 | * | ||
216 | * This function appends the string defined by the format @p fmt to @p buf. @p | ||
217 | * fmt must be of a valid format for printf family of functions. If it can't | ||
218 | * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. | ||
219 | * | ||
220 | * @see eina_strbuf_append() | ||
221 | */ | ||
222 | EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); | ||
223 | |||
224 | /** | ||
225 | * @brief Append a string to a buffer, reallocating as necessary. | ||
226 | * | ||
227 | * @param buf The string buffer to append to. | ||
228 | * @param fmt The string to append. | ||
229 | * @param args The variable arguments. | ||
230 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
231 | * | ||
232 | * @see eina_strbuf_append_printf() | ||
233 | */ | ||
234 | EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2); | ||
235 | |||
236 | /** | ||
237 | * @brief Insert a string to a buffer, reallocating as necessary. | ||
238 | * | ||
239 | * @param buf The string buffer to insert. | ||
240 | * @param str The string to insert. | ||
241 | * @param pos The position to insert the string. | ||
242 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
243 | * | ||
244 | * This function inserts @p str to @p buf at position @p pos. It | ||
245 | * computes the length of @p str, so is slightly slower than | ||
246 | * eina_strbuf_insert_length(). If the length is known beforehand, | ||
247 | * consider using that variant. If @p buf can't insert it, #EINA_FALSE | ||
248 | * is returned, otherwise #EINA_TRUE is returned. | ||
249 | */ | ||
250 | EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
251 | |||
252 | /** | ||
253 | * @brief Insert an escaped string to a buffer, reallocating as | ||
254 | * necessary. | ||
255 | * | ||
256 | * @param buf The string buffer to insert to. | ||
257 | * @param str The string to insert. | ||
258 | * @param pos The position to insert the string. | ||
259 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
260 | * | ||
261 | * This function escapes and inserts the string @p str to @p buf at | ||
262 | * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is | ||
263 | * returned, otherwise #EINA_TRUE is returned. | ||
264 | */ | ||
265 | EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
266 | |||
267 | /** | ||
268 | * @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen. | ||
269 | * | ||
270 | * @param buf The string buffer to insert to. | ||
271 | * @param str The string to insert. | ||
272 | * @param maxlen The maximum number of chars to insert. | ||
273 | * @param pos The position to insert the string. | ||
274 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
275 | * | ||
276 | * This function inserts @p str to @p buf at position @p pos, with at | ||
277 | * most @p maxlen bytes. The number of inserted characters can not be | ||
278 | * greater than the length of @p str. It computes the length of | ||
279 | * @p str, so is slightly slower than eina_strbuf_insert_length(). If the | ||
280 | * length is known beforehand, consider using that variant (@p maxlen | ||
281 | * should then be checked so that it is greater than the size of | ||
282 | * @p str). If @p str can not be inserted, #EINA_FALSE is returned, | ||
283 | * otherwise, #EINA_TRUE is returned. | ||
284 | */ | ||
285 | EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
286 | |||
287 | /** | ||
288 | * @brief Insert a string of exact length to a buffer, reallocating as necessary. | ||
289 | * | ||
290 | * @param buf The string buffer to insert to. | ||
291 | * @param str The string to insert. | ||
292 | * @param length The exact length to use. | ||
293 | * @param pos The position to insert the string. | ||
294 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
295 | * | ||
296 | * This function inserts @p str to @p buf. @p str must be of size at | ||
297 | * most @p length. It is slightly faster than eina_strbuf_insert() as | ||
298 | * it does not compute the size of @p str. It is useful when dealing | ||
299 | * with strings of known size, such as eina_strngshare. If @p buf | ||
300 | * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
301 | * returned. | ||
302 | * | ||
303 | * @see eina_stringshare_length() | ||
304 | * @see eina_strbuf_insert() | ||
305 | * @see eina_strbuf_insert_n() | ||
306 | */ | ||
307 | EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); | ||
308 | |||
309 | /** | ||
310 | * @brief Insert a character to a string buffer, reallocating as | ||
311 | * necessary. | ||
312 | * | ||
313 | * @param buf The string buffer to insert to. | ||
314 | * @param c The char to insert. | ||
315 | * @param pos The position to insert the char. | ||
316 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
317 | * | ||
318 | * This function inserts @p c to @p buf at position @p pos. If @p buf | ||
319 | * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
320 | * returned. | ||
321 | */ | ||
322 | EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1); | ||
323 | |||
324 | /** | ||
325 | * @brief Insert a string to a buffer, reallocating as necessary. | ||
326 | * | ||
327 | * @param buf The string buffer to insert. | ||
328 | * @param fmt The string to insert. | ||
329 | * @param pos The position to insert the string. | ||
330 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
331 | * | ||
332 | * This function insert a string as described by the format @p fmt to @p buf at | ||
333 | * the position @p pos. @p fmt must be of a valid format for printf family of | ||
334 | * functions. If it can't insert it, #EINA_FALSE is returned, otherwise | ||
335 | * #EINA_TRUE is returned. | ||
336 | */ | ||
337 | 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); | ||
338 | |||
339 | /** | ||
340 | * @brief Insert a string to a buffer, reallocating as necessary. | ||
341 | * | ||
342 | * @param buf The string buffer to insert. | ||
343 | * @param fmt The string to insert. | ||
344 | * @param pos The position to insert the string. | ||
345 | * @param args The variable arguments. | ||
346 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
347 | * | ||
348 | * @see eina_strbuf_insert_printf | ||
349 | */ | ||
350 | EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, size_t pos, va_list args) EINA_ARG_NONNULL(1, 2); | ||
351 | |||
352 | /** | ||
353 | * @def eina_strbuf_prepend(buf, str) | ||
354 | * @brief Prepend the given string to the given buffer | ||
355 | * | ||
356 | * @param buf The string buffer to prepend to. | ||
357 | * @param str The string to prepend. | ||
358 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
359 | * | ||
360 | * This macro is calling eina_strbuf_insert() at position 0. If @p buf | ||
361 | * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
362 | * returned. | ||
363 | */ | ||
364 | #define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf, str, 0) | ||
365 | |||
366 | /** | ||
367 | * @def eina_strbuf_prepend_escaped(buf, str) | ||
368 | * @brief Prepend the given escaped string to the given buffer | ||
369 | * | ||
370 | * @param buf The string buffer to prepend to. | ||
371 | * @param str The string to prepend. | ||
372 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
373 | * | ||
374 | * This macro is calling eina_strbuf_insert_escaped() at position 0. If | ||
375 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
376 | * #EINA_TRUE is returned. | ||
377 | */ | ||
378 | #define eina_strbuf_prepend_escaped(buf, str) eina_strbuf_insert_escaped(buf, str, 0) | ||
379 | |||
380 | /** | ||
381 | * @def eina_strbuf_prepend_n(buf, str) | ||
382 | * @brief Prepend the given escaped string to the given buffer | ||
383 | * | ||
384 | * @param buf The string buffer to prepend to. | ||
385 | * @param str The string to prepend. | ||
386 | * @param maxlen The maximum number of chars to prepend. | ||
387 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
388 | * | ||
389 | * This macro is calling eina_strbuf_insert_n() at position 0. If | ||
390 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
391 | * #EINA_TRUE is returned. | ||
392 | */ | ||
393 | #define eina_strbuf_prepend_n(buf, str, maxlen) eina_strbuf_insert_n(buf, str, maxlen, 0) | ||
394 | |||
395 | /** | ||
396 | * @def eina_strbuf_prepend_length(buf, str) | ||
397 | * @brief Prepend the given escaped string to the given buffer | ||
398 | * | ||
399 | * @param buf The string buffer to prepend to. | ||
400 | * @param str The string to prepend. | ||
401 | * @param length The exact length to use. | ||
402 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
403 | * | ||
404 | * This macro is calling eina_strbuf_insert_length() at position 0. If | ||
405 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
406 | * #EINA_TRUE is returned. | ||
407 | */ | ||
408 | #define eina_strbuf_prepend_length(buf, str, length) eina_strbuf_insert_length(buf, str, length, 0) | ||
409 | |||
410 | /** | ||
411 | * @def eina_strbuf_prepend_char(buf, str) | ||
412 | * @brief Prepend the given character to the given buffer | ||
413 | * | ||
414 | * @param buf The string buffer to prepend to. | ||
415 | * @param c The character to prepend. | ||
416 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
417 | * | ||
418 | * This macro is calling eina_strbuf_insert_char() at position 0. If | ||
419 | * @p buf can't prepend it, #EINA_FALSE is returned, otherwise | ||
420 | * #EINA_TRUE is returned. | ||
421 | */ | ||
422 | #define eina_strbuf_prepend_char(buf, c) eina_strbuf_insert_char(buf, c, 0) | ||
423 | |||
424 | /** | ||
425 | * @def eina_strbuf_prepend_printf(buf, fmt, ...) | ||
426 | * @brief Prepend the given string to the given buffer | ||
427 | * | ||
428 | * @param buf The string buffer to prepend to. | ||
429 | * @param fmt The string to prepend. | ||
430 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
431 | * | ||
432 | * This macro is calling eina_strbuf_insert_printf() at position 0.If @p buf | ||
433 | * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
434 | * returned. | ||
435 | */ | ||
436 | #define eina_strbuf_prepend_printf(buf, fmt, ...) eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__) | ||
437 | |||
438 | /** | ||
439 | * @def eina_strbuf_prepend_vprintf(buf, fmt, args) | ||
440 | * @brief Prepend the given string to the given buffer | ||
441 | * | ||
442 | * @param buf The string buffer to prepend to. | ||
443 | * @param fmt The string to prepend. | ||
444 | * @param args The variable arguments. | ||
445 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
446 | * | ||
447 | * This macro is calling eina_strbuf_insert_vprintf() at position 0.If @p buf | ||
448 | * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
449 | * returned. | ||
450 | */ | ||
451 | #define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args) | ||
452 | |||
453 | /** | ||
454 | * @brief Remove a slice of the given string buffer. | ||
455 | * | ||
456 | * @param buf The string buffer to remove a slice. | ||
457 | * @param start The initial (inclusive) slice position to start | ||
458 | * removing, in bytes. | ||
459 | * @param end The final (non-inclusive) slice position to finish | ||
460 | * removing, in bytes. | ||
461 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
462 | * | ||
463 | * This function removes a slice of @p buf, starting at @p start | ||
464 | * (inclusive) and ending at @p end (non-inclusive). Both values are | ||
465 | * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. | ||
466 | */ | ||
467 | |||
468 | EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); | ||
469 | |||
470 | /** | ||
471 | * @brief Retrieve a pointer to the contents of a string buffer | ||
472 | * | ||
473 | * @param buf The string buffer. | ||
474 | * @return The current string in the string buffer. | ||
475 | * | ||
476 | * This function returns the string contained in @p buf. The returned | ||
477 | * value must not be modified and will no longer be valid if @p buf is | ||
478 | * modified. In other words, any eina_strbuf_append() or similar will | ||
479 | * make that pointer invalid. The pointer returned by this function <b>must | ||
480 | * not</b> be freed. | ||
481 | * | ||
482 | * @see eina_strbuf_string_steal() | ||
483 | */ | ||
484 | EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
485 | |||
486 | /** | ||
487 | * @brief Steal the contents of a string buffer. | ||
488 | * | ||
489 | * @param buf The string buffer to steal. | ||
490 | * @return The current string in the string buffer. | ||
491 | * | ||
492 | * This function returns the string contained in @p buf. @p buf is | ||
493 | * then initialized and does not own the returned string anymore. The | ||
494 | * caller must release the memory of the returned string by calling | ||
495 | * free(). | ||
496 | * | ||
497 | * @see eina_strbuf_string_get() | ||
498 | */ | ||
499 | EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | ||
500 | |||
501 | /** | ||
502 | * @brief Free the contents of a string buffer but not the buffer. | ||
503 | * | ||
504 | * @param buf The string buffer to free the string of. | ||
505 | * | ||
506 | * This function frees the string contained in @p buf without freeing | ||
507 | * @p buf. | ||
508 | */ | ||
509 | EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
510 | |||
511 | /** | ||
512 | * @brief Retrieve the length of the string buffer content. | ||
513 | * | ||
514 | * @param buf The string buffer. | ||
515 | * @return The current length of the string, in bytes. | ||
516 | * | ||
517 | * This function returns the length of @p buf. | ||
518 | */ | ||
519 | EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
520 | |||
521 | |||
522 | /** | ||
523 | * @brief Replace the n-th string with an other string. | ||
524 | * | ||
525 | * @param buf The string buffer to work with. | ||
526 | * @param str The string to replace. | ||
527 | * @param with The replaceing string. | ||
528 | * @param n The number of the fitting string. | ||
529 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
530 | * | ||
531 | * This function replaces the n-th occurrence of @p str in @p buf with | ||
532 | * @p with. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. | ||
533 | */ | ||
534 | EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3); | ||
535 | |||
536 | /** | ||
537 | * @def eina_strbuf_replace_first(buf, str, with) | ||
538 | * @brief Prepend the given character to the given buffer | ||
539 | * | ||
540 | * @param buf The string buffer to work with. | ||
541 | * @param str The string to replace. | ||
542 | * @param with The replaceing string. | ||
543 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
544 | * | ||
545 | * This macro is calling eina_strbuf_replace() with the n-th occurrence | ||
546 | * equal to @c 1. If @p buf can't replace it, #EINA_FALSE is returned, | ||
547 | * otherwise #EINA_TRUE is returned. | ||
548 | */ | ||
549 | #define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf, str, with, 1) | ||
550 | |||
551 | |||
552 | /** | ||
553 | * @brief Replace all strings with an other string. | ||
554 | |||
555 | * @param buf the string buffer to work with. | ||
556 | * @param str The string to replace. | ||
557 | * @param with The replaceing string. | ||
558 | * @return How often the string was replaced. | ||
559 | * | ||
560 | * This function replaces all the occurrences of @p str in @p buf with | ||
561 | * the string @p with. This function returns the number of times @p str | ||
562 | * has been replaced. On failure, it returns 0. | ||
563 | */ | ||
564 | EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3); | ||
565 | |||
566 | /** | ||
567 | * @brief Trim the string buffer | ||
568 | |||
569 | * @param buf the string buffer to work with. | ||
570 | * | ||
571 | * This function skips whitespaces in the beginning and the end of the buffer. | ||
572 | */ | ||
573 | EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
574 | |||
575 | /** | ||
576 | * @brief Left trim the string buffer | ||
577 | |||
578 | * @param buf the string buffer to work with. | ||
579 | * | ||
580 | * This function skips whitespaces in the beginning of the buffer. | ||
581 | */ | ||
582 | EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
583 | |||
584 | /** | ||
585 | * @brief Right trim the string buffer | ||
586 | |||
587 | * @param buf the string buffer to work with. | ||
588 | * | ||
589 | * This function skips whitespaces in the end of the buffer. | ||
590 | */ | ||
591 | EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | ||
592 | |||
593 | /** | ||
594 | * @} | ||
595 | */ | ||
596 | |||
597 | /** | ||
598 | * @} | ||
599 | */ | ||
600 | |||
601 | /** | ||
602 | * @} | ||
603 | */ | ||
604 | |||
605 | #endif /* EINA_STRBUF_H */ | ||