diff options
Diffstat (limited to 'libraries/eina/src/include/eina_stringshare.h')
-rw-r--r-- | libraries/eina/src/include/eina_stringshare.h | 345 |
1 files changed, 0 insertions, 345 deletions
diff --git a/libraries/eina/src/include/eina_stringshare.h b/libraries/eina/src/include/eina_stringshare.h deleted file mode 100644 index 8edadd2..0000000 --- a/libraries/eina/src/include/eina_stringshare.h +++ /dev/null | |||
@@ -1,345 +0,0 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2002-2008 Carsten Haitzler, Jorge Luis Zapata Muga, Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | * | ||
18 | * This file incorporates work covered by the following copyright and | ||
19 | * permission notice: | ||
20 | * | ||
21 | * Copyright (C) 2008 Peter Wehrfritz | ||
22 | * | ||
23 | * Permission is hereby granted, free of charge, to any person obtaining a copy | ||
24 | * of this software and associated documentation files (the "Software"), to | ||
25 | * deal in the Software without restriction, including without limitation the | ||
26 | * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or | ||
27 | * sell copies of the Software, and to permit persons to whom the Software is | ||
28 | * furnished to do so, subject to the following conditions: | ||
29 | * | ||
30 | * The above copyright notice and this permission notice shall be included in | ||
31 | * all copies of the Software and its Copyright notices. In addition publicly | ||
32 | * documented acknowledgment must be given that this software has been used if no | ||
33 | * source code of this software is made available publicly. This includes | ||
34 | * acknowledgments in either Copyright notices, Manuals, Publicity and Marketing | ||
35 | * documents or any documentation provided with any product containing this | ||
36 | * software. This License does not apply to any software that links to the | ||
37 | * libraries provided by this software (statically or dynamically), but only to | ||
38 | * the software provided. | ||
39 | * | ||
40 | * Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice | ||
41 | * and it's intent. | ||
42 | * | ||
43 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
44 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
45 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL | ||
46 | * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER | ||
47 | * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN | ||
48 | * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | ||
49 | */ | ||
50 | |||
51 | #ifndef EINA_STRINGSHARE_H_ | ||
52 | #define EINA_STRINGSHARE_H_ | ||
53 | |||
54 | #include <stdarg.h> | ||
55 | |||
56 | #include "eina_types.h" | ||
57 | |||
58 | /** | ||
59 | * @page eina_stringshare_example_01_page | ||
60 | * @dontinclude eina_stringshare_01.c | ||
61 | * | ||
62 | * Like all examples we start by including Eina: | ||
63 | * @skip #include | ||
64 | * @line #include | ||
65 | * | ||
66 | * Here we declare some variables and initialize eina: | ||
67 | * @until eina_init | ||
68 | * | ||
69 | * We start the substantive part of the example by showing how to make a part | ||
70 | * of a string shared and how to get the length of a shared string: | ||
71 | * @until stringshare_strlen | ||
72 | * As we add shared strings we also need to delete them when done using them: | ||
73 | * @line del | ||
74 | * | ||
75 | * There are many ways of creating shared strings including an equivalent to | ||
76 | * sprintf: | ||
77 | * @until del | ||
78 | * | ||
79 | * An equivalent to snprintf: | ||
80 | * @until printf | ||
81 | * | ||
82 | * But the simplest way of creating a shared string is through | ||
83 | * eina_stringshare_add(): | ||
84 | * @until printf | ||
85 | * | ||
86 | * Sometimes you already have a pointer to a shared string and want to use it, | ||
87 | * so to make sure the provider of the pointer won't free it while you're using | ||
88 | * it you can increase the shared string's ref count: | ||
89 | * @until printf | ||
90 | * | ||
91 | * Whenever you have a pointer to a shared string and would like to change it's | ||
92 | * value you should use eina_stringshare_replace(): | ||
93 | * @until printf | ||
94 | * @warning @b Don't use eina_stringshare_del() followed by | ||
95 | * eina_share_common_add(), under some circunstances you might end up deleting | ||
96 | * a shared string some other piece of code is using. | ||
97 | * | ||
98 | * We created str but haven't deleted it yet, and while we called | ||
99 | * eina_stringshare_del() on str2, we created it and then increased the ref | ||
100 | * count so it's still alive: | ||
101 | * @until str2 | ||
102 | * | ||
103 | * You can see the full source code @ref eina_stringshare_example_01 "here". | ||
104 | */ | ||
105 | /** | ||
106 | * @page eina_stringshare_example_01 | ||
107 | * @include eina_stringshare_01.c | ||
108 | * @example eina_stringshare_01.c | ||
109 | */ | ||
110 | /** | ||
111 | * @addtogroup Eina_Stringshare_Group Stringshare | ||
112 | * | ||
113 | * These functions allow you to store a single copy of a string, and use in | ||
114 | * multiple places throughout your program. | ||
115 | * | ||
116 | * This is a method to reduce the number of duplicated strings kept in | ||
117 | * memory. It's pretty common for the same strings to be dynamically | ||
118 | * allocated repeatedly between applications and libraries, especially in | ||
119 | * circumstances where you could have multiple copies of a structure that | ||
120 | * allocates the string. So rather than duplicating and freeing these | ||
121 | * strings, you request a read-only pointer to an existing string and | ||
122 | * only incur the overhead of a hash lookup. | ||
123 | * | ||
124 | * It sounds like micro-optimizing, but profiling has shown this can have | ||
125 | * a significant impact as you scale the number of copies up. It improves | ||
126 | * string creation/destruction speed, reduces memory use and decreases | ||
127 | * memory fragmentation, so a win all-around. | ||
128 | * | ||
129 | * Using eina stringshares usually boils down to: | ||
130 | * @code | ||
131 | * const char *str = eina_stringshare_add("My string"); | ||
132 | * ... | ||
133 | * //Use str | ||
134 | * ... | ||
135 | * eina_stringshare_del(str); | ||
136 | * @endcode | ||
137 | * @note It's very important to note that string shares are @b @c const, | ||
138 | * changing them will result in undefined behavior. | ||
139 | * @note eina_stringshare_del() @b doesn't guarantee the string share will be | ||
140 | * freed, it releases a reference to it, but if other references to it still | ||
141 | * exist the string share will live until those are released. | ||
142 | * | ||
143 | * The following diagram gives an idea of what happens as you create strings | ||
144 | * with eina_stringshare_add(): | ||
145 | * | ||
146 | * @image html eina_stringshare.png | ||
147 | * @image latex eina_stringshare.eps height=\textheight | ||
148 | * | ||
149 | * For more information, see @ref eina_stringshare_example_01_page | ||
150 | * "this example". | ||
151 | */ | ||
152 | |||
153 | /** | ||
154 | * @addtogroup Eina_Data_Types_Group Data Types | ||
155 | * | ||
156 | * @{ | ||
157 | */ | ||
158 | |||
159 | /** | ||
160 | * @defgroup Eina_Stringshare_Group Stringshare | ||
161 | * | ||
162 | * @{ | ||
163 | */ | ||
164 | |||
165 | /** | ||
166 | * @typedef Eina_Stringshare | ||
167 | * | ||
168 | * Interchangeable with "const char *" but still a good visual hint for the | ||
169 | * purpose. Maybe in the far far future we'll even add strict type checking. | ||
170 | * | ||
171 | * @since 1.2.0 | ||
172 | */ | ||
173 | typedef const char Eina_Stringshare; | ||
174 | |||
175 | /** | ||
176 | * @brief Retrieve an instance of a string for use in a program. | ||
177 | * | ||
178 | * @param str The string to retrieve an instance of. | ||
179 | * @param slen The string size (<= strlen(str)). | ||
180 | * @return A pointer to an instance of the string on success. | ||
181 | * @c NULL on failure. | ||
182 | * | ||
183 | * This function retrieves an instance of @p str. If @p str is | ||
184 | * @c NULL, then @c NULL is returned. If @p str is already stored, it | ||
185 | * is just returned and its reference counter is increased. Otherwise | ||
186 | * a duplicated string of @p str is returned. | ||
187 | * | ||
188 | * This function does not check string size, but uses the | ||
189 | * exact given size. This can be used to share_common part of a larger | ||
190 | * buffer or substring. | ||
191 | * | ||
192 | * @see eina_share_common_add() | ||
193 | */ | ||
194 | EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT; | ||
195 | |||
196 | /** | ||
197 | * @brief Retrieve an instance of a string for use in a program. | ||
198 | * | ||
199 | * @param str The NULL terminated string to retrieve an instance of. | ||
200 | * @return A pointer to an instance of the string on success. | ||
201 | * @c NULL on failure. | ||
202 | * | ||
203 | * This function retrieves an instance of @p str. If @p str is | ||
204 | * @c NULL, then @c NULL is returned. If @p str is already stored, it | ||
205 | * is just returned and its reference counter is increased. Otherwise | ||
206 | * a duplicated string of @p str is returned. | ||
207 | * | ||
208 | * The string @p str must be NULL terminated ('@\0') and its full | ||
209 | * length will be used. To use part of the string or non-null | ||
210 | * terminated, use eina_stringshare_add_length() instead. | ||
211 | * | ||
212 | * @see eina_stringshare_add_length() | ||
213 | */ | ||
214 | EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT; | ||
215 | |||
216 | /** | ||
217 | * @brief Retrieve an instance of a string for use in a program | ||
218 | * from a format string. | ||
219 | * | ||
220 | * @param fmt The NULL terminated format string to retrieve an instance of. | ||
221 | * @return A pointer to an instance of the string on success. | ||
222 | * @c NULL on failure. | ||
223 | * | ||
224 | * This function retrieves an instance of @p fmt. If @p fmt is | ||
225 | * @c NULL, then @c NULL is returned. If @p fmt is already stored, it | ||
226 | * is just returned and its reference counter is increased. Otherwise | ||
227 | * a duplicated string is returned. | ||
228 | * | ||
229 | * The format string @p fmt must be NULL terminated ('@\0') and its full | ||
230 | * length will be used. To use part of the format string or non-null | ||
231 | * terminated, use eina_stringshare_nprintf() instead. | ||
232 | * | ||
233 | * @see eina_stringshare_nprintf() | ||
234 | */ | ||
235 | EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2); | ||
236 | |||
237 | /** | ||
238 | * @brief Retrieve an instance of a string for use in a program | ||
239 | * from a format string. | ||
240 | * | ||
241 | * @param fmt The NULL terminated format string to retrieve an instance of. | ||
242 | * @param args The va_args for @p fmt | ||
243 | * @return A pointer to an instance of the string on success. | ||
244 | * @c NULL on failure. | ||
245 | * | ||
246 | * This function retrieves an instance of @p fmt with @p args. If @p fmt is | ||
247 | * @c NULL, then @c NULL is returned. If @p fmt with @p args is already stored, it | ||
248 | * is just returned and its reference counter is increased. Otherwise | ||
249 | * a duplicated string is returned. | ||
250 | * | ||
251 | * The format string @p fmt must be NULL terminated ('@\0') and its full | ||
252 | * length will be used. To use part of the format string or non-null | ||
253 | * terminated, use eina_stringshare_nprintf() instead. | ||
254 | * | ||
255 | * @see eina_stringshare_nprintf() | ||
256 | */ | ||
257 | EAPI Eina_Stringshare *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT; | ||
258 | |||
259 | /** | ||
260 | * @brief Retrieve an instance of a string for use in a program | ||
261 | * from a format string with size limitation. | ||
262 | * @param len The length of the format string to use | ||
263 | * @param fmt The format string to retrieve an instance of. | ||
264 | * @return A pointer to an instance of the string on success. | ||
265 | * @c NULL on failure. | ||
266 | * | ||
267 | * This function retrieves an instance of @p fmt limited by @p len. If @p fmt is | ||
268 | * @c NULL or @p len is < 1, then @c NULL is returned. If the resulting string | ||
269 | * is already stored, it is returned and its reference counter is increased. | ||
270 | * Otherwise a duplicated string is returned. | ||
271 | * | ||
272 | * @p len length of the format string will be used. To use the | ||
273 | * entire format string, use eina_stringshare_printf() instead. | ||
274 | * | ||
275 | * @see eina_stringshare_printf() | ||
276 | */ | ||
277 | EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(2, 3); | ||
278 | |||
279 | /** | ||
280 | * Increment references of the given shared string. | ||
281 | * | ||
282 | * @param str The shared string. | ||
283 | * @return A pointer to an instance of the string on success. | ||
284 | * @c NULL on failure. | ||
285 | * | ||
286 | * This is similar to eina_share_common_add(), but it's faster since it will | ||
287 | * avoid lookups if possible, but on the down side it requires the parameter | ||
288 | * to be shared string. In other words, it must be the return of a previous | ||
289 | * call to one of the stringshare functions. | ||
290 | * | ||
291 | * There is no unref since this is the work of eina_share_common_del(). | ||
292 | */ | ||
293 | EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str); | ||
294 | |||
295 | /** | ||
296 | * @brief Note that the given string has lost an instance. | ||
297 | * | ||
298 | * @param str string The given string. | ||
299 | * | ||
300 | * This function decreases the reference counter associated to @p str | ||
301 | * if it exists. If that counter reaches 0, the memory associated to | ||
302 | * @p str is freed. If @p str is NULL, the function returns | ||
303 | * immediately. | ||
304 | * | ||
305 | * Note that if the given pointer is not shared or NULL, bad things | ||
306 | * will happen, likely a segmentation fault. | ||
307 | */ | ||
308 | EAPI void eina_stringshare_del(Eina_Stringshare *str); | ||
309 | |||
310 | /** | ||
311 | * @brief Note that the given string @b must be shared. | ||
312 | * | ||
313 | * @param str the shared string to know the length. It is safe to | ||
314 | * give NULL, in that case -1 is returned. | ||
315 | * @return The length of a shared string. | ||
316 | * | ||
317 | * This function is a cheap way to known the length of a shared | ||
318 | * string. Note that if the given pointer is not shared, bad | ||
319 | * things will happen, likely a segmentation fault. If in doubt, try | ||
320 | * strlen(). | ||
321 | */ | ||
322 | EAPI int eina_stringshare_strlen(Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
323 | |||
324 | /** | ||
325 | * @brief Dump the contents of the share_common. | ||
326 | * | ||
327 | * This function dumps all strings in the share_common to stdout with a | ||
328 | * DDD: prefix per line and a memory usage summary. | ||
329 | */ | ||
330 | EAPI void eina_stringshare_dump(void); | ||
331 | |||
332 | static inline Eina_Bool eina_stringshare_replace(Eina_Stringshare **p_str, const char *news) EINA_ARG_NONNULL(1); | ||
333 | static inline Eina_Bool eina_stringshare_replace_length(Eina_Stringshare **p_str, const char *news, unsigned int slen) EINA_ARG_NONNULL(1); | ||
334 | |||
335 | #include "eina_inline_stringshare.x" | ||
336 | |||
337 | /** | ||
338 | * @} | ||
339 | */ | ||
340 | |||
341 | /** | ||
342 | * @} | ||
343 | */ | ||
344 | |||
345 | #endif /* EINA_STRINGSHARE_H_ */ | ||