src/include/eina_binbuf.h

   1 #ifndef EINA_BINBUF_H
   2 #define EINA_BINBUF_H
   3
   4 #include <stddef.h>
   5 #include <stdarg.h>
   6
   7 #include "eina_types.h"
   8
   9 /**
  10  * @addtogroup Eina_Binary_Buffer_Group Binary Buffer
  11  *
  12  * @brief These functions provide string buffers management.
  13  *
  14  * The Binary 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_Binary_Buffer_Group Binary Buffer
  26  *
  27  * @{
  28  */
  29
  30 /**
  31  * @typedef Eina_Binbuf
  32  * Type for a string buffer.
  33  */
  34 typedef struct _Eina_Strbuf Eina_Binbuf;
  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_binbuf_free().
  44  *
  45  * @see eina_binbuf_free()
  46  * @see eina_binbuf_append()
  47  * @see eina_binbuf_string_get()
  48  */
  49 EAPI Eina_Binbuf *eina_binbuf_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_binbuf_string_steal . The passed string must be malloced.
  55  *
  56  * @param str the string to manage
  57  * @param length the length of the string.
  58  * @return Newly allocated string buffer instance.
  59  *
  60  * This function creates a new string buffer. On error, @c NULL is
  61  * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
  62  * free the resources, use eina_binbuf_free().
  63  *
  64  * @see eina_binbuf_manage_new()
  65  * @since 1.2.0
  66  */
  67 EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
  68
  69 /**
  70  * @brief Free a string buffer.
  71  *
  72  * @param buf The string buffer to free.
  73  *
  74  * This function frees the memory of @p buf. @p buf must have been
  75  * created by eina_binbuf_new().
  76  */
  77 EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
  78
  79 /**
  80  * @brief Reset a string buffer.
  81  *
  82  * @param buf The string buffer to reset.
  83  *
  84  * This function reset @p buf: the buffer len is set to 0, and the
  85  * string is set to '\\0'. No memory is free'd.
  86  */
  87 EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
  88
  89 /**
  90  * @brief Append a string of exact length to a buffer, reallocating as necessary.
  91  *
  92  * @param buf The string buffer to append to.
  93  * @param str The string to append.
  94  * @param length The exact length to use.
  95  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
  96  *
  97  * This function appends @p str to @p buf. @p str must be of size at
  98  * most @p length. It is slightly faster than eina_binbuf_append() as
  99  * it does not compute the size of @p str. It is useful when dealing
 100  * with strings of known size, such as eina_strngshare. If @p buf
 101  * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
 102  * returned.
 103  *
 104  * @see eina_stringshare_length()
 105  * @see eina_binbuf_append()
 106  * @see eina_binbuf_append_n()
 107  */
 108 EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1, 2);
 109
 110 /**
 111  * @brief Append a character to a string buffer, reallocating as
 112  * necessary.
 113  *
 114  * @param buf The string buffer to append to.
 115  * @param c The char to append.
 116  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
 117  *
 118  * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE
 119  * is returned, otherwise #EINA_TRUE is returned.
 120  */
 121 EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1);
 122
 123 /**
 124  * @brief Insert a string of exact length to a buffer, reallocating as necessary.
 125  *
 126  * @param buf The string buffer to insert to.
 127  * @param str The string to insert.
 128  * @param length The exact length to use.
 129  * @param pos The position to insert the string.
 130  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
 131  *
 132  * This function inserts @p str to @p buf. @p str must be of size at
 133  * most @p length. It is slightly faster than eina_binbuf_insert() as
 134  * it does not compute the size of @p str. It is useful when dealing
 135  * with strings of known size, such as eina_strngshare. If @p buf
 136  * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
 137  * returned.
 138  *
 139  * @see eina_stringshare_length()
 140  * @see eina_binbuf_insert()
 141  * @see eina_binbuf_insert_n()
 142  */
 143 EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
 144
 145 /**
 146  * @brief Insert a character to a string buffer, reallocating as
 147  * necessary.
 148  *
 149  * @param buf The string buffer to insert to.
 150  * @param c The char to insert.
 151  * @param pos The position to insert the char.
 152  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
 153  *
 154  * This function inserts @p c to @p buf at position @p pos. If @p buf
 155  * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
 156  * returned.
 157  */
 158 EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1);
 159
 160 /**
 161  * @brief Remove a slice of the given string buffer.
 162  *
 163  * @param buf The string buffer to remove a slice.
 164  * @param start The initial (inclusive) slice position to start
 165  *        removing, in bytes.
 166  * @param end The final (non-inclusive) slice position to finish
 167  *        removing, in bytes.
 168  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
 169  *
 170  * This function removes a slice of @p buf, starting at @p start
 171  * (inclusive) and ending at @p end (non-inclusive). Both values are
 172  * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise.
 173  */
 174
 175 EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
 176
 177 /**
 178  * @brief Retrieve a pointer to the contents of a string buffer
 179  *
 180  * @param buf The string buffer.
 181  * @return The current string in the string buffer.
 182  *
 183  * This function returns the string contained in @p buf. The returned
 184  * value must not be modified and will no longer be valid if @p buf is
 185  * modified. In other words, any eina_binbuf_append() or similar will
 186  * make that pointer invalid.
 187  *
 188  * @see eina_binbuf_string_steal()
 189  */
 190 EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 191
 192 /**
 193  * @brief Steal the contents of a string buffer.
 194  *
 195  * @param buf The string buffer to steal.
 196  * @return The current string in the string buffer.
 197  *
 198  * This function returns the string contained in @p buf. @p buf is
 199  * then initialized and does not own the returned string anymore. The
 200  * caller must release the memory of the returned string by calling
 201  * free().
 202  *
 203  * @see eina_binbuf_string_get()
 204  */
 205 EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 206
 207 /**
 208  * @brief Free the contents of a string buffer but not the buffer.
 209  *
 210  * @param buf The string buffer to free the string of.
 211  *
 212  * This function frees the string contained in @p buf without freeing
 213  * @p buf.
 214  */
 215 EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
 216
 217 /**
 218  * @brief Retrieve the length of the string buffer content.
 219  *
 220  * @param buf The string buffer.
 221  * @return The current length of the string, in bytes.
 222  *
 223  * This function returns the length of @p buf.
 224  */
 225 EAPI size_t    eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 226
 227 /**
 228  * @}
 229  */
 230
 231 /**
 232  * @}
 233  */
 234
 235 #endif /* EINA_STRBUF_H */