aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_ustrbuf.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_ustrbuf.h')
-rw-r--r--libraries/eina/src/include/eina_ustrbuf.h464
1 files changed, 0 insertions, 464 deletions
diff --git a/libraries/eina/src/include/eina_ustrbuf.h b/libraries/eina/src/include/eina_ustrbuf.h
deleted file mode 100644
index 9710c42..0000000
--- a/libraries/eina/src/include/eina_ustrbuf.h
+++ /dev/null
@@ -1,464 +0,0 @@
1#ifndef EINA_USTRBUF_H
2#define EINA_USTRBUF_H
3
4#include <stddef.h>
5
6#include "eina_types.h"
7#include "eina_unicode.h"
8
9/**
10 * @addtogroup Eina_Unicode_String_Buffer_Group Unicode String Buffer
11 *
12 * @brief These functions provide unicode string buffers management.
13 *
14 * The Unicode String Buffer data type is designed to be a mutable string,
15 * allowing to append, prepend or insert a string to a buffer.
16 */
17
18/**
19 * @addtogroup Eina_Data_Types_Group Data Types
20 *
21 * @{
22 */
23
24/**
25 * @defgroup Eina_Unicode_String_Buffer_Group Unicode String Buffer
26 *
27 * @{
28 */
29
30/**
31 * @typedef Eina_UStrbuf
32 * Type for a string buffer.
33 */
34typedef struct _Eina_Strbuf Eina_UStrbuf;
35
36/**
37 * @brief Create a new string buffer.
38 *
39 * @return Newly allocated string buffer instance.
40 *
41 * This function creates a new string buffer. On error, @c NULL is
42 * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
43 * free the resources, use eina_ustrbuf_free().
44 *
45 * @see eina_ustrbuf_free()
46 * @see eina_ustrbuf_append()
47 * @see eina_ustrbuf_string_get()
48 */
49EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
50
51/**
52 * @brief Create a new string buffer using the passed string. The passed
53 * string is used directly as the buffer, it's somehow the opposite function of
54 * @ref eina_ustrbuf_string_steal . The passed string must be malloced.
55 *
56 * @param str the string to manage
57 * @return Newly allocated string buffer instance.
58 *
59 * This function creates a new string buffer. On error, @c NULL is
60 * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
61 * free the resources, use eina_strbuf_free().
62 *
63 * @see eina_ustrbuf_free()
64 * @see eina_ustrbuf_append()
65 * @see eina_ustrbuf_string_get()
66 * @since 1.1.0
67 */
68EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
69
70/**
71 * @brief Create a new string buffer using the passed string. The passed
72 * string is used directly as the buffer, it's somehow the opposite function of
73 * @ref eina_ustrbuf_string_steal . The passed string must be malloced.
74 *
75 * @param str the string to manage
76 * @param length the length of the string.
77 * @return Newly allocated string buffer instance.
78 *
79 * This function creates a new string buffer. On error, @c NULL is
80 * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
81 * free the resources, use eina_ustrbuf_free().
82 *
83 * @see eina_ustrbuf_manage_new()
84 * @since 1.2.0
85 */
86EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
87
88/**
89 * @brief Free a string buffer.
90 *
91 * @param buf The string buffer to free.
92 *
93 * This function frees the memory of @p buf. @p buf must have been
94 * created by eina_ustrbuf_new().
95 */
96EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
97
98/**
99 * @brief Reset a string buffer.
100 *
101 * @param buf The string buffer to reset.
102 *
103 * This function reset @p buf: the buffer len is set to 0, and the
104 * string is set to '\\0'. No memory is free'd.
105 */
106EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
107
108/**
109 * @brief Append a string to a buffer, reallocating as necessary.
110 *
111 * @param buf The string buffer to append to.
112 * @param str The string to append.
113 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
114 *
115 * This function appends @p str to @p buf. It computes the length of
116 * @p str, so is slightly slower than eina_ustrbuf_append_length(). If
117 * the length is known beforehand, consider using that variant. If
118 * @p buf can't append it, #EINA_FALSE is returned, otherwise
119 * #EINA_TRUE is returned.
120 *
121 * @see eina_ustrbuf_append()
122 * @see eina_ustrbuf_append_length()
123 */
124EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
125
126/**
127 * @brief Append an escaped string to a buffer, reallocating as necessary.
128 *
129 * @param buf The string buffer to append to.
130 * @param str The string to append.
131 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
132 *
133 * This function appends the escaped string @p str to @p buf. If @p
134 * str can not be appended, #EINA_FALSE is returned, otherwise,
135 * #EINA_TRUE is returned.
136 */
137EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
138
139/**
140 * @brief Append a string to a buffer, reallocating as necessary,
141 * limited by the given length.
142 *
143 * @param buf The string buffer to append to.
144 * @param str The string to append.
145 * @param maxlen The maximum number of characters to append.
146 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
147 *
148 * This function appends at most @p maxlen characters of @p str to
149 * @p buf. It can't appends more than the length of @p str. It
150 * computes the length of @p str, so is slightly slower than
151 * eina_ustrbuf_append_length(). If the length is known beforehand,
152 * consider using that variant (@p maxlen should then be checked so
153 * that it is greater than the size of @p str). If @p str can not be
154 * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
155 * returned.
156 *
157 * @see eina_ustrbuf_append()
158 * @see eina_ustrbuf_append_length()
159 */
160EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
161
162/**
163 * @brief Append a string of exact length to a buffer, reallocating as necessary.
164 *
165 * @param buf The string buffer to append to.
166 * @param str The string to append.
167 * @param length The exact length to use.
168 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
169 *
170 * This function appends @p str to @p buf. @p str must be of size at
171 * most @p length. It is slightly faster than eina_ustrbuf_append() as
172 * it does not compute the size of @p str. It is useful when dealing
173 * with strings of known size, such as eina_strngshare. If @p buf
174 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
175 * returned.
176 *
177 * @see eina_stringshare_length()
178 * @see eina_ustrbuf_append()
179 * @see eina_ustrbuf_append_n()
180 */
181EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) EINA_ARG_NONNULL(1, 2);
182
183/**
184 * @brief Append a character to a string buffer, reallocating as
185 * necessary.
186 *
187 * @param buf The string buffer to append to.
188 * @param c The char to append.
189 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
190 *
191 * This function inserts @p c to @p buf. If it can not insert it,
192 * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
193 */
194EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1);
195
196/**
197 * @brief Insert a string to a buffer, reallocating as necessary.
198 *
199 * @param buf The string buffer to insert.
200 * @param str The string to insert.
201 * @param pos The position to insert the string.
202 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
203 *
204 * This function inserts @p str to @p buf at position @p pos. It
205 * computes the length of @p str, so is slightly slower than
206 * eina_ustrbuf_insert_length(). If the length is known beforehand,
207 * consider using that variant. If @p buf can't insert it, #EINA_FALSE
208 * is returned, otherwise #EINA_TRUE is returned.
209 */
210EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
211
212/**
213 * @brief Insert an escaped string to a buffer, reallocating as
214 * necessary.
215 *
216 * @param buf The string buffer to insert to.
217 * @param str The string to insert.
218 * @param pos The position to insert the string.
219 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
220 *
221 * This function inserts the escaped string @p str to @p buf at
222 * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is
223 * returned, otherwise #EINA_TRUE is returned.
224 */
225EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
226
227/**
228 * @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen.
229 *
230 * @param buf The string buffer to insert to.
231 * @param str The string to insert.
232 * @param maxlen The maximum number of chars to insert.
233 * @param pos The position to insert the string.
234 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
235 *
236 * This function inserts @p str ot @p buf at position @p pos, with at
237 * most @p maxlen bytes. The number of inserted characters can not be
238 * greater than the length of @p str. It computes the length of
239 * @p str, so is slightly slower than eina_ustrbuf_insert_length(). If the
240 * length is known beforehand, consider using that variant (@p maxlen
241 * should then be checked so that it is greater than the size of
242 * @p str). If @p str can not be inserted, #EINA_FALSE is returned,
243 * otherwise, #EINA_TRUE is returned.
244 */
245EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
246
247/**
248 * @brief Insert a string of exact length to a buffer, reallocating as necessary.
249 *
250 * @param buf The string buffer to insert to.
251 * @param str The string to insert.
252 * @param length The exact length to use.
253 * @param pos The position to insert the string.
254 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
255 *
256 * This function inserts @p str to @p buf. @p str must be of size at
257 * most @p length. It is slightly faster than eina_ustrbuf_insert() as
258 * it does not compute the size of @p str. It is useful when dealing
259 * with strings of known size, such as eina_strngshare. If @p buf
260 * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
261 * returned.
262 *
263 * @see eina_stringshare_length()
264 * @see eina_ustrbuf_insert()
265 * @see eina_ustrbuf_insert_n()
266 */
267EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
268
269/**
270 * @brief Insert a character to a string buffer, reallocating as
271 * necessary.
272 *
273 * @param buf The string buffer to insert to.
274 * @param c The char to insert.
275 * @param pos The position to insert the char.
276 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
277 *
278 * This function inserts @p c to @p buf at position @p pos. If @p buf
279 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
280 * returned.
281 */
282EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_t pos) EINA_ARG_NONNULL(1);
283
284/**
285 * @def eina_ustrbuf_prepend(buf, str)
286 * @brief Prepend the given string to the given buffer
287 *
288 * @param buf The string buffer to prepend to.
289 * @param str The string to prepend.
290 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
291 *
292 * This macro is calling eina_ustrbuf_insert() at position 0.If @p buf
293 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
294 * returned.
295 */
296#define eina_ustrbuf_prepend(buf, str) eina_ustrbuf_insert(buf, str, 0)
297
298/**
299 * @def eina_ustrbuf_prepend_escaped(buf, str)
300 * @brief Prepend the given escaped string to the given buffer
301 *
302 * @param buf The string buffer to prepend to.
303 * @param str The string to prepend.
304 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
305 *
306 * This macro is calling eina_ustrbuf_insert_escaped() at position 0. If
307 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
308 * #EINA_TRUE is returned.
309 */
310#define eina_ustrbuf_prepend_escaped(buf, str) eina_ustrbuf_insert_escaped(buf, str, 0)
311
312/**
313 * @def eina_ustrbuf_prepend_n(buf, str)
314 * @brief Prepend the given escaped string to the given buffer
315 *
316 * @param buf The string buffer to prepend to.
317 * @param str The string to prepend.
318 * @param maxlen The maximum number of Eina_Unicode *s to prepend.
319 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
320 *
321 * This macro is calling eina_ustrbuf_insert_n() at position 0. If
322 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
323 * #EINA_TRUE is returned.
324 */
325#define eina_ustrbuf_prepend_n(buf, str, maxlen) eina_ustrbuf_insert_n(buf, str, maxlen, 0)
326
327/**
328 * @def eina_ustrbuf_prepend_length(buf, str)
329 * @brief Prepend the given escaped string to the given buffer
330 *
331 * @param buf The string buffer to prepend to.
332 * @param str The string to prepend.
333 * @param length The exact length to use.
334 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
335 *
336 * This macro is calling eina_ustrbuf_insert_length() at position 0. If
337 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
338 * #EINA_TRUE is returned.
339 */
340#define eina_ustrbuf_prepend_length(buf, str, length) eina_ustrbuf_insert_length(buf, str, length, 0)
341
342/**
343 * @def eina_ustrbuf_prepend_char(buf, c)
344 * @brief Prepend the given unicode character to the given buffer
345 *
346 * @param buf The string buffer to prepend to.
347 * @param c The Eina_Unicode character to prepend.
348 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
349 *
350 * This macro is calling eina_ustrbuf_insert_Eina_Unicode *() at position 0. If
351 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
352 * #EINA_TRUE is returned.
353 */
354#define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0)
355
356/**
357 * @def eina_ustrbuf_prepend_printf(buf, fmt, ...)
358 * @brief Prepend the given string to the given buffer
359 *
360 * @param buf The string buffer to prepend to.
361 * @param fmt The string to prepend.
362 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
363 *
364 * This macro is calling eina_ustrbuf_insert_printf() at position 0.If @p buf
365 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
366 * returned.
367 */
368#define eina_ustrbuf_prepend_printf(buf, fmt, ...) eina_ustrbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__)
369
370/**
371 * @def eina_ustrbuf_prepend_vprintf(buf, fmt, args)
372 * @brief Prepend the given string to the given buffer
373 *
374 * @param buf The string buffer to prepend to.
375 * @param fmt The string to prepend.
376 * @param args The variable arguments.
377 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
378 *
379 * This macro is calling eina_ustrbuf_insert_vprintf() at position 0.If @p buf
380 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
381 * returned.
382 */
383#define eina_ustrbuf_prepend_vprintf(buf, fmt, args) eina_ustrbuf_insert_vprintf(buf, fmt, 0, args)
384
385/**
386 * @brief Remove a slice of the given string buffer.
387 *
388 * @param buf The string buffer to remove a slice.
389 * @param start The initial (inclusive) slice position to start
390 * removing, in bytes.
391 * @param end The final (non-inclusive) slice position to finish
392 * removing, in bytes.
393 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
394 *
395 * This function removes a slice of @p buf, starting at @p start
396 * (inclusive) and ending at @p end (non-inclusive). Both values are
397 * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise.
398 */
399EAPI Eina_Bool
400eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
401
402/**
403 * @brief Retrieve a pointer to the contents of a string buffer
404 *
405 * @param buf The string buffer.
406 * @return The current string in the string buffer.
407 *
408 * This function returns the string contained in @p buf. The returned
409 * value must not be modified and will no longer be valid if @p buf is
410 * modified. In other words, any eina_ustrbuf_append() or similar will
411 * make that pointer invalid.
412 *
413 * @see eina_ustrbuf_string_steal()
414 */
415EAPI const Eina_Unicode *
416eina_ustrbuf_string_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
417
418/**
419 * @brief Steal the contents of a string buffer.
420 *
421 * @param buf The string buffer to steal.
422 * @return The current string in the string buffer.
423 *
424 * This function returns the string contained in @p buf. @p buf is
425 * then initialized and does not own the returned string anymore. The
426 * caller must release the memory of the returned string by calling
427 * free().
428 *
429 * @see eina_ustrbuf_string_get()
430 */
431EAPI Eina_Unicode *
432eina_ustrbuf_string_steal(Eina_UStrbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
433
434/**
435 * @brief Free the contents of a string buffer but not the buffer.
436 *
437 * @param buf The string buffer to free the string of.
438 *
439 * This function frees the string contained in @p buf without freeing
440 * @p buf.
441 */
442EAPI void
443eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
444
445/**
446 * @brief Retrieve the length of the string buffer content.
447 *
448 * @param buf The string buffer.
449 * @return The current length of the string, in bytes.
450 *
451 * This function returns the length of @p buf.
452 */
453EAPI size_t
454eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
455
456/**
457 * @}
458 */
459
460/**
461 * @}
462 */
463
464#endif /* EINA_STRBUF_H */