aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_stringshare.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_stringshare.h')
-rw-r--r--libraries/eina/src/include/eina_stringshare.h345
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 */
173typedef 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 */
194EAPI 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 */
214EAPI 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 */
235EAPI 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 */
257EAPI 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 */
277EAPI 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 */
293EAPI 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 */
308EAPI 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 */
322EAPI 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 */
330EAPI void eina_stringshare_dump(void);
331
332static inline Eina_Bool eina_stringshare_replace(Eina_Stringshare **p_str, const char *news) EINA_ARG_NONNULL(1);
333static 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_ */