aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_binbuf.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_binbuf.h')
-rw-r--r--libraries/eina/src/include/eina_binbuf.h235
1 files changed, 0 insertions, 235 deletions
diff --git a/libraries/eina/src/include/eina_binbuf.h b/libraries/eina/src/include/eina_binbuf.h
deleted file mode 100644
index 7c3524b..0000000
--- a/libraries/eina/src/include/eina_binbuf.h
+++ /dev/null
@@ -1,235 +0,0 @@
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 */
34typedef 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 */
49EAPI 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 */
67EAPI 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 */
77EAPI 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 */
87EAPI 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 */
108EAPI 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,
119 * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
120 */
121EAPI 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 */
143EAPI 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 */
158EAPI 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
175EAPI 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 */
190EAPI 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 */
205EAPI 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 */
215EAPI 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 */
225EAPI 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 */