src/include/eina_ustrbuf.h

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