aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_ustrbuf.h
diff options
context:
space:
mode:
authorDavid Walter Seikel2012-01-04 18:41:13 +1000
committerDavid Walter Seikel2012-01-04 18:41:13 +1000
commitdd7595a3475407a7fa96a97393bae8c5220e8762 (patch)
treee341e911d7eb911a51684a7412ef7f7c7605d28e /libraries/eina/src/include/eina_ustrbuf.h
parentAdd the skeleton. (diff)
downloadSledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.zip
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.gz
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.bz2
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.xz
Add the base Enlightenment Foundation Libraries - eina, eet, evas, ecore, embryo, and edje.
Note that embryo wont be used, but I'm not sure yet if you can build edje without it.
Diffstat (limited to 'libraries/eina/src/include/eina_ustrbuf.h')
-rw-r--r--libraries/eina/src/include/eina_ustrbuf.h446
1 files changed, 446 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_ustrbuf.h b/libraries/eina/src/include/eina_ustrbuf.h
new file mode 100644
index 0000000..f68cb7b
--- /dev/null
+++ b/libraries/eina/src/include/eina_ustrbuf.h
@@ -0,0 +1,446 @@
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_Strbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
69
70/**
71 * @brief Free a string buffer.
72 *
73 * @param buf The string buffer to free.
74 *
75 * This function frees the memory of @p buf. @p buf must have been
76 * created by eina_ustrbuf_new().
77 */
78EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
79
80/**
81 * @brief Reset a string buffer.
82 *
83 * @param buf The string buffer to reset.
84 *
85 * This function reset @p buf: the buffer len is set to 0, and the
86 * string is set to '\\0'. No memory is free'd.
87 */
88EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
89
90/**
91 * @brief Append a string to a buffer, reallocating as necessary.
92 *
93 * @param buf The string buffer to append to.
94 * @param str The string to append.
95 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
96 *
97 * This function appends @p str to @p buf. It computes the length of
98 * @p str, so is slightly slower than eina_ustrbuf_append_length(). If
99 * the length is known beforehand, consider using that variant. If
100 * @p buf can't append it, #EINA_FALSE is returned, otherwise
101 * #EINA_TRUE is returned.
102 *
103 * @see eina_ustrbuf_append()
104 * @see eina_ustrbuf_append_length()
105 */
106EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
107
108/**
109 * @brief Append an escaped 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 the escaped string @p str to @p buf. If @p
116 * str can not be appended, #EINA_FALSE is returned, otherwise,
117 * #EINA_TRUE is returned.
118 */
119EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
120
121/**
122 * @brief Append a string to a buffer, reallocating as necessary,
123 * limited by the given length.
124 *
125 * @param buf The string buffer to append to.
126 * @param str The string to append.
127 * @param maxlen The maximum number of characters to append.
128 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
129 *
130 * This function appends at most @p maxlen characters of @p str to
131 * @p buf. It can't appends more than the length of @p str. It
132 * computes the length of @p str, so is slightly slower than
133 * eina_ustrbuf_append_length(). If the length is known beforehand,
134 * consider using that variant (@p maxlen should then be checked so
135 * that it is greater than the size of @p str). If @p str can not be
136 * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
137 * returned.
138 *
139 * @see eina_ustrbuf_append()
140 * @see eina_ustrbuf_append_length()
141 */
142EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
143
144/**
145 * @brief Append a string of exact length to a buffer, reallocating as necessary.
146 *
147 * @param buf The string buffer to append to.
148 * @param str The string to append.
149 * @param length The exact length to use.
150 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
151 *
152 * This function appends @p str to @p buf. @p str must be of size at
153 * most @p length. It is slightly faster than eina_ustrbuf_append() as
154 * it does not compute the size of @p str. It is useful when dealing
155 * with strings of known size, such as eina_strngshare. If @p buf
156 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
157 * returned.
158 *
159 * @see eina_stringshare_length()
160 * @see eina_ustrbuf_append()
161 * @see eina_ustrbuf_append_n()
162 */
163EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) EINA_ARG_NONNULL(1, 2);
164
165/**
166 * @brief Append a character to a string buffer, reallocating as
167 * necessary.
168 *
169 * @param buf The string buffer to append to.
170 * @param c The char to append.
171 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
172 *
173 * This function inserts @p c to @p buf. If it can not insert it,
174 * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
175 */
176EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1);
177
178/**
179 * @brief Insert a string to a buffer, reallocating as necessary.
180 *
181 * @param buf The string buffer to insert.
182 * @param str The string to insert.
183 * @param pos The position to insert the string.
184 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
185 *
186 * This function inserts @p str to @p buf at position @p pos. It
187 * computes the length of @p str, so is slightly slower than
188 * eina_ustrbuf_insert_length(). If the length is known beforehand,
189 * consider using that variant. If @p buf can't insert it, #EINA_FALSE
190 * is returned, otherwise #EINA_TRUE is returned.
191 */
192EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
193
194/**
195 * @brief Insert an escaped string to a buffer, reallocating as
196 * necessary.
197 *
198 * @param buf The string buffer to insert to.
199 * @param str The string to insert.
200 * @param pos The position to insert the string.
201 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
202 *
203 * This function inserts the escaped string @p str to @p buf at
204 * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is
205 * returned, otherwise #EINA_TRUE is returned.
206 */
207EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
208
209/**
210 * @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen.
211 *
212 * @param buf The string buffer to insert to.
213 * @param str The string to insert.
214 * @param maxlen The maximum number of chars to insert.
215 * @param pos The position to insert the string.
216 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
217 *
218 * This function inserts @p str ot @p buf at position @p pos, with at
219 * most @p maxlen bytes. The number of inserted characters can not be
220 * greater than the length of @p str. It computes the length of
221 * @p str, so is slightly slower than eina_ustrbuf_insert_length(). If the
222 * length is known beforehand, consider using that variant (@p maxlen
223 * should then be checked so that it is greater than the size of
224 * @p str). If @p str can not be inserted, #EINA_FALSE is returned,
225 * otherwise, #EINA_TRUE is returned.
226 */
227EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
228
229/**
230 * @brief Insert a string of exact length to a buffer, reallocating as necessary.
231 *
232 * @param buf The string buffer to insert to.
233 * @param str The string to insert.
234 * @param length The exact length to use.
235 * @param pos The position to insert the string.
236 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
237 *
238 * This function inserts @p str to @p buf. @p str must be of size at
239 * most @p length. It is slightly faster than eina_ustrbuf_insert() as
240 * it does not compute the size of @p str. It is useful when dealing
241 * with strings of known size, such as eina_strngshare. If @p buf
242 * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
243 * returned.
244 *
245 * @see eina_stringshare_length()
246 * @see eina_ustrbuf_insert()
247 * @see eina_ustrbuf_insert_n()
248 */
249EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
250
251/**
252 * @brief Insert a character to a string buffer, reallocating as
253 * necessary.
254 *
255 * @param buf The string buffer to insert to.
256 * @param c The char to insert.
257 * @param pos The position to insert the char.
258 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
259 *
260 * This function inserts @p c to @p buf at position @p pos. If @p buf
261 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
262 * returned.
263 */
264EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_t pos) EINA_ARG_NONNULL(1);
265
266/**
267 * @def eina_ustrbuf_prepend(buf, str)
268 * @brief Prepend the given string to the given buffer
269 *
270 * @param buf The string buffer to prepend to.
271 * @param str The string to prepend.
272 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
273 *
274 * This macro is calling eina_ustrbuf_insert() at position 0.If @p buf
275 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
276 * returned.
277 */
278#define eina_ustrbuf_prepend(buf, str) eina_ustrbuf_insert(buf, str, 0)
279
280/**
281 * @def eina_ustrbuf_prepend_escaped(buf, str)
282 * @brief Prepend the given escaped string to the given buffer
283 *
284 * @param buf The string buffer to prepend to.
285 * @param str The string to prepend.
286 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
287 *
288 * This macro is calling eina_ustrbuf_insert_escaped() at position 0. If
289 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
290 * #EINA_TRUE is returned.
291 */
292#define eina_ustrbuf_prepend_escaped(buf, str) eina_ustrbuf_insert_escaped(buf, str, 0)
293
294/**
295 * @def eina_ustrbuf_prepend_n(buf, str)
296 * @brief Prepend the given escaped string to the given buffer
297 *
298 * @param buf The string buffer to prepend to.
299 * @param str The string to prepend.
300 * @param maxlen The maximum number of Eina_Unicode *s to prepend.
301 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
302 *
303 * This macro is calling eina_ustrbuf_insert_n() at position 0. If
304 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
305 * #EINA_TRUE is returned.
306 */
307#define eina_ustrbuf_prepend_n(buf, str, maxlen) eina_ustrbuf_insert_n(buf, str, maxlen, 0)
308
309/**
310 * @def eina_ustrbuf_prepend_length(buf, str)
311 * @brief Prepend the given escaped string to the given buffer
312 *
313 * @param buf The string buffer to prepend to.
314 * @param str The string to prepend.
315 * @param length The exact length to use.
316 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
317 *
318 * This macro is calling eina_ustrbuf_insert_length() at position 0. If
319 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
320 * #EINA_TRUE is returned.
321 */
322#define eina_ustrbuf_prepend_length(buf, str, length) eina_ustrbuf_insert_length(buf, str, length, 0)
323
324/**
325 * @def eina_ustrbuf_prepend_char(buf, c)
326 * @brief Prepend the given unicode character to the given buffer
327 *
328 * @param buf The string buffer to prepend to.
329 * @param c The Eina_Unicode character to prepend.
330 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
331 *
332 * This macro is calling eina_ustrbuf_insert_Eina_Unicode *() at position 0. If
333 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise
334 * #EINA_TRUE is returned.
335 */
336#define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0)
337
338/**
339 * @def eina_ustrbuf_prepend_printf(buf, fmt, ...)
340 * @brief Prepend the given string to the given buffer
341 *
342 * @param buf The string buffer to prepend to.
343 * @param fmt The string to prepend.
344 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
345 *
346 * This macro is calling eina_ustrbuf_insert_printf() at position 0.If @p buf
347 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
348 * returned.
349 */
350#define eina_ustrbuf_prepend_printf(buf, fmt, ...) eina_ustrbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__)
351
352/**
353 * @def eina_ustrbuf_prepend_vprintf(buf, fmt, args)
354 * @brief Prepend the given string to the given buffer
355 *
356 * @param buf The string buffer to prepend to.
357 * @param fmt The string to prepend.
358 * @param args The variable arguments.
359 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
360 *
361 * This macro is calling eina_ustrbuf_insert_vprintf() at position 0.If @p buf
362 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
363 * returned.
364 */
365#define eina_ustrbuf_prepend_vprintf(buf, fmt, args) eina_ustrbuf_insert_vprintf(buf, fmt, 0, args)
366
367/**
368 * @brief Remove a slice of the given string buffer.
369 *
370 * @param buf The string buffer to remove a slice.
371 * @param start The initial (inclusive) slice position to start
372 * removing, in bytes.
373 * @param end The final (non-inclusive) slice position to finish
374 * removing, in bytes.
375 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
376 *
377 * This function removes a slice of @p buf, starting at @p start
378 * (inclusive) and ending at @p end (non-inclusive). Both values are
379 * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise.
380 */
381EAPI Eina_Bool
382eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
383
384/**
385 * @brief Retrieve a pointer to the contents of a string buffer
386 *
387 * @param buf The string buffer.
388 * @return The current string in the string buffer.
389 *
390 * This function returns the string contained in @p buf. The returned
391 * value must not be modified and will no longer be valid if @p buf is
392 * modified. In other words, any eina_ustrbuf_append() or similar will
393 * make that pointer invalid.
394 *
395 * @see eina_ustrbuf_string_steal()
396 */
397EAPI const Eina_Unicode *
398eina_ustrbuf_string_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
399
400/**
401 * @brief Steal the contents of a string buffer.
402 *
403 * @param buf The string buffer to steal.
404 * @return The current string in the string buffer.
405 *
406 * This function returns the string contained in @p buf. @p buf is
407 * then initialized and does not own the returned string anymore. The
408 * caller must release the memory of the returned string by calling
409 * free().
410 *
411 * @see eina_ustrbuf_string_get()
412 */
413EAPI Eina_Unicode *
414eina_ustrbuf_string_steal(Eina_UStrbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
415
416/**
417 * @brief Free the contents of a string buffer but not the buffer.
418 *
419 * @param buf The string buffer to free the string of.
420 *
421 * This function frees the string contained in @p buf without freeing
422 * @p buf.
423 */
424EAPI void
425eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
426
427/**
428 * @brief Retrieve the length of the string buffer content.
429 *
430 * @param buf The string buffer.
431 * @return The current length of the string, in bytes.
432 *
433 * This function returns the length of @p buf.
434 */
435EAPI size_t
436eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
437
438/**
439 * @}
440 */
441
442/**
443 * @}
444 */
445
446#endif /* EINA_STRBUF_H */