summaryrefslogtreecommitdiff
path: root/src/lib/eina
diff options
context:
space:
mode:
authorBryce Harrington <bryce@osg.samsung.com>2018-07-10 10:55:10 +0900
committerHermet Park <hermetpark@gmail.com>2018-07-10 10:55:10 +0900
commitd7c67febe1e773d52f7b792416cf39988ce0e1f5 (patch)
treec64c14c721ef17ade21e47b47acd5c6792d9a940 /src/lib/eina
parent7a538cbc4a6e2a63f3bd9ef858208ac2f813b002 (diff)
eina: Improve documentation for binbuf/strbuf/ustrbuf
Summary: These three classes have essentially the same API, just different underlying data types. This patch seeks to improve the docs for all three while retaining or improving the consistency between them. Several functions had completely incorrect documentation (looks like cut-and-paste mistakes), others had missing or incorrectly named parameter documentation, typographical errors, or other similar issues. This also cleans up a lot of spelling and grammar errors, defines return values as part of @return, and reformats/revises doxygen code for consistency. There are no changes to code, except some whitespace cleanup. Reviewers: devilhorns Subscribers: cedric, #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6544
Diffstat (limited to 'src/lib/eina')
-rw-r--r--src/lib/eina/eina_binbuf.h192
-rw-r--r--src/lib/eina/eina_strbuf.h500
-rw-r--r--src/lib/eina/eina_ustrbuf.h247
3 files changed, 443 insertions, 496 deletions
diff --git a/src/lib/eina/eina_binbuf.h b/src/lib/eina/eina_binbuf.h
index 27da52351a..f9e688d5e0 100644
--- a/src/lib/eina/eina_binbuf.h
+++ b/src/lib/eina/eina_binbuf.h
@@ -13,7 +13,8 @@
13 * @brief These functions provide string buffer management. 13 * @brief These functions provide string buffer management.
14 * 14 *
15 * The Binary Buffer data type is designed to be a mutable string, 15 * The Binary Buffer data type is designed to be a mutable string,
16 * allowing to append, prepend or insert a string to a buffer. 16 * allowing the appending, prepending or insertion of a string to a
17 * buffer.
17 */ 18 */
18 19
19/** 20/**
@@ -30,12 +31,12 @@
30 31
31/** 32/**
32 * @typedef Eina_Binbuf 33 * @typedef Eina_Binbuf
33 * Type for a string buffer. 34 * Type for a binary string buffer.
34 */ 35 */
35typedef struct _Eina_Strbuf Eina_Binbuf; 36typedef struct _Eina_Strbuf Eina_Binbuf;
36 37
37/** 38/**
38 * @brief Creates a new string buffer. 39 * @brief Creates a new binary string buffer.
39 * 40 *
40 * @return Newly allocated string buffer instance, or @c NULL on error. 41 * @return Newly allocated string buffer instance, or @c NULL on error.
41 * 42 *
@@ -49,61 +50,63 @@ typedef struct _Eina_Strbuf Eina_Binbuf;
49EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 50EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
50 51
51/** 52/**
52 * @brief Creates a new string buffer using the passed string. The passed 53 * @brief Creates a new string buffer using the passed string.
53 * string is used directly as the buffer, it's somehow the opposite function of
54 * @ref eina_binbuf_string_steal . The passed string must be malloced.
55 * 54 *
56 * @param str The string to manage. 55 * @param str The string to manage.
57 * @param length The length of the string. 56 * @param length The length of the string.
57 * @param ro The passed string will not be touched if set to #EINA_TRUE.
58 * @return Newly allocated string buffer instance, or @c NULL on error. 58 * @return Newly allocated string buffer instance, or @c NULL on error.
59 * 59 *
60 * This function creates a new string buffer. To free the resources, use 60 * This function creates a new binary string buffer. The passed string
61 * is used directly as the buffer, it's effectively the inverse of
62 * eina_binbuf_string_steal(). To free the resources, use
61 * eina_binbuf_free(). 63 * eina_binbuf_free().
62 * 64 *
65 * This routine will not touch the buffer if @p ro is set to
66 * #EINA_TRUE, but it will also not copy it. If @p ro is set to
67 * #EINA_TRUE any change operation will create a fresh new memory
68 * buffer, copy the old data there and modify that one instead.
69 *
63 * @see eina_binbuf_manage_new() 70 * @see eina_binbuf_manage_new()
64 * @since 1.2.0 71 * @see eina_binbuf_manage_new_length()
72 * @see eina_binbuf_manage_read_only_new_length()
73 *
74 * @since 1.14.0
65 */ 75 */
66EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED; 76EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length, Eina_Bool ro) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
67 77
68/** 78/**
69 * @brief Creates a new string buffer using the passed string. The passed 79 * @brief Creates a new string buffer using the passed string.
70 * string is used directly as the buffer, it's somehow the opposite function of
71 * @ref eina_binbuf_string_steal .
72 * 80 *
73 * @param str The string to start from. 81 * @param str The string to manage.
74 * @param length The length of the string. 82 * @param length The length of the string.
75 * @param ro The passed string will not be touched if set to EINA_TRUE.
76 * @return Newly allocated string buffer instance, or @c NULL on error. 83 * @return Newly allocated string buffer instance, or @c NULL on error.
77 * 84 *
78 * This function creates a new string buffer. To free the resources, use 85 * This function creates a new string buffer. To free the resources, use
79 * eina_binbuf_free(). It will not touch the buffer if ro is set to @c 86 * eina_binbuf_free().
80 * EINA_TRUE, but it will also not copy it. If ro is set to @c EINA_TRUE
81 * any change operation will create a fresh new memory, copy old data
82 * there and starting modifying that one.
83 * 87 *
84 * @see eina_binbuf_manage_new() 88 * @see eina_binbuf_manage_new()
85 * @see eina_binbuf_manage_new_length()
86 * @see eina_binbuf_manage_read_only_new_length()
87 * 89 *
88 * @since 1.14.0 90 * @since 1.2.0
89 */ 91 */
90EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length, Eina_Bool ro) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 92EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED;
91 93
92/** 94/**
93 * @brief Creates a new string buffer using the passed string. The passed 95 * @brief Creates a new string buffer using the passed string.
94 * string is used directly as the buffer, it's somehow the opposite function of
95 * @ref eina_binbuf_string_steal . The passed string will not be touched.
96 * 96 *
97 * @param str The string to start from. 97 * @param str The string to start from.
98 * @param length The length of the string. 98 * @param length The length of the string.
99 * @return Newly allocated string buffer instance, or @c NULL on error. 99 * @return Newly allocated string buffer instance, or @c NULL on error.
100 * 100 *
101 * This function creates a new string buffer. To free the resources, use 101 * This function creates a new string buffer. The passed string is used
102 * eina_binbuf_free(). It will not touch the internal buffer. Any 102 * directly as the buffer, it's effectively the inverse of
103 * changing operation will create a fresh new memory, copy old data 103 * eina_binbuf_string_steal(). The passed string will not be touched.
104 * there and starting modifying that one. 104 * It will not touch the internal buffer. Any changing operation will
105 * create a fresh new memory, copy old data there and starting modifying
106 * that one. To free the resources, use eina_binbuf_free().
105 * 107 *
106 * @see eina_binbuf_manage_new() 108 * @see eina_binbuf_manage_new()
109 *
107 * @since 1.9.0 110 * @since 1.9.0
108 */ 111 */
109EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED; 112EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED;
@@ -121,7 +124,7 @@ EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
121/** 124/**
122 * @brief Resets a string buffer. 125 * @brief Resets a string buffer.
123 * 126 *
124 * @param buf The string buffer to reset. 127 * @param buf The string buffer.
125 * 128 *
126 * This function resets @p buf: the buffer len is set to 0, and the 129 * This function resets @p buf: the buffer len is set to 0, and the
127 * string is set to '\\0'. No memory is freed. 130 * string is set to '\\0'. No memory is freed.
@@ -129,28 +132,27 @@ EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
129EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); 132EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
130 133
131/** 134/**
132 * @brief Expands a buffer, making room for at least @a minimum_unused_space. 135 * @brief Expands a buffer, making room for at least @p minimum_unused_space.
133 *
134 * One of the properties of the buffer is that it may overallocate
135 * space, thus it may have more than eina_binbuf_length_get() bytes
136 * allocated. How much depends on buffer growing logic, but this
137 * function allows one to request a minimum amount of bytes to be
138 * allocated at the end of the buffer.
139 *
140 * This is particularly useful to write directly to buffer's memory
141 * (ie: a call to read(2)). After the bytes are used call
142 * eina_binbuf_use() to mark them as such, so eina_binbuf_length_get()
143 * will consider the new bytes.
144 * 136 *
145 * @param buf The Buffer to expand. 137 * @param buf The Buffer to expand.
146 * @param minimum_unused_space The minimum unused allocated space, in 138 * @param minimum_unused_space The minimum unused allocated space, in
147 * bytes, at the end of the buffer. Zero can be used to query 139 * bytes, at the end of the buffer. Zero can be used to query
148 * the available slice of unused bytes. 140 * the available slice of unused bytes.
149 *
150 * @return The slice of unused bytes. The slice length may be zero if 141 * @return The slice of unused bytes. The slice length may be zero if
151 * @a minimum_unused_space couldn't be allocated, otherwise it 142 * @p minimum_unused_space couldn't be allocated, otherwise it will
152 * will be at least @a minimum_unused_space. After bytes are used, 143 * be at least @p minimum_unused_space. After bytes are used, mark
153 * mark them as such using eina_binbuf_use(). 144 * them as such using eina_binbuf_use().
145 *
146 * One of the properties of the buffer is that it may overallocate
147 * space, thus it may have more than eina_binbuf_length_get() bytes
148 * allocated. How much depends on the buffer growth logic, but this
149 * function allows requesting a minimum amount of bytes to be allocated
150 * at the end of the buffer.
151 *
152 * This is particularly useful to write directly to buffer's memory
153 * (i.e.: a call to read(2)). After the bytes are used call
154 * eina_binbuf_use() to mark them as such, so eina_binbuf_length_get()
155 * will account for the new bytes.
154 * 156 *
155 * @see eina_binbuf_rw_slice_get() 157 * @see eina_binbuf_rw_slice_get()
156 * @see eina_binbuf_use() 158 * @see eina_binbuf_use()
@@ -162,17 +164,16 @@ EAPI Eina_Rw_Slice eina_binbuf_expand(Eina_Binbuf *buf, size_t minimum_unused_sp
162/** 164/**
163 * @brief Marks more bytes as used. 165 * @brief Marks more bytes as used.
164 * 166 *
165 * This function should be used after eina_binbuf_expand(), marking
166 * the extra bytes returned there as used, then they will be
167 * considered in all other functions, such as eina_binbuf_length_get().
168 *
169 * @param buf The buffer to mark extra bytes as used. 167 * @param buf The buffer to mark extra bytes as used.
170 * @param extra_bytes the number of bytes to be considered used, must 168 * @param extra_bytes the number of bytes to be considered used, must
171 * be between zero and the length of the slice returned by 169 * be between zero and the length of the slice returned by
172 * eina_binbuf_expand(). 170 * eina_binbuf_expand().
171 * @return #EINA_TRUE on success, #EINA_FALSE on failure, such as
172 * @p extra_bytes is too big or @a buf is NULL.
173 * 173 *
174 * @return #EINA_TRUE on success, #EINA_FALSE on failure, such as @a 174 * This function should be used after eina_binbuf_expand(), marking
175 * extra_bytes is too big or @a buf is NULL. 175 * the extra bytes returned there as used, then they will be
176 * taken into account by other functions, such as eina_binbuf_length_get().
176 * 177 *
177 * @see eina_binbuf_expand() 178 * @see eina_binbuf_expand()
178 * 179 *
@@ -181,13 +182,13 @@ EAPI Eina_Rw_Slice eina_binbuf_expand(Eina_Binbuf *buf, size_t minimum_unused_sp
181EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NONNULL(1); 182EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NONNULL(1);
182 183
183/** 184/**
184 * @brief Appends a string of exact length to a buffer, reallocating as necessary. 185 * @brief Appends a string of exact length to a buffer, reallocating as
186 * necessary.
185 * 187 *
186 * @param buf The string buffer to append to. 188 * @param buf The string buffer.
187 * @param str The string to append. 189 * @param str The string to append.
188 * @param length The exact length to use. 190 * @param length The exact length to use.
189 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if @p 191 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be appended.
190 * buf can't be appended.
191 * 192 *
192 * This function appends @p str to @p buf. @p str must be of size at 193 * This function appends @p str to @p buf. @p str must be of size at
193 * most @p length. It is slightly faster than eina_binbuf_append() as 194 * most @p length. It is slightly faster than eina_binbuf_append() as
@@ -203,10 +204,9 @@ EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *
203/** 204/**
204 * @brief Appends a slice to a buffer, reallocating as necessary. 205 * @brief Appends a slice to a buffer, reallocating as necessary.
205 * 206 *
206 * @param buf The string buffer to append to. 207 * @param buf The string buffer.
207 * @param slice The slice to append. 208 * @param slice The slice to append.
208 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if 209 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be appended.
209 * @p buf can't be appended.
210 * 210 *
211 * This function appends @p slice to @p buf. 211 * This function appends @p slice to @p buf.
212 * 212 *
@@ -217,18 +217,18 @@ EAPI Eina_Bool eina_binbuf_append_slice(Eina_Binbuf *buf, const Eina_Slice slice
217/** 217/**
218 * @brief Appends an Eina_Binbuf to a buffer, reallocating as necessary. 218 * @brief Appends an Eina_Binbuf to a buffer, reallocating as necessary.
219 * 219 *
220 * @param buf The string buffer to append to. 220 * @param buf The string buffer.
221 * @param data The string buffer to append. 221 * @param data The string buffer to append.
222 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if @p 222 * @return #EINA_TRUE on success, #EINA_FALSE if @p data could not be appended.
223 * buf can't be appended.
224 * 223 *
225 * This function appends @p data to @p buf. @p data must be allocated and 224 * This function appends @p data to @p buf. @p data must be allocated and
226 * different from @c NULL. It is slightly faster than eina_binbuf_append() as 225 * different from @c NULL. It is slightly faster than eina_binbuf_append() as
227 * it does not compute the size of @p str. 226 * it does not compute the size of @p data.
228 * 227 *
229 * @see eina_binbuf_append() 228 * @see eina_binbuf_append()
230 * @see eina_binbuf_append_n() 229 * @see eina_binbuf_append_n()
231 * @see eina_binbuf_append_length() 230 * @see eina_binbuf_append_length()
231 *
232 * @since 1.9.0 232 * @since 1.9.0
233 */ 233 */
234EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *data) EINA_ARG_NONNULL(1, 2); 234EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *data) EINA_ARG_NONNULL(1, 2);
@@ -237,25 +237,25 @@ EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *da
237 * @brief Appends a character to a string buffer, reallocating as 237 * @brief Appends a character to a string buffer, reallocating as
238 * necessary. 238 * necessary.
239 * 239 *
240 * @param buf The string buffer to append to. 240 * @param buf The string buffer.
241 * @param c The char to append. 241 * @param c The char to append.
242 * @return #EINA_TRUE on success, #EINA_FALSE if @pc could not be inserted. 242 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be inserted.
243 * 243 *
244 * This function inserts @p c to @p buf. 244 * This function appends @p c to @p buf.
245 */ 245 */
246EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1); 246EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1);
247 247
248/** 248/**
249 * @brief Inserts a string of exact length to a buffer, reallocating as necessary. 249 * @brief Inserts a string of exact length into a buffer, reallocating as necessary.
250 * 250 *
251 * @param buf The string buffer to insert to. 251 * @param buf The string buffer.
252 * @param str The string to insert. 252 * @param str The string to insert.
253 * @param length The exact length to use. 253 * @param length The exact length to use.
254 * @param pos The position to insert the string. 254 * @param pos The position to insert the string.
255 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted. 255 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
256 * 256 *
257 * This function inserts @p str to @p buf. @p str must be of size at 257 * This function inserts @p str into @p buf. @p str must be no longer
258 * most @p length. It is slightly faster than eina_binbuf_insert() as 258 * than @p length. It is slightly faster than eina_binbuf_insert() as
259 * it does not compute the size of @p str. It is useful when dealing 259 * it does not compute the size of @p str. It is useful when dealing
260 * with strings of known size, such as eina_stringshare. 260 * with strings of known size, such as eina_stringshare.
261 * 261 *
@@ -266,24 +266,24 @@ EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_A
266EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); 266EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
267 267
268/** 268/**
269 * @brief Inserts a slice to a buffer, reallocating as necessary. 269 * @brief Inserts a slice into a buffer, reallocating as necessary.
270 * 270 *
271 * @param buf The string buffer to insert to. 271 * @param buf The string buffer.
272 * @param slice The slice to insert. 272 * @param slice The slice to insert.
273 * @param pos The position to insert the string. 273 * @param pos The position to insert the string.
274 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be inserted. 274 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be inserted.
275 * 275 *
276 * This function inserts @p slice to @p buf at position @p pos. 276 * This function inserts @p slice into @p buf at position @p pos.
277 * 277 *
278 * @since 1.19.0 278 * @since 1.19.0
279 */ 279 */
280EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1); 280EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
281 281
282/** 282/**
283 * @brief Inserts a character to a string buffer, reallocating as 283 * @brief Inserts a character into a string buffer, reallocating as
284 * necessary. 284 * necessary.
285 * 285 *
286 * @param buf The string buffer to insert to. 286 * @param buf The string buffer.
287 * @param c The char to insert. 287 * @param c The char to insert.
288 * @param pos The position to insert the char. 288 * @param pos The position to insert the char.
289 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be inserted. 289 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be inserted.
@@ -295,7 +295,7 @@ EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t
295/** 295/**
296 * @brief Removes a slice of the given string buffer. 296 * @brief Removes a slice of the given string buffer.
297 * 297 *
298 * @param buf The string buffer to remove a slice. 298 * @param buf The string buffer.
299 * @param start The initial (inclusive) slice position to start 299 * @param start The initial (inclusive) slice position to start
300 * removing, in bytes. 300 * removing, in bytes.
301 * @param end The final (non-inclusive) slice position to finish 301 * @param end The final (non-inclusive) slice position to finish
@@ -306,7 +306,6 @@ EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t
306 * (inclusive) and ending at @p end (non-inclusive). Both values are 306 * (inclusive) and ending at @p end (non-inclusive). Both values are
307 * in bytes. 307 * in bytes.
308 */ 308 */
309
310EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); 309EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
311 310
312/** 311/**
@@ -317,8 +316,8 @@ EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EI
317 * 316 *
318 * This function returns the string contained in @p buf. The returned 317 * This function returns the string contained in @p buf. The returned
319 * value must not be modified and will no longer be valid if @p buf is 318 * value must not be modified and will no longer be valid if @p buf is
320 * modified. In other words, any eina_binbuf_append() or similar will 319 * modified. In other words, calling eina_binbuf_append() or similar
321 * make the pointer invalid. 320 * functions will make the pointer invalid.
322 * 321 *
323 * @see eina_binbuf_string_steal() 322 * @see eina_binbuf_string_steal()
324 */ 323 */
@@ -342,7 +341,7 @@ EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_
342/** 341/**
343 * @brief Frees the contents of a string buffer but not the buffer. 342 * @brief Frees the contents of a string buffer but not the buffer.
344 * 343 *
345 * @param buf The string buffer to free the string of. 344 * @param buf The string buffer.
346 * 345 *
347 * This function frees the string contained in @p buf without freeing 346 * This function frees the string contained in @p buf without freeing
348 * @p buf. 347 * @p buf.
@@ -350,33 +349,33 @@ EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_
350EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); 349EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
351 350
352/** 351/**
353 * @brief Retrieves the length of the string buffer content. 352 * @brief Retrieves the length of the string buffer's content.
354 * 353 *
355 * @param buf The string buffer. 354 * @param buf The string buffer.
356 * @return The current length of the string, in bytes. 355 * @return The current length of the string, in bytes.
357 * 356 *
358 * This function returns the length of @p buf. 357 * This function returns the length of @p buf.
359 */ 358 */
360EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 359EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
361 360
362/** 361/**
363 * @brief Gets a read-only slice representing the current binbuf contents. 362 * @brief Gets a read-only slice of the buffer contents.
364 * 363 *
365 * @param buf the src buffer. 364 * @param buf The string buffer.
366 * @return a read-only slice for the current contents. It may become 365 * @return A read-only slice of the current contents. It may become
367 * invalid as soon as the @a buf is changed. 366 * invalid as soon as @p buf is changed.
368 * 367 *
369 * @since 1.19 368 * @since 1.19
370 */ 369 */
371EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 370EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
372 371
373/** 372/**
374 * @brief Gets a read-write slice representing the current binbuf contents. 373 * @brief Gets a read-write slice of the buffer contents.
375 * 374 *
376 * @param buf the src buffer. 375 * @param buf The string buffer.
377 * @return a read-write slice for the current contents. It may become 376 * @return A read-write slice for the current contents. It may become
378 * invalid as soon as the @a buf is changed with calls such as 377 * invalid as soon as @p buf is changed, such as through calls like
379 * eina_binbuf_append(), eina_binbuf_remove() 378 * eina_binbuf_append() or eina_binbuf_remove().
380 * 379 *
381 * @see eina_binbuf_expand() 380 * @see eina_binbuf_expand()
382 * 381 *
@@ -385,14 +384,11 @@ EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_R
385EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 384EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
386 385
387/** 386/**
388 * @brief Gets the content of the buffer and frees the buffer. 387 * @brief Frees the buffer, returning its old contents.
389 *
390 * @param buf the buffer to get the content from and which will be freed
391 * 388 *
392 * @return The content contained by buf. 389 * @param buf The string buffer.
393 * 390 * @return The content contained by buf. The caller must release the
394 * The caller must release the memory of the returned content by calling 391 * memory of the returned string by calling free().
395 * free().
396 * 392 *
397 * @since 1.19 393 * @since 1.19
398 */ 394 */
diff --git a/src/lib/eina/eina_strbuf.h b/src/lib/eina/eina_strbuf.h
index a0b77af8fe..27552318c2 100644
--- a/src/lib/eina/eina_strbuf.h
+++ b/src/lib/eina/eina_strbuf.h
@@ -36,13 +36,15 @@
36 * 36 *
37 * @example eina_strbuf_01.c 37 * @example eina_strbuf_01.c
38 */ 38 */
39
39/** 40/**
40 * @addtogroup Eina_String_Buffer_Group String Buffer 41 * @addtogroup Eina_String_Buffer_Group String Buffer
41 * 42 *
42 * @brief These functions provide string buffers management. 43 * @brief These functions provide string buffer management.
43 * 44 *
44 * The String Buffer data type is designed to be a mutable string, 45 * The String Buffer data type is designed to be a mutable string,
45 * allowing to append, prepend or insert a string to a buffer. 46 * allowing the appending, prepending or insertion of a string to a
47 * buffer.
46 * 48 *
47 * For more information see @ref tutorial_strbuf "this example". 49 * For more information see @ref tutorial_strbuf "this example".
48 */ 50 */
@@ -68,10 +70,10 @@ typedef struct _Eina_Strbuf Eina_Strbuf;
68/** 70/**
69 * @brief Creates a new string buffer. 71 * @brief Creates a new string buffer.
70 * 72 *
71 * @return Newly allocated string buffer instance. 73 * @return Newly allocated string buffer instance, or @c NULL on error.
72 * 74 *
73 * This function creates a new string buffer. On error, @c NULL is 75 * This function creates a new string buffer. To free the resources, use
74 * returned. To free the resources, use eina_strbuf_free(). 76 * eina_strbuf_free().
75 * 77 *
76 * @see eina_strbuf_free() 78 * @see eina_strbuf_free()
77 * @see eina_strbuf_append() 79 * @see eina_strbuf_append()
@@ -80,56 +82,59 @@ typedef struct _Eina_Strbuf Eina_Strbuf;
80EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 82EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
81 83
82/** 84/**
83 * @brief Creates a new string buffer using the passed string. The passed 85 * @brief Creates a new string buffer using the passed string.
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 malloc'd.
86 * 86 *
87 * @param str The string to manage 87 * @param str The string to manage.
88 * @return Newly allocated string buffer instance. 88 * @return Newly allocated string buffer instance, or @c NULL on error.
89 * 89 *
90 * This function creates a new string buffer. On error, @c NULL is 90 * This function creates a new string buffer. The passed string is used
91 * returned. To free the resources, use eina_strbuf_free(). 91 * directly as the buffer, it's effectively the inverse of
92 * eina_strbuf_string_steal(). The passed string must be malloc'd.
93 * To free the resources, use eina_strbuf_free().
92 * 94 *
93 * @see eina_strbuf_free() 95 * @see eina_strbuf_free()
94 * @see eina_strbuf_append() 96 * @see eina_strbuf_append()
95 * @see eina_strbuf_string_get() 97 * @see eina_strbuf_string_get()
98 *
96 * @since 1.1.0 99 * @since 1.1.0
97 */ 100 */
98EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 101EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
99 102
100/** 103/**
101 * @brief Creates a new string buffer using the passed string. The passed 104 * @brief Creates a new string buffer using the passed string.
102 * string is used directly as the buffer, it's somehow the opposite function of
103 * @ref eina_strbuf_string_steal . The passed string must be malloc'd.
104 * 105 *
105 * @param str The string to manage 106 * @param str The string to manage.
106 * @param length The length of the string. 107 * @param length The length of the string.
107 * @return Newly allocated string buffer instance. 108 * @return Newly allocated string buffer instance, or @c NULL on error.
108 * 109 *
109 * This function creates a new string buffer. On error, @c NULL is 110 * This function creates a new string buffer. The passed string is used
110 * returned. To free the resources, use eina_strbuf_free(). 111 * directly as the buffer, it's effectively the inverse of
112 * eina_strbuf_string_steal(). The passed string must be malloc'd. To
113 * free the resources, use eina_strbuf_free().
111 * 114 *
112 * @see eina_strbuf_manage_new() 115 * @see eina_strbuf_manage_new()
116 *
113 * @since 1.2.0 117 * @since 1.2.0
114 */ 118 */
115EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 119EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
116 120
117/** 121/**
118 * @brief Creates a new string buffer using the passed string. The passed 122 * @brief Creates a new string buffer using the passed string.
119 * string is used directly as the buffer, it's somehow the opposite function of
120 * @ref eina_strbuf_string_steal . The passed string is expected to be static or
121 * otherwise on the stack rather than the malloc'd string required by
122 * @ref eina_strbuf_manage_new_length .
123 * 123 *
124 * @param str The string to manage 124 * @param str The string to manage.
125 * @param length The length of the string. 125 * @param length The length of the string.
126 * @return Newly allocated string buffer instance. 126 * @return Newly allocated string buffer instance, or @c NULL on error.
127 * 127 *
128 * This function creates a new string buffer. On error, @c NULL is 128 * This function creates a new string buffer. The passed string is used
129 * returned. To free the resources, use eina_strbuf_free(). 129 * directly as the buffer, it's effectively the inverse of
130 * eina_strbuf_string_steal(). The passed string is expected to be static
131 * or otherwise on the stack rather than the malloc'd string required by
132 * eina_strbuf_manage_new_length(). To free the resources, use
133 * eina_strbuf_free().
130 * 134 *
131 * @see eina_strbuf_manage_new() 135 * @see eina_strbuf_manage_new()
132 * @see eina_strbuf_manage_new_length() 136 * @see eina_strbuf_manage_new_length()
137 *
133 * @since 1.9.0 138 * @since 1.9.0
134 */ 139 */
135EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 140EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
@@ -147,25 +152,24 @@ EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
147/** 152/**
148 * @brief Resets a string buffer. 153 * @brief Resets a string buffer.
149 * 154 *
150 * @param buf The string buffer to reset. 155 * @param buf The string buffer.
151 * 156 *
152 * This function reset @p buf: the buffer len is set to 0, and the 157 * This function resets @p buf: the buffer len is set to 0, and the
153 * string is set to '\\0'. No memory is free'd. 158 * string data is set to '\\0'. No memory is freed.
154 */ 159 */
155EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); 160EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
156 161
157/** 162/**
158 * @brief Appends a string to a buffer, reallocating as necessary. 163 * @brief Appends a string to a buffer, reallocating as necessary.
159 * 164 *
160 * @param buf The string buffer to append to. 165 * @param buf The string buffer.
161 * @param str The string to append. 166 * @param str The string to append.
162 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 167 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if
168 * @p str could not be appended.
163 * 169 *
164 * This function appends @p str to @p buf. It computes the length of 170 * This function appends @p str to @p buf. It computes the length of
165 * @p str, so is slightly slower than eina_strbuf_append_length(). If 171 * @p str, so is slightly slower than eina_strbuf_append_length(). If
166 * the length is known beforehand, consider using that variant. If 172 * the length is known beforehand, consider using that variant.
167 * @p buf can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
168 * returned.
169 * 173 *
170 * @see eina_strbuf_append() 174 * @see eina_strbuf_append()
171 * @see eina_strbuf_append_length() 175 * @see eina_strbuf_append_length()
@@ -175,13 +179,11 @@ EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NO
175/** 179/**
176 * @brief Appends an escaped string to a buffer, reallocating as necessary. 180 * @brief Appends an escaped string to a buffer, reallocating as necessary.
177 * 181 *
178 * @param buf The string buffer to append to. 182 * @param buf The string buffer.
179 * @param str The string to append. 183 * @param str The string to append.
180 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 184 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be appended.
181 * 185 *
182 * This function escapes and then appends the string @p str to @p buf. If @p str 186 * This function escapes and then appends the string @p str to @p buf.
183 * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
184 * returned.
185 */ 187 */
186EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); 188EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2);
187 189
@@ -189,19 +191,17 @@ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EIN
189 * @brief Appends a string to a buffer, reallocating as necessary, 191 * @brief Appends a string to a buffer, reallocating as necessary,
190 * limited by the given length. 192 * limited by the given length.
191 * 193 *
192 * @param buf The string buffer to append to. 194 * @param buf The string buffer.
193 * @param str The string to append. 195 * @param str The string to append.
194 * @param maxlen The maximum number of characters to append. 196 * @param maxlen The maximum number of characters to append.
195 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 197 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be appended.
196 * 198 *
197 * This function appends at most @p maxlen characters of @p str to 199 * This function appends at most @p maxlen characters of @p str to
198 * @p buf. It can't append more than the length of @p str. It 200 * @p buf. It can't append more than the length of @p str. It
199 * computes the length of @p str, so it is slightly slower than 201 * computes the length of @p str, so it is slightly slower than
200 * eina_strbuf_append_length(). If the length is known beforehand, 202 * eina_strbuf_append_length(). If the length is known beforehand,
201 * consider using that variant (@p maxlen should then be checked so 203 * consider using that variant (@p maxlen should then be checked so
202 * that it is greater than the size of @p str). If @p str can not be 204 * that it is greater than the size of @p str).
203 * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
204 * returned.
205 * 205 *
206 * @see eina_strbuf_append() 206 * @see eina_strbuf_append()
207 * @see eina_strbuf_append_length() 207 * @see eina_strbuf_append_length()
@@ -209,19 +209,18 @@ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EIN
209EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2); 209EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
210 210
211/** 211/**
212 * @brief Appends a string of exact length to a buffer, reallocating as necessary. 212 * @brief Appends a string of exact length to a buffer, reallocating as
213 * necessary.
213 * 214 *
214 * @param buf The string buffer to append to. 215 * @param buf The string buffer.
215 * @param str The string to append. 216 * @param str The string to append.
216 * @param length The exact length to use. 217 * @param length The exact length to use.
217 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 218 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be appended.
218 * 219 *
219 * This function appends @p str to @p buf. @p str must be of size at 220 * This function appends @p str to @p buf. @p str must be of size at
220 * most @p length. It is slightly faster than eina_strbuf_append() as 221 * most @p length. It is slightly faster than eina_strbuf_append() as
221 * it does not compute the size of @p str. It is useful when dealing 222 * it does not compute the size of @p str. It is useful when dealing
222 * with strings of known size, such as eina_stringshare. If @p buf 223 * with strings of known size, such as eina_stringshare.
223 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
224 * returned.
225 * 224 *
226 * @see eina_stringshare_length() 225 * @see eina_stringshare_length()
227 * @see eina_strbuf_append() 226 * @see eina_strbuf_append()
@@ -232,12 +231,11 @@ EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size
232/** 231/**
233 * @brief Append a slice to a buffer, reallocating as necessary. 232 * @brief Append a slice to a buffer, reallocating as necessary.
234 * 233 *
235 * @param buf The string buffer to append to. 234 * @param buf The string buffer.
236 * @param slice The slice to append. 235 * @param slice The slice to append.
237 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 236 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be appended.
238 * 237 *
239 * This function appends @p slice to @p buf. If @p buf can't append 238 * This function appends @p slice to @p buf.
240 * it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
241 * 239 *
242 * @since 1.19.0 240 * @since 1.19.0
243 */ 241 */
@@ -246,18 +244,18 @@ EAPI Eina_Bool eina_strbuf_append_slice(Eina_Strbuf *buf, const Eina_Slice slice
246/** 244/**
247 * @brief Appends an Eina_Strbuf to a buffer, reallocating as necessary. 245 * @brief Appends an Eina_Strbuf to a buffer, reallocating as necessary.
248 * 246 *
249 * @param buf The string buffer to append to. 247 * @param buf The string buffer.
250 * @param data The string buffer to append. 248 * @param data The string buffer to append.
251 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 249 * @return #EINA_TRUE on success, #EINA_FALSE if @p data could not be appended.
252 * 250 *
253 * This function appends @p data to @p buf. @p data must be allocated and 251 * This function appends @p data to @p buf. @p data must be allocated and
254 * different from @c NULL. It is slightly faster than eina_strbuf_append() as 252 * different from @c NULL. It is slightly faster than eina_strbuf_append() as
255 * it does not compute the size of @p str. If @p buf can't append it, 253 * it does not compute the size of @p str.
256 * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
257 * 254 *
258 * @see eina_strbuf_append() 255 * @see eina_strbuf_append()
259 * @see eina_strbuf_append_n() 256 * @see eina_strbuf_append_n()
260 * @see eina_strbuf_append_length() 257 * @see eina_strbuf_append_length()
258 *
261 * @since 1.9.0 259 * @since 1.9.0
262 */ 260 */
263EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *data) EINA_ARG_NONNULL(1, 2); 261EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *data) EINA_ARG_NONNULL(1, 2);
@@ -266,35 +264,36 @@ EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *da
266 * @brief Appends a character to a string buffer, reallocating as 264 * @brief Appends a character to a string buffer, reallocating as
267 * necessary. 265 * necessary.
268 * 266 *
269 * @param buf The string buffer to append to. 267 * @param buf The string buffer.
270 * @param c The char to append. 268 * @param c The character to append.
271 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 269 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be appended.
272 * 270 *
273 * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE 271 * This function appends @p c to @p buf.
274 * is returned, otherwise #EINA_TRUE is returned.
275 */ 272 */
276EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1); 273EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1);
277 274
278/** 275/**
279 * @brief Appends a string to a buffer, reallocating as necessary. 276 * @brief Appends data elements to a buffer using printf-style formatting.
280 * 277 *
281 * @param buf The string buffer to append to. 278 * @param buf The string buffer.
282 * @param fmt The string to append. 279 * @param fmt A formatting string.
283 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 280 * @param ... Variable list of data parameters to be appended.
281 * @return #EINA_TRUE on success, #EINA_FALSE if formatted string could
282 * not be appended.
284 * 283 *
285 * This function appends the string defined by the format @p fmt to @p buf. @p 284 * This function appends the string defined by the format @p fmt to @p
286 * fmt must be of a valid format for printf family of functions. If it can't 285 * buf, reallocating as necessary. @p fmt must be of a valid format for
287 * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. 286 * the printf family of functions.
288 * 287 *
289 * @see eina_strbuf_append() 288 * @see eina_strbuf_append()
290 */ 289 */
291EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); 290EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3);
292 291
293/** 292/**
294 * @brief Appends a string to a buffer, reallocating as necessary. 293 * @brief Appends data elements to a string buffer using a va_list.
295 * 294 *
296 * @param buf The string buffer to append to. 295 * @param buf The string buffer.
297 * @param fmt The string to append. 296 * @param fmt A formatting string.
298 * @param args The variable arguments. 297 * @param args The variable arguments.
299 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 298 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
300 * 299 *
@@ -303,71 +302,66 @@ EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...)
303EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2); 302EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2);
304 303
305/** 304/**
306 * @brief Inserts a string to a buffer, reallocating as necessary. 305 * @brief Inserts a string into a buffer, reallocating as necessary.
307 * 306 *
308 * @param buf The string buffer to insert. 307 * @param buf The string buffer.
309 * @param str The string to insert. 308 * @param str The string to insert.
310 * @param pos The position to insert the string. 309 * @param pos The position to insert the string.
311 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 310 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
312 * 311 *
313 * This function inserts @p str to @p buf at position @p pos. It 312 * This function inserts @p str into @p buf at position @p pos. It
314 * computes the length of @p str, so is slightly slower than 313 * computes the length of @p str, so is slightly slower than
315 * eina_strbuf_insert_length(). If the length is known beforehand, 314 * eina_strbuf_insert_length(). If the length is known beforehand,
316 * consider using that variant. If @p buf can't insert it, #EINA_FALSE 315 * consider using that variant.
317 * is returned, otherwise #EINA_TRUE is returned.
318 */ 316 */
319EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); 317EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
320 318
321/** 319/**
322 * @brief Inserts an escaped string to a buffer, reallocating as 320 * @brief Inserts an escaped string into a buffer, reallocating as
323 * necessary. 321 * necessary.
324 * 322 *
325 * @param buf The string buffer to insert to. 323 * @param buf The string buffer.
326 * @param str The string to insert. 324 * @param str The string to insert.
327 * @param pos The position to insert the string. 325 * @param pos The position to insert the string.
328 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 326 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
329 * 327 *
330 * This function escapes and inserts the string @p str to @p buf at 328 * This function escapes and inserts the string @p str into @p buf at
331 * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is 329 * position @p pos.
332 * returned, otherwise #EINA_TRUE is returned.
333 */ 330 */
334EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); 331EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
335 332
336/** 333/**
337 * @brief Inserts a string to a buffer, reallocating as necessary. Limited by maxlen. 334 * @brief Inserts a string of a maximum length into a buffer, reallocating as necessary.
338 * 335 *
339 * @param buf The string buffer to insert to. 336 * @param buf The string buffer.
340 * @param str The string to insert. 337 * @param str The string to insert.
341 * @param maxlen The maximum number of chars to insert. 338 * @param maxlen The maximum number of chars to insert.
342 * @param pos The position to insert the string. 339 * @param pos The position to insert the string.
343 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 340 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
344 * 341 *
345 * This function inserts @p str to @p buf at position @p pos, with at 342 * This function inserts @p str into @p buf at position @p pos, with at
346 * most @p maxlen bytes. The number of inserted characters can not be 343 * most @p maxlen bytes. The number of inserted characters cannot be
347 * greater than the length of @p str. It computes the length of 344 * greater than the length of @p str. It computes the length of
348 * @p str, so is slightly slower than eina_strbuf_insert_length(). If the 345 * @p str, so is slightly slower than eina_strbuf_insert_length(). If the
349 * length is known beforehand, consider using that variant (@p maxlen 346 * length is known beforehand, consider using that variant (@p maxlen
350 * should then be checked so that it is greater than the size of 347 * should then be checked so that it is greater than the size of
351 * @p str). If @p str can not be inserted, #EINA_FALSE is returned, 348 * @p str).
352 * otherwise, #EINA_TRUE is returned.
353 */ 349 */
354EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); 350EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
355 351
356/** 352/**
357 * @brief Inserts a string of exact length to a buffer, reallocating as necessary. 353 * @brief Inserts a string of an exact length into a buffer, reallocating as necessary.
358 * 354 *
359 * @param buf The string buffer to insert to. 355 * @param buf The string buffer.
360 * @param str The string to insert. 356 * @param str The string to insert.
361 * @param length The exact length to use. 357 * @param length The exact length to use.
362 * @param pos The position to insert the string. 358 * @param pos The position to insert the string.
363 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 359 * @return #EINA_TRUE on success, #EINA_FALSE if @p string could not be inserted.
364 * 360 *
365 * This function inserts @p str to @p buf. @p str must be of size at 361 * This function inserts @p str into @p buf. @p str must be no longer
366 * most @p length. It is slightly faster than eina_strbuf_insert() as 362 * than @p length. It is slightly faster than eina_strbuf_insert() as
367 * it does not compute the size of @p str. It is useful when dealing 363 * it does not compute the size of @p str. It is useful when dealing
368 * with strings of known size, such as eina_strngshare. If @p buf 364 * with strings of known size, such as eina_stringshare.
369 * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
370 * returned.
371 * 365 *
372 * @see eina_stringshare_length() 366 * @see eina_stringshare_length()
373 * @see eina_strbuf_insert() 367 * @see eina_strbuf_insert()
@@ -376,55 +370,51 @@ EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t ma
376EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); 370EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
377 371
378/** 372/**
379 * @brief Insert a slice to a buffer, reallocating as necessary. 373 * @brief Insert a slice into a buffer, reallocating as necessary.
380 * 374 *
381 * @param buf The string buffer to insert to. 375 * @param buf The string buffer.
382 * @param slice The slice to insert. 376 * @param slice The slice to insert.
383 * @param pos The position to insert the string. 377 * @param pos The position to insert the string.
384 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 378 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be inserted.
385 * 379 *
386 * This function inserts @p slice to @p buf at position @p pos. If @p 380 * This function inserts @p slice into @p buf at position @p pos.
387 * buf can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE
388 * is returned.
389 * 381 *
390 * @since 1.19.0 382 * @since 1.19.0
391 */ 383 */
392EAPI Eina_Bool eina_strbuf_insert_slice(Eina_Strbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1); 384EAPI Eina_Bool eina_strbuf_insert_slice(Eina_Strbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
393 385
394/** 386/**
395 * @brief Inserts a character to a string buffer, reallocating as 387 * @brief Inserts a character into a string buffer, reallocating as
396 * necessary. 388 * necessary.
397 * 389 *
398 * @param buf The string buffer to insert to. 390 * @param buf The string buffer.
399 * @param c The char to insert. 391 * @param c The character to insert.
400 * @param pos The position to insert the char. 392 * @param pos The position to insert the character.
401 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 393 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be inserted.
402 * 394 *
403 * This function inserts @p c to @p buf at position @p pos. If @p buf 395 * This function inserts @p c into @p buf at position @p pos.
404 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
405 * returned.
406 */ 396 */
407EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1); 397EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1);
408 398
409/** 399/**
410 * @brief Inserts a string to a buffer, reallocating as necessary. 400 * @brief Inserts data elements into a buffer using printf-style formatting.
411 * 401 *
412 * @param buf The string buffer to insert. 402 * @param buf The string buffer.
413 * @param fmt The string to insert. 403 * @param fmt The string to insert.
414 * @param pos The position to insert the string. 404 * @param pos The position to insert the string.
415 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 405 * @param ... Variable list of data parameters to be inserted.
406 * @return #EINA_TRUE on success, #EINA_FALSE if the string could not be inserted.
416 * 407 *
417 * This function inserts a string as described by the format @p fmt to @p buf at 408 * This function inserts a string as described by the format @p fmt into @p buf at
418 * the position @p pos. @p fmt must be of a valid format for printf family of 409 * the position @p pos. @p fmt must be of a valid format for printf family of
419 * functions. If it can't insert it, #EINA_FALSE is returned, 410 * functions.
420 * otherwise #EINA_TRUE is returned.
421 */ 411 */
422EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4); 412EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4);
423 413
424/** 414/**
425 * @brief Inserts a string to a buffer, reallocating as necessary. 415 * @brief Inserts data elements into a buffer using a va_list.
426 * 416 *
427 * @param buf The string buffer to insert. 417 * @param buf The string buffer.
428 * @param fmt The string to insert. 418 * @param fmt The string to insert.
429 * @param pos The position to insert the string. 419 * @param pos The position to insert the string.
430 * @param args The variable arguments. 420 * @param args The variable arguments.
@@ -436,118 +426,103 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
436 426
437/** 427/**
438 * @def eina_strbuf_prepend(buf, str) 428 * @def eina_strbuf_prepend(buf, str)
439 * @brief Prepends the given string to the given buffer. 429 * @brief Prepends a string to the given buffer.
440 * 430 *
441 * @param buf The string buffer to prepend to. 431 * @param buf The string buffer.
442 * @param str The string to prepend. 432 * @param str The string to prepend.
443 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 433 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be prepended.
444 * 434 *
445 * This macro is calling eina_strbuf_insert() at position 0. If @p buf 435 * This macro simply calls eina_strbuf_insert() with position 0.
446 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
447 * returned.
448 */ 436 */
449#define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf, str, 0) 437#define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf, str, 0)
450 438
451/** 439/**
452 * @def eina_strbuf_prepend_escaped(buf, str) 440 * @def eina_strbuf_prepend_escaped(buf, str)
453 * @brief Prepends the given escaped string to the given buffer. 441 * @brief Prepends an escaped string to the given buffer.
454 * 442 *
455 * @param buf The string buffer to prepend to. 443 * @param buf The string buffer.
456 * @param str The string to prepend. 444 * @param str The string to prepend.
457 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 445 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be prepended.
458 * 446 *
459 * This macro is calling eina_strbuf_insert_escaped() at position 0. If 447 * This macro simply calls eina_strbuf_insert_escaped() with position 0.
460 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
461 * returned.
462 */ 448 */
463#define eina_strbuf_prepend_escaped(buf, str) eina_strbuf_insert_escaped(buf, str, 0) 449#define eina_strbuf_prepend_escaped(buf, str) eina_strbuf_insert_escaped(buf, str, 0)
464 450
465/** 451/**
466 * @def eina_strbuf_prepend_n(buf, str) 452 * @def eina_strbuf_prepend_n(buf, str)
467 * @brief Prepends the given escaped string to the given buffer. 453 * @brief Prepends an escaped string to the given buffer.
468 * 454 *
469 * @param buf The string buffer to prepend to. 455 * @param buf The string buffer.
470 * @param str The string to prepend. 456 * @param str The string to prepend.
471 * @param maxlen The maximum number of chars to prepend. 457 * @param maxlen The maximum number of chars to prepend.
472 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 458 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be prepended.
473 * 459 *
474 * This macro is calling eina_strbuf_insert_n() at position 0. If 460 * This macro simply calls eina_strbuf_insert_n() with position 0.
475 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
476 * returned.
477 */ 461 */
478#define eina_strbuf_prepend_n(buf, str, maxlen) eina_strbuf_insert_n(buf, str, maxlen, 0) 462#define eina_strbuf_prepend_n(buf, str, maxlen) eina_strbuf_insert_n(buf, str, maxlen, 0)
479 463
480/** 464/**
481 * @def eina_strbuf_prepend_length(buf, str) 465 * @def eina_strbuf_prepend_length(buf, str)
482 * @brief Prepends the given escaped string to the given buffer. 466 * @brief Prepends an escaped string to the given buffer.
483 * 467 *
484 * @param buf The string buffer to prepend to. 468 * @param buf The string buffer.
485 * @param str The string to prepend. 469 * @param str The string to prepend.
486 * @param length The exact length to use. 470 * @param length The exact length to use.
487 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 471 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be prepended.
488 * 472 *
489 * This macro is calling eina_strbuf_insert_length() at position 0. If 473 * This macro simply calls eina_strbuf_insert_length() with position 0.
490 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
491 * returned.
492 */ 474 */
493#define eina_strbuf_prepend_length(buf, str, length) eina_strbuf_insert_length(buf, str, length, 0) 475#define eina_strbuf_prepend_length(buf, str, length) eina_strbuf_insert_length(buf, str, length, 0)
494 476
495/** 477/**
496 * @def eina_strbuf_prepend_char(buf, str) 478 * @def eina_strbuf_prepend_char(buf, str)
497 * @brief Prepends the given character to the given buffer. 479 * @brief Prepends a character to the given buffer.
498 * 480 *
499 * @param buf The string buffer to prepend to. 481 * @param buf The string buffer.
500 * @param c The character to prepend. 482 * @param c The character to prepend.
501 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 483 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
502 * 484 *
503 * This macro is calling eina_strbuf_insert_char() at position 0. If 485 * This macro simply calls eina_strbuf_insert_char() with position 0.
504 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE
505 * is returned.
506 */ 486 */
507#define eina_strbuf_prepend_char(buf, c) eina_strbuf_insert_char(buf, c, 0) 487#define eina_strbuf_prepend_char(buf, c) eina_strbuf_insert_char(buf, c, 0)
508 488
509/** 489/**
510 * @def eina_strbuf_prepend_printf(buf, fmt, ...) 490 * @def eina_strbuf_prepend_printf(buf, fmt, ...)
511 * @brief Prepends the given string to the given buffer. 491 * @brief Prepends data elements to the given buffer using printf-style formatting.
512 * 492 *
513 * @param buf The string buffer to prepend to. 493 * @param buf The string buffer.
514 * @param fmt The string to prepend. 494 * @param fmt The string to prepend.
515 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 495 * @param ... Variable list of data elements to prepend.
496 * @return #EINA_TRUE on success, #EINA_FALSE if data could not be prepended.
516 * 497 *
517 * This macro is calling eina_strbuf_insert_printf() at position 0. If @p buf 498 * This macro simply calls eina_strbuf_insert_printf() with position 0.
518 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
519 * returned.
520 */ 499 */
521#define eina_strbuf_prepend_printf(buf, fmt, ...) eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__) 500#define eina_strbuf_prepend_printf(buf, fmt, ...) eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__)
522 501
523/** 502/**
524 * @def eina_strbuf_prepend_vprintf(buf, fmt, args) 503 * @def eina_strbuf_prepend_vprintf(buf, fmt, args)
525 * @brief Prepends the given string to the given buffer. 504 * @brief Prepends the given string to the given buffer.
526 * 505 *
527 * @param buf The string buffer to prepend to. 506 * @param buf The string buffer.
528 * @param fmt The string to prepend. 507 * @param fmt The string to prepend.
529 * @param args The variable arguments. 508 * @param args The variable arguments.
530 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 509 * @return #EINA_TRUE on success, #EINA_FALSE if data could not be prepended.
531 * 510 *
532 * This macro is calling eina_strbuf_insert_vprintf() at position 0.If @p buf 511 * This macro simply calls eina_strbuf_insert_vprintf() with position 0.
533 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
534 * returned.
535 */ 512 */
536#define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args) 513#define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args)
537 514
538/** 515/**
539 * @brief Removes a slice of the given string buffer. 516 * @brief Removes a section from the given string buffer.
540 * 517 *
541 * @param buf The string buffer to remove a slice. 518 * @param buf The string buffer.
542 * @param start The initial (inclusive) slice position to start 519 * @param start The initial (inclusive) byte position to start removal.
543 * removing, in bytes. 520 * @param end The final (non-inclusive) byte position to end removal.
544 * @param end The final (non-inclusive) slice position to finish
545 * removing, in bytes.
546 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 521 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
547 * 522 *
548 * This function removes a slice of @p buf, starting at @p start 523 * This function removes a slice of @p buf, starting at @p start
549 * (inclusive) and ending at @p end (non-inclusive). Both values are 524 * (inclusive) and ending at @p end (non-inclusive). Both values are
550 * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. 525 * in bytes.
551 */ 526 */
552 527
553EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); 528EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
@@ -560,9 +535,9 @@ EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EI
560 * 535 *
561 * This function returns the string contained in @p buf. The returned 536 * This function returns the string contained in @p buf. The returned
562 * value must not be modified and will no longer be valid if @p buf is 537 * value must not be modified and will no longer be valid if @p buf is
563 * modified. In other words, any eina_strbuf_append() or similar will 538 * modified. In other words, calling eina_strbuf_append() or similar
564 * make that pointer invalid. The pointer returned by this function <b>must 539 * functions will make this pointer invalid. The pointer returned by
565 * not</b> be freed. 540 * this function <b>must not</b> be freed.
566 * 541 *
567 * @see eina_strbuf_string_steal() 542 * @see eina_strbuf_string_steal()
568 */ 543 */
@@ -571,8 +546,8 @@ EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL
571/** 546/**
572 * @brief Steals the contents of a string buffer. 547 * @brief Steals the contents of a string buffer.
573 * 548 *
574 * @param buf The string buffer to steal. 549 * @param buf The string buffer.
575 * @return The current string in the string buffer. 550 * @return The string that was contained in @p buf.
576 * 551 *
577 * This function returns the string contained in @p buf. @p buf is 552 * This function returns the string contained in @p buf. @p buf is
578 * then initialized and does not own the returned string anymore. The 553 * then initialized and does not own the returned string anymore. The
@@ -586,7 +561,7 @@ EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUS
586/** 561/**
587 * @brief Frees the contents of a string buffer but not the buffer. 562 * @brief Frees the contents of a string buffer but not the buffer.
588 * 563 *
589 * @param buf The string buffer to free the string of. 564 * @param buf The string buffer.
590 * 565 *
591 * This function frees the string contained in @p buf without freeing 566 * This function frees the string contained in @p buf without freeing
592 * @p buf. 567 * @p buf.
@@ -594,160 +569,160 @@ EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUS
594EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); 569EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
595 570
596/** 571/**
597 * @brief Retrieves the length of the string buffer content. 572 * @brief Retrieves the length of the string buffer's content.
598 * 573 *
599 * @param buf The string buffer. 574 * @param buf The string buffer.
600 * @return The current length of the string, in bytes. 575 * @return The current length of the string, in bytes.
601 * 576 *
602 * This function returns the length of @p buf. 577 * This function returns the length of @p buf.
603 */ 578 */
604EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 579EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
605
606 580
607/** 581/**
608 * @brief Replaces the n-th string with an other string. 582 * @brief Replaces a substring in the buffer with another string.
609 * 583 *
610 * @param buf The string buffer to work with. 584 * @param buf The string buffer.
611 * @param str The string to replace. 585 * @param str The text to match.
612 * @param with The replacing string. 586 * @param with The replacement string.
613 * @param n The number of the fitting string. 587 * @param n The indexed occurrence to be replaced.
614 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 588 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
615 * 589 *
616 * This function replaces the n-th occurrence of @p str in @p buf with 590 * This function replaces the n-th occurrence of @p str in @p buf with
617 * @p with. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. 591 * @p with.
618 */ 592 */
619EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3); 593EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3);
620 594
621/** 595/**
622 * @def eina_strbuf_replace_first(buf, str, with) 596 * @def eina_strbuf_replace_first(buf, str, with)
623 * @brief Prepends the given character to the given buffer. 597 * @brief Replaces the first occurance of a substring with another string.
624 * 598 *
625 * @param buf The string buffer to work with. 599 * @param buf The string buffer.
626 * @param str The string to replace. 600 * @param str The text to match.
627 * @param with The replaceing string. 601 * @param with The replacement string.
628 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 602 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be
603 * replaced in @p buf.
629 * 604 *
630 * This macro is calling eina_strbuf_replace() with the n-th occurrence 605 * This macro simply calls eina_strbuf_replace() with @p n
631 * equal to @c 1. If @p buf can't replace it, #EINA_FALSE is returned, 606 * equal to @c 1.
632 * otherwise #EINA_TRUE is returned.
633 */ 607 */
634#define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf, str, with, 1) 608#define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf, str, with, 1)
635 609
636
637/** 610/**
638 * @brief Replaces all strings with another string. 611 * @brief Replaces all matching substrings with another string.
639 612 *
640 * @param buf The string buffer to work with. 613 * @param buf The string buffer.
641 * @param str The string to replace. 614 * @param str The text to match.
642 * @param with The replacement string. 615 * @param with The replacement string.
643 * @return How often the string was replaced. 616 * @return Number of replacements made, or @c 0 on failure.
644 * 617 *
645 * This function replaces all the occurrences of @p str in @p buf with 618 * This function replaces all the occurrences of @p str in @p buf with
646 * the string @p with. This function returns the number of times @p str 619 * the string @p with.
647 * has been replaced. On failure, it returns @c 0.
648 */ 620 */
649EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3); 621EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3);
650 622
651/** 623/**
652 * @brief Trims the string buffer. 624 * @brief Trims the string buffer.
653
654 * @param buf The string buffer to work with.
655 * 625 *
656 * This function skips whitespaces at the beginning and the end of the buffer. 626 * @param buf The string buffer.
627 *
628 * This function removes whitespace at the beginning and end of the
629 * buffer's string.
657 */ 630 */
658EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); 631EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
659 632
660/** 633/**
661 * @brief Left trims the string buffer. 634 * @brief Left trims the string buffer.
662
663 * @param buf The string buffer to work with.
664 * 635 *
665 * This function skips whitespaces in the beginning of the buffer. 636 * @param buf The string buffer.
637 *
638 * This function removes whitespace at the beginning of the buffer's
639 * string.
666 */ 640 */
667EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); 641EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
668 642
669/** 643/**
670 * @brief Right trims the string buffer. 644 * @brief Right trims the string buffer.
671
672 * @param buf The string buffer to work with.
673 * 645 *
674 * This function skips whitespaces in the end of the buffer. 646 * @param buf The string buffer.
647 *
648 * This function removes whitespace at the end of the buffer's string.
675 */ 649 */
676EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); 650EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
677 651
678/** 652/**
679 * @brief Converts the string to lower case. 653 * @brief Converts the string to lower case.
680 * 654 *
681 * @param buf The string buffer to work with. 655 * @param buf The string buffer.
682 * 656 *
683 * This function converts all the characters in the strbuf to lower case. 657 * This function converts all the characters in the buffer's string to
658 * lower case.
684 * 659 *
685 * @since 1.17 660 * @since 1.17
686 */ 661 */
687EAPI void eina_strbuf_tolower(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); 662EAPI void eina_strbuf_tolower(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
688 663
689/** 664/**
690 * @brief Obtains substring from the src. 665 * @brief Obtains substring from a source string buffer.
691 * 666 *
692 * @param buf The src string. 667 * @param buf The string buffer.
693 * @param pos The position in the source string from which the substring 668 * @param pos The (0-based) position where the substring starts.
694 * should be created. The first character is denoted by a 669 * @param len The length from @p pos that should be copied.
695 * value of 0 (not 1). 670 * @return A string buffer containing the substring, or @c NULL if
696 * @param len The length from pos that should be copied to substring. 671 * invalid parameters were specified.
697 * 672 *
698 * This function creates a Eina_Strbuf which is a substring of buf which 673 * This function creates a Eina_Strbuf containing a copy of a substring
699 * is passed from pos position with len length. 674 * of buf starting at @p pos with @p len length. If len is 0, then an
700 * If buf is NULL then returns NULL. 675 * empty strbuf will be returned.
701 * If len is 0, then an empty strbuf is returned.
702 * 676 *
703 * @since 1.17 677 * @since 1.17
704 */ 678 */
705EAPI Eina_Strbuf * eina_strbuf_substr_get(Eina_Strbuf *buf, size_t pos, size_t len) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 679EAPI Eina_Strbuf * eina_strbuf_substr_get(Eina_Strbuf *buf, size_t pos, size_t len) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
706 680
707/** 681/**
708 * @brief Gets a read-only slice representing the current strbuf contents. 682 * @brief Gets a read-only slice of the buffer contents.
709 * 683 *
710 * @param buf The source string. 684 * @param buf The string buffer.
711 * @return A read-only slice for the current contents. It may become 685 * @return A read-only slice of the current contents. It may become
712 * invalid as soon as the @a buf is changed. 686 * invalid as soon as @p buf is changed.
713 * 687 *
714 * @since 1.19 688 * @since 1.19
715 */ 689 */
716EAPI Eina_Slice eina_strbuf_slice_get(const Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 690EAPI Eina_Slice eina_strbuf_slice_get(const Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
717 691
718/** 692/**
719 * @brief Gets a read-write slice representing the current strbuf contents. 693 * @brief Gets a read-write slice of the buffer contents.
720 * 694 *
721 * @param buf The source string. 695 * @param buf The string buffer.
722 * @return A read-write slice for the current contents. It may become 696 * @return A read-write slice for the current contents. It may become
723 * invalid as soon as the @a buf is changed with calls such as 697 * invalid as soon as the @p buf is changed, such as through calls like
724 * eina_strbuf_append(), eina_strbuf_remove() 698 * eina_strbuf_append() or eina_strbuf_remove().
725 * 699 *
726 * @since 1.19.0 700 * @since 1.19.0
727 */ 701 */
728EAPI Eina_Rw_Slice eina_strbuf_rw_slice_get(const Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 702EAPI Eina_Rw_Slice eina_strbuf_rw_slice_get(const Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
729 703
730
731/** 704/**
732 * @brief Gets the string of the buffer and free the buffer 705 * @brief Frees the buffer, returning its old contents.
733 *
734 * @param buf The buffer to get the string from and which will be freed
735 * 706 *
736 * @return The string contained by buf. The caller must release the memory of the returned string by calling 707 * @param buf The string buffer.*
737 * free(). 708 * @return The string contained by buf. The caller must release the
709 * memory of the returned string by calling free().
738 * 710 *
739 * @since 1.19 711 * @since 1.19
740 */ 712 */
741EAPI char* eina_strbuf_release(Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 713EAPI char* eina_strbuf_release(Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
742 714
743/** 715/**
744 * @brief append the given buffer based on strftime output. 716 * @brief Appends a strftime-style timestamp to the buffer.
745 * 717 *
746 * @param tm Pointer to a tm structure needed by strftime. 718 * @param buf The string buffer.
747 * @param fmt String containing format specifiers needed by strftime. 719 * @param fmt The formatting string.
720 * @param tm The time value.
748 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 721 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
749 * 722 *
750 * This will add append buffer of exact required size based on strftime output 723 * This function appends a timestamp to the buffer, formatted using
724 * strftime. A string of the exact size required by strftime's output
725 * is added to the end.
751 * 726 *
752 * Example usage: 727 * Example usage:
753 * @code 728 * @code
@@ -759,21 +734,24 @@ EAPI char* eina_strbuf_release(Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_AR
759 * eina_strbuf_append_strftime(buf, "%I:%M%p", info); 734 * eina_strbuf_append_strftime(buf, "%I:%M%p", info);
760 * //after use 735 * //after use
761 * eina_strbuf_free(buf); 736 * eina_strbuf_free(buf);
762 * @endcode #EINA_TRUE on success, #EINA_FALSE on failure. 737 * @endcode
763 * 738 *
764 * @since 1.21 739 * @since 1.21
765 */ 740 */
766EAPI Eina_Bool eina_strbuf_append_strftime(Eina_Strbuf *buf, const char *fmt, const struct tm *tm); 741EAPI Eina_Bool eina_strbuf_append_strftime(Eina_Strbuf *buf, const char *fmt, const struct tm *tm);
767 742
768/** 743/**
769 * @brief insert the given buffer based on strftime output at given position 744 * @brief Inserts a strftime-style timestamp into the buffer.
770 * 745 *
771 * @param buf The string buffer to prepend to. 746 * @param buf The string buffer.
772 * @param fmt String containing format specifiers needed by strftime. 747 * @param fmt The formatting string.
773 * @param tm Pointer to a tm structure needed by strftime. 748 * @param tm The time value.
749 * @param pos The position in the buffer to insert the timestamp.
774 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 750 * @return #EINA_TRUE on success, #EINA_FALSE on failure.
775 * 751 *
776 * This will add append buffer of exact required size based on strftime output 752 * This function inserts a timestamp into the buffer, formatted using
753 * strftime. The buffer's length will be increased by the exact amount
754 * required by strftime's output.
777 * 755 *
778 * Example usage: 756 * Example usage:
779 * @code 757 * @code
@@ -793,20 +771,18 @@ EAPI Eina_Bool eina_strbuf_insert_strftime(Eina_Strbuf *buf, const char *fmt, co
793 771
794/** 772/**
795 * @def eina_strbuf_prepend_strftime(buf, fmt, tm) 773 * @def eina_strbuf_prepend_strftime(buf, fmt, tm)
796 * @brief Prepends the given string to the given buffer. 774 * @brief Prepends a strftime-style timestamp to the buffer.
797 * 775 *
798 * @param buf The string buffer to prepend to. 776 * @param buf The string buffer.
799 * @param fmt The string to prepend. 777 * @param fmt The formatting string.
800 * @param tm The variable arguments. 778 * @param tm The time value.
801 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 779 * @return #EINA_TRUE on success, #EINA_FALSE if @p tm could not be prepended.
802 * 780 *
803 * This macro is calling eina_strbuf_insert_strftime() at position 0. If @p buf 781 * This macro simply calls eina_strbuf_insert_strftime() with position 0.
804 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
805 * returned.
806 * 782 *
807 * @since 1.21 783 * @since 1.21
808 */ 784 */
809#define eina_strbuf_prepend_strftime(buf, fmt, tm) eina_strbuf_insert_strftime(buf, fmt, tm, 0) 785#define eina_strbuf_prepend_strftime(buf, fmt, tm) eina_strbuf_insert_strftime(buf, fmt, tm, 0)
810 786
811/** 787/**
812 * @} 788 * @}
diff --git a/src/lib/eina/eina_ustrbuf.h b/src/lib/eina/eina_ustrbuf.h
index f3ea97d931..5c88af9257 100644
--- a/src/lib/eina/eina_ustrbuf.h
+++ b/src/lib/eina/eina_ustrbuf.h
@@ -9,10 +9,11 @@
9/** 9/**
10 * @addtogroup Eina_Unicode_String_Buffer_Group Unicode String Buffer 10 * @addtogroup Eina_Unicode_String_Buffer_Group Unicode String Buffer
11 * 11 *
12 * @brief These functions provide unicode string buffers management. 12 * @brief These functions provide unicode string buffer management.
13 * 13 *
14 * The Unicode String Buffer data type is designed to be a mutable string, 14 * The Unicode String Buffer data type is designed to be a mutable
15 * allowing to append, prepend or insert a string to a buffer. 15 * string, allowing the appending, prepending or insertion of a string
16 * to a buffer.
16 */ 17 */
17 18
18/** 19/**
@@ -29,17 +30,17 @@
29 30
30/** 31/**
31 * @typedef Eina_UStrbuf 32 * @typedef Eina_UStrbuf
32 * Type for a string buffer. 33 * Type for a unicode string buffer.
33 */ 34 */
34typedef struct _Eina_Strbuf Eina_UStrbuf; 35typedef struct _Eina_Strbuf Eina_UStrbuf;
35 36
36/** 37/**
37 * @brief Creates a new string buffer. 38 * @brief Creates a new unicode string buffer.
38 * 39 *
39 * @return Newly allocated string buffer instance. 40 * @return Newly allocated string buffer instance, or @c NULL on error.
40 * 41 *
41 * This function creates a new string buffer. On error, @c NULL is 42 * This function creates a new string buffer. To free the resources, use
42 * returned. To free the resources, use eina_ustrbuf_free(). 43 * eina_ustrbuf_free().
43 * 44 *
44 * @see eina_ustrbuf_free() 45 * @see eina_ustrbuf_free()
45 * @see eina_ustrbuf_append() 46 * @see eina_ustrbuf_append()
@@ -48,36 +49,38 @@ typedef struct _Eina_Strbuf Eina_UStrbuf;
48EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 49EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
49 50
50/** 51/**
51 * @brief Creates a new string buffer using the passed string. The passed 52 * @brief Creates a new string buffer using the passed string.
52 * string is used directly as the buffer, it's somehow the opposite function of
53 * @ref eina_ustrbuf_string_steal . The passed string must be malloc'd.
54 * 53 *
55 * @param str The string to manage 54 * @param str The string to manage.
56 * @return Newly allocated string buffer instance 55 * @return Newly allocated string buffer instance, or @c NULL on error.
57 * 56 *
58 * This function creates a new string buffer. On error, @c NULL is 57 * This function creates a new unicode string buffer. The passed string
59 * returned. To free the resources, use eina_strbuf_free(). 58 * is used directly as the buffer, it's effectively the inverse of
59 * eina_ustrbuf_string_steal(). The passed string must be malloc'd.
60 * To free the resources, use eina_ustrbuf_free().
60 * 61 *
61 * @see eina_ustrbuf_free() 62 * @see eina_ustrbuf_free()
62 * @see eina_ustrbuf_append() 63 * @see eina_ustrbuf_append()
63 * @see eina_ustrbuf_string_get() 64 * @see eina_ustrbuf_string_get()
65 *
64 * @since 1.1.0 66 * @since 1.1.0
65 */ 67 */
66EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 68EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
67 69
68/** 70/**
69 * @brief Creates a new string buffer using the passed string. The passed 71 * @brief Creates a new string buffer using the passed string.
70 * string is used directly as the buffer, it's somehow the opposite function of
71 * @ref eina_ustrbuf_string_steal . The passed string must be malloc'd.
72 * 72 *
73 * @param str The string to manage 73 * @param str The string to manage.
74 * @param length The length of the string. 74 * @param length The length of the string.
75 * @return Newly allocated string buffer instance. 75 * @return Newly allocated string buffer instance, or @c NULL on error.
76 * 76 *
77 * This function creates a new string buffer. On error, @c NULL is 77 * This function creates a new string buffer. The passed string is used
78 * returned. To free the resources, use eina_ustrbuf_free(). 78 * directly as the buffer, it's effectively the inverse of
79 * eina_ustrbuf_string_steal(). The passed string must be malloc'd. To
80 * free the resources, use eina_ustrbuf_free().
79 * 81 *
80 * @see eina_ustrbuf_manage_new() 82 * @see eina_ustrbuf_manage_new()
83 *
81 * @since 1.2.0 84 * @since 1.2.0
82 */ 85 */
83EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 86EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
@@ -95,25 +98,24 @@ EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
95/** 98/**
96 * @brief Resets a string buffer. 99 * @brief Resets a string buffer.
97 * 100 *
98 * @param buf The string buffer to reset. 101 * @param buf The string buffer.
99 * 102 *
100 * This function reset @p buf: the buffer len is set to 0, and the 103 * This function resets @p buf: the buffer len is set to 0, and the
101 * string is set to '\\0'. No memory is free'd. 104 * string data is set to '\\0'. No memory is freed.
102 */ 105 */
103EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); 106EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
104 107
105/** 108/**
106 * @brief Appends a string to a buffer, reallocating as necessary. 109 * @brief Appends a string to a buffer, reallocating as necessary.
107 * 110 *
108 * @param buf The string buffer to append to. 111 * @param buf The string buffer.
109 * @param str The string to append. 112 * @param str The string to append.
110 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 113 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if
114 * @p str could not be appended.
111 * 115 *
112 * This function appends @p str to @p buf. It computes the length of 116 * This function appends @p str to @p buf. It computes the length of
113 * @p str, so is slightly slower than eina_ustrbuf_append_length(). If 117 * @p str, so is slightly slower than eina_ustrbuf_append_length(). If
114 * the length is known beforehand, consider using that variant. If 118 * the length is known beforehand, consider using that variant.
115 * @p buf can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
116 * returned.
117 * 119 *
118 * @see eina_ustrbuf_append() 120 * @see eina_ustrbuf_append()
119 * @see eina_ustrbuf_append_length() 121 * @see eina_ustrbuf_append_length()
@@ -123,13 +125,11 @@ EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) E
123/** 125/**
124 * @brief Appends an escaped string to a buffer, reallocating as necessary. 126 * @brief Appends an escaped string to a buffer, reallocating as necessary.
125 * 127 *
126 * @param buf The string buffer to append to. 128 * @param buf The string buffer.
127 * @param str The string to append. 129 * @param str The string to append.
128 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 130 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be appended.
129 * 131 *
130 * This function appends the escaped string @p str to @p buf. If @p 132 * This function appends the escaped string @p str to @p buf.
131 * str can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
132 * returned.
133 */ 133 */
134EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2); 134EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
135 135
@@ -140,16 +140,14 @@ EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode
140 * @param buf The string buffer to append to. 140 * @param buf The string buffer to append to.
141 * @param str The string to append. 141 * @param str The string to append.
142 * @param maxlen The maximum number of characters to append. 142 * @param maxlen The maximum number of characters to append.
143 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 143 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be appended.
144 * 144 *
145 * This function appends at most @p maxlen characters of @p str to 145 * This function appends at most @p maxlen characters of @p str to
146 * @p buf. It can't append more than the length of @p str. It 146 * @p buf. It can't append more than the length of @p str. It
147 * computes the length of @p str, so is slightly slower than 147 * computes the length of @p str, so is slightly slower than
148 * eina_ustrbuf_append_length(). If the length is known beforehand, 148 * eina_ustrbuf_append_length(). If the length is known beforehand,
149 * consider using that variant (@p maxlen should then be checked so 149 * consider using that variant (@p maxlen should then be checked so
150 * that it is greater than the size of @p str). If @p str can not be 150 * that it is greater than the size of @p str).
151 * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
152 * returned.
153 * 151 *
154 * @see eina_ustrbuf_append() 152 * @see eina_ustrbuf_append()
155 * @see eina_ustrbuf_append_length() 153 * @see eina_ustrbuf_append_length()
@@ -157,19 +155,18 @@ EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode
157EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) EINA_ARG_NONNULL(1, 2); 155EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
158 156
159/** 157/**
160 * @brief Appends a string of exact length to a buffer, reallocating as necessary. 158 * @brief Appends a string of exact length to a buffer, reallocating as
159 * necessary.
161 * 160 *
162 * @param buf The string buffer to append to. 161 * @param buf The string buffer.
163 * @param str The string to append. 162 * @param str The string to append.
164 * @param length The exact length to use. 163 * @param length The exact length to use.
165 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 164 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be appended.
166 * 165 *
167 * This function appends @p str to @p buf. @p str must be of size at 166 * This function appends @p str to @p buf. @p str must be of size at
168 * most @p length. It is slightly faster than eina_ustrbuf_append() as 167 * most @p length. It is slightly faster than eina_ustrbuf_append() as
169 * it does not compute the size of @p str. It is useful when dealing 168 * it does not compute the size of @p str. It is useful when dealing
170 * with strings of known size, such as eina_strngshare. If @p buf 169 * with strings of known size, such as eina_strngshare.
171 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
172 * returned.
173 * 170 *
174 * @see eina_stringshare_length() 171 * @see eina_stringshare_length()
175 * @see eina_ustrbuf_append() 172 * @see eina_ustrbuf_append()
@@ -180,12 +177,11 @@ EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode
180/** 177/**
181 * @brief Appends a slice to a buffer, reallocating as necessary. 178 * @brief Appends a slice to a buffer, reallocating as necessary.
182 * 179 *
183 * @param buf The string buffer to append to. 180 * @param buf The string buffer.
184 * @param slice The slice to append. 181 * @param slice The slice to append.
185 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 182 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be appended.
186 * 183 *
187 * This function appends @p slice to @p buf. If @p buf can't append 184 * This function appends @p slice to @p buf.
188 * it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
189 * 185 *
190 * @since 1.19.0 186 * @since 1.19.0
191 */ 187 */
@@ -195,12 +191,11 @@ EAPI Eina_Bool eina_ustrbuf_append_slice(Eina_UStrbuf *buf, const Eina_Slice sli
195 * @brief Appends a character to a string buffer, reallocating as 191 * @brief Appends a character to a string buffer, reallocating as
196 * necessary. 192 * necessary.
197 * 193 *
198 * @param buf The string buffer to append to. 194 * @param buf The string buffer.
199 * @param c The char to append. 195 * @param c The char to append.
200 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 196 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be appended.
201 * 197 *
202 * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE 198 * This function appends @p c to @p buf.
203 * is returned, otherwise #EINA_TRUE is returned.
204 */ 199 */
205EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1); 200EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1);
206 201
@@ -210,13 +205,12 @@ EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_
210 * @param buf The string buffer to insert. 205 * @param buf The string buffer to insert.
211 * @param str The string to insert. 206 * @param str The string to insert.
212 * @param pos The position to insert the string. 207 * @param pos The position to insert the string.
213 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 208 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
214 * 209 *
215 * This function inserts @p str to @p buf at position @p pos. It 210 * This function inserts @p str to @p buf at position @p pos. It
216 * computes the length of @p str, so is slightly slower than 211 * computes the length of @p str, so is slightly slower than
217 * eina_ustrbuf_insert_length(). If the length is known beforehand, 212 * eina_ustrbuf_insert_length(). If the length is known beforehand,
218 * consider using that variant. If @p buf can't insert it, #EINA_FALSE 213 * consider using that variant.
219 * is returned, otherwise #EINA_TRUE is returned.
220 */ 214 */
221EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2); 215EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
222 216
@@ -224,52 +218,48 @@ EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, s
224 * @brief Inserts an escaped string to a buffer, reallocating as 218 * @brief Inserts an escaped string to a buffer, reallocating as
225 * necessary. 219 * necessary.
226 * 220 *
227 * @param buf The string buffer to insert to. 221 * @param buf The string buffer.
228 * @param str The string to insert. 222 * @param str The string to insert.
229 * @param pos The position to insert the string. 223 * @param pos The position to insert the string.
230 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 224 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
231 * 225 *
232 * This function inserts the escaped string @p str to @p buf at 226 * This function inserts the escaped string @p str to @p buf at
233 * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is 227 * position @p pos.
234 * returned, otherwise #EINA_TRUE is returned.
235 */ 228 */
236EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2); 229EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
237 230
238/** 231/**
239 * @brief Inserts a string to a buffer, reallocating as necessary. Limited by maxlen. 232 * @brief Inserts a string to a buffer, reallocating as necessary. Limited by maxlen.
240 * 233 *
241 * @param buf The string buffer to insert to. 234 * @param buf The string buffer.
242 * @param str The string to insert. 235 * @param str The string to insert.
243 * @param maxlen The maximum number of chars to insert. 236 * @param maxlen The maximum number of chars to insert.
244 * @param pos The position to insert the string. 237 * @param pos The position to insert the string.
245 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 238 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
246 * 239 *
247 * This function inserts @p str ot @p buf at position @p pos, with at 240 * This function inserts @p str into @p buf at position @p pos, with at
248 * most @p maxlen bytes. The number of inserted characters can not be 241 * most @p maxlen bytes. The number of inserted characters cannot be
249 * greater than the length of @p str. It computes the length of 242 * greater than the length of @p str. It computes the length of
250 * @p str, so is slightly slower than eina_ustrbuf_insert_length(). If the 243 * @p str, so is slightly slower than eina_ustrbuf_insert_length(). If the
251 * length is known beforehand, consider using that variant (@p maxlen 244 * length is known beforehand, consider using that variant (@p maxlen
252 * should then be checked so that it is greater than the size of 245 * should then be checked so that it is greater than the size of
253 * @p str). If @p str can not be inserted, #EINA_FALSE is returned, 246 * @p str).
254 * otherwise, #EINA_TRUE is returned.
255 */ 247 */
256EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); 248EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
257 249
258/** 250/**
259 * @brief Inserts a string of exact length to a buffer, reallocating as necessary. 251 * @brief Inserts a string of exact length to a buffer, reallocating as necessary.
260 * 252 *
261 * @param buf The string buffer to insert to. 253 * @param buf The string buffer.
262 * @param str The string to insert. 254 * @param str The string to insert.
263 * @param length The exact length to use. 255 * @param length The exact length to use.
264 * @param pos The position to insert the string. 256 * @param pos The position to insert the string.
265 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 257 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
266 * 258 *
267 * This function inserts @p str to @p buf. @p str must be of size at 259 * This function inserts @p str into @p buf. @p str must be no longer
268 * most @p length. It is slightly faster than eina_ustrbuf_insert() as 260 * than @p length. It is slightly faster than eina_ustrbuf_insert() as
269 * it does not compute the size of @p str. It is useful when dealing 261 * it does not compute the size of @p str. It is useful when dealing
270 * with strings of known size, such as eina_strngshare. If @p buf 262 * with strings of known size, such as eina_stringshare.
271 * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
272 * returned.
273 * 263 *
274 * @see eina_stringshare_length() 264 * @see eina_stringshare_length()
275 * @see eina_ustrbuf_insert() 265 * @see eina_ustrbuf_insert()
@@ -280,14 +270,12 @@ EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode
280/** 270/**
281 * @brief Inserts a slice to a buffer, reallocating as necessary. 271 * @brief Inserts a slice to a buffer, reallocating as necessary.
282 * 272 *
283 * @param buf The string buffer to insert to. 273 * @param buf The string buffer.
284 * @param slice The slice to insert. 274 * @param slice The slice to insert.
285 * @param pos The position to insert the string. 275 * @param pos The position to insert the string.
286 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 276 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be inserted.
287 * 277 *
288 * This function inserts @p slice to @p buf at position @p pos. If @p 278 * This function inserts @p slice to @p buf at position @p pos.
289 * buf can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE
290 * is returned.
291 * 279 *
292 * @since 1.19.0 280 * @since 1.19.0
293 */ 281 */
@@ -297,91 +285,79 @@ EAPI Eina_Bool eina_ustrbuf_insert_slice(Eina_UStrbuf *buf, const Eina_Slice sli
297 * @brief Inserts a character to a string buffer, reallocating as 285 * @brief Inserts a character to a string buffer, reallocating as
298 * necessary. 286 * necessary.
299 * 287 *
300 * @param buf The string buffer to insert to. 288 * @param buf The string buffer.
301 * @param c The char to insert. 289 * @param c The char to insert.
302 * @param pos The position to insert the char. 290 * @param pos The position to insert the char.
303 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 291 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be inserted.
304 * 292 *
305 * This function inserts @p c to @p buf at position @p pos. If @p buf 293 * This function inserts @p c to @p buf at position @p pos.
306 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
307 * returned.
308 */ 294 */
309EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_t pos) EINA_ARG_NONNULL(1); 295EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_t pos) EINA_ARG_NONNULL(1);
310 296
311/** 297/**
312 * @def eina_ustrbuf_prepend(buf, str) 298 * @def eina_ustrbuf_prepend(buf, str)
313 * @brief Prepends the given string to the given buffer. 299 * @brief Prepends a string to the given buffer.
314 * 300 *
315 * @param buf The string buffer to prepend to. 301 * @param buf The string buffer.
316 * @param str The string to prepend. 302 * @param str The string to prepend.
317 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 303 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be prepended.
318 * 304 *
319 * This macro is calling eina_ustrbuf_insert() at position 0. If @p buf 305 * This macro simply calls eina_ustrbuf_insert() with position 0.
320 * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
321 * returned.
322 */ 306 */
323#define eina_ustrbuf_prepend(buf, str) eina_ustrbuf_insert(buf, str, 0) 307#define eina_ustrbuf_prepend(buf, str) eina_ustrbuf_insert(buf, str, 0)
324 308
325/** 309/**
326 * @def eina_ustrbuf_prepend_escaped(buf, str) 310 * @def eina_ustrbuf_prepend_escaped(buf, str)
327 * @brief Prepends the given escaped string to the given buffer. 311 * @brief Prepends an escaped string to the given buffer.
328 * 312 *
329 * @param buf The string buffer to prepend to. 313 * @param buf The string buffer.
330 * @param str The string to prepend. 314 * @param str The string to prepend.
331 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 315 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be prepended.
332 * 316 *
333 * This macro is calling eina_ustrbuf_insert_escaped() at position 0. If 317 * This macro simply calls eina_ustrbuf_insert_escaped() with position 0.
334 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
335 * returned.
336 */ 318 */
337#define eina_ustrbuf_prepend_escaped(buf, str) eina_ustrbuf_insert_escaped(buf, str, 0) 319#define eina_ustrbuf_prepend_escaped(buf, str) eina_ustrbuf_insert_escaped(buf, str, 0)
338 320
339/** 321/**
340 * @def eina_ustrbuf_prepend_n(buf, str) 322 * @def eina_ustrbuf_prepend_n(buf, str)
341 * @brief Prepends the given escaped string to the given buffer. 323 * @brief Prepends an escaped string to the given buffer.
342 * 324 *
343 * @param buf The string buffer to prepend to. 325 * @param buf The string buffer.
344 * @param str The string to prepend. 326 * @param str The string to prepend.
345 * @param maxlen The maximum number of Eina_Unicode *s to prepend. 327 * @param maxlen The maximum number of Eina_Unicode *s to prepend.
346 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 328 * @return #EINA_TRUE on success, #EINA_FALSE if @str could not be prepended.
347 * 329 *
348 * This macro is calling eina_ustrbuf_insert_n() at position 0. If 330 * This macro simply calls eina_ustrbuf_insert_n() with position 0.
349 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
350 * returned.
351 */ 331 */
352#define eina_ustrbuf_prepend_n(buf, str, maxlen) eina_ustrbuf_insert_n(buf, str, maxlen, 0) 332#define eina_ustrbuf_prepend_n(buf, str, maxlen) eina_ustrbuf_insert_n(buf, str, maxlen, 0)
353 333
354/** 334/**
355 * @def eina_ustrbuf_prepend_length(buf, str) 335 * @def eina_ustrbuf_prepend_length(buf, str)
356 * @brief Prepends the given escaped string to the given buffer. 336 * @brief Prepends an escaped string to the given buffer.
357 * 337 *
358 * @param buf The string buffer to prepend to. 338 * @param buf The string buffer.
359 * @param str The string to prepend. 339 * @param str The string to prepend.
360 * @param length The exact length to use. 340 * @param length The exact length to use.
361 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 341 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be prepended.
362 * 342 *
363 * This macro is calling eina_ustrbuf_insert_length() at position 0. If 343 * This macro simply calls eina_ustrbuf_insert_length() with position 0.
364 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
365 * returned.
366 */ 344 */
367#define eina_ustrbuf_prepend_length(buf, str, length) eina_ustrbuf_insert_length(buf, str, length, 0) 345#define eina_ustrbuf_prepend_length(buf, str, length) eina_ustrbuf_insert_length(buf, str, length, 0)
368 346
369/** 347/**
370 * @def eina_ustrbuf_prepend_char(buf, c) 348 * @def eina_ustrbuf_prepend_char(buf, c)
371 * @brief Prepends the given unicode character to the given buffer. 349 * @brief Prepends a unicode character to the given buffer.
372 * 350 *
373 * @param buf The string buffer to prepend to. 351 * @param buf The string buffer.
374 * @param c The Eina_Unicode character to prepend. 352 * @param c The Eina_Unicode character to prepend.
375 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 353 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be prepended.
376 * 354 *
377 * This macro is calling eina_ustrbuf_insert_Eina_Unicode *() at position 0. If 355 * This macro is calling eina_ustrbuf_insert_Eina_Unicode() at position 0.
378 * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
379 * returned.
380 */ 356 */
381#define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0) 357#define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0)
382 358
383/** 359/**
384 * @brief Removes a slice of the given string buffer. 360 * @brief Removes a section of the given string buffer.
385 * 361 *
386 * @param buf The string buffer to remove a slice. 362 * @param buf The string buffer to remove a slice.
387 * @param start The initial (inclusive) slice position to start 363 * @param start The initial (inclusive) slice position to start
@@ -392,7 +368,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
392 * 368 *
393 * This function removes a slice of @p buf, starting at @p start 369 * This function removes a slice of @p buf, starting at @p start
394 * (inclusive) and ending at @p end (non-inclusive). Both values are 370 * (inclusive) and ending at @p end (non-inclusive). Both values are
395 * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. 371 * in bytes.
396 */ 372 */
397EAPI Eina_Bool 373EAPI Eina_Bool
398eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); 374eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
@@ -405,8 +381,8 @@ eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNUL
405 * 381 *
406 * This function returns the string contained in @p buf. The returned 382 * This function returns the string contained in @p buf. The returned
407 * value must not be modified and will no longer be valid if @p buf is 383 * value must not be modified and will no longer be valid if @p buf is
408 * modified. In other words, any eina_ustrbuf_append() or similar will 384 * modified. In other words, calling eina_ustrbuf_append() or similar
409 * make that pointer invalid. 385 * functions will make this pointer invalid.
410 * 386 *
411 * @see eina_ustrbuf_string_steal() 387 * @see eina_ustrbuf_string_steal()
412 */ 388 */
@@ -416,8 +392,8 @@ eina_ustrbuf_string_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_U
416/** 392/**
417 * @brief Steals the contents of a string buffer. 393 * @brief Steals the contents of a string buffer.
418 * 394 *
419 * @param buf The string buffer to steal. 395 * @param buf The string buffer.
420 * @return The current string in the string buffer. 396 * @return The string that was contained in @p buf.
421 * 397 *
422 * This function returns the string contained in @p buf. @p buf is 398 * This function returns the string contained in @p buf. @p buf is
423 * then initialized and does not own the returned string anymore. The 399 * then initialized and does not own the returned string anymore. The
@@ -432,7 +408,7 @@ eina_ustrbuf_string_steal(Eina_UStrbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT
432/** 408/**
433 * @brief Frees the contents of a string buffer but not the buffer. 409 * @brief Frees the contents of a string buffer but not the buffer.
434 * 410 *
435 * @param buf The string buffer to free the string of. 411 * @param buf The string buffer.
436 * 412 *
437 * This function frees the string contained in @p buf without freeing 413 * This function frees the string contained in @p buf without freeing
438 * @p buf. 414 * @p buf.
@@ -441,7 +417,7 @@ EAPI void
441eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); 417eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
442 418
443/** 419/**
444 * @brief Retrieves the length of the string buffer content. 420 * @brief Retrieves the length of the string buffer's content.
445 * 421 *
446 * @param buf The string buffer. 422 * @param buf The string buffer.
447 * @return The current length of the string, in bytes. 423 * @return The current length of the string, in bytes.
@@ -452,35 +428,34 @@ EAPI size_t
452eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 428eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
453 429
454/** 430/**
455 * @brief Gets a read-only slice representing the current ustrbuf contents. 431 * @brief Gets a read-only slice of the buffer contents.
456 * 432 *
457 * @param buf The source string. 433 * @param buf The string buffer.
458 * @return A read-only slice for the current contents. It may become 434 * @return A read-only slice for the current contents. It may become
459 * invalid as soon as the @a buf is changed. 435 * invalid as soon as @a buf is changed.
460 * 436 *
461 * @since 1.19 437 * @since 1.19
462 */ 438 */
463EAPI Eina_Slice eina_ustrbuf_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 439EAPI Eina_Slice eina_ustrbuf_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
464 440
465/** 441/**
466 * @brief Gets a read-write slice representing the current ustrbuf contents. 442 * @brief Gets a read-write slice of the buffer contents.
467 * 443 *
468 * @param buf The source string. 444 * @param buf The string buffer.
469 * @return A read-write slice for the current contents. It may become 445 * @return A read-write slice for the current contents. It may become
470 * invalid as soon as the @a buf is changed with calls such as 446 * invalid as soon as the @p buf is changed, such as through calls like
471 * eina_ustrbuf_append(), eina_ustrbuf_remove() 447 * eina_ustrbuf_append() or eina_ustrbuf_remove().
472 * 448 *
473 * @since 1.19.0 449 * @since 1.19.0
474 */ 450 */
475EAPI Eina_Rw_Slice eina_ustrbuf_rw_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 451EAPI Eina_Rw_Slice eina_ustrbuf_rw_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
476 452
477/** 453/**
478 * @brief Gets the string of the buffer and free the buffer 454 * @brief Frees the buffer, returning its old contents.
479 * 455 *
480 * @param buf The buffer to get the string from and which will be freed 456 * @param buf The string buffer.
481 * 457 * @return The string contained by buf. The caller must release the
482 * @return The string contained by buf. The caller must release the memory of the returned string by calling 458 * memory of the returned string by calling free().
483 * free().
484 * 459 *
485 * @since 1.19 460 * @since 1.19
486 */ 461 */