aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_ustringshare.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_ustringshare.h')
-rw-r--r--libraries/eina/src/include/eina_ustringshare.h200
1 files changed, 200 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_ustringshare.h b/libraries/eina/src/include/eina_ustringshare.h
new file mode 100644
index 0000000..1036573
--- /dev/null
+++ b/libraries/eina/src/include/eina_ustringshare.h
@@ -0,0 +1,200 @@
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_USTRINGSHARE_H_
52#define EINA_USTRINGSHARE_H_
53
54#include "eina_types.h"
55#include "eina_unicode.h"
56
57/**
58 * @addtogroup Eina_UStringshare_Group Unicode Stringshare
59 *
60 * These functions allow you to store one copy of a string, and use it
61 * throughout your program.
62 *
63 * This is a method to reduce the number of duplicated strings kept in
64 * memory. It's pretty common for the same strings to be dynamically
65 * allocated repeatedly between applications and libraries, especially in
66 * circumstances where you could have multiple copies of a structure that
67 * allocates the string. So rather than duplicating and freeing these
68 * strings, you request a read-only pointer to an existing string and
69 * only incur the overhead of a hash lookup.
70 *
71 * It sounds like micro-optimizing, but profiling has shown this can have
72 * a significant impact as you scale the number of copies up. It improves
73 * string creation/destruction speed, reduces memory use and decreases
74 * memory fragmentation, so a win all-around.
75 *
76 * For more information, you can look at the @ref tutorial_ustringshare_page.
77 */
78
79/**
80 * @addtogroup Eina_Data_Types_Group Data Types
81 *
82 * @{
83 */
84
85/**
86 * @defgroup Eina_UStringshare_Group Unicode Stringshare
87 *
88 * @{
89 */
90
91
92/**
93 * @brief Retrieve an instance of a string for use in a program.
94 *
95 * @param str The string to retrieve an instance of.
96 * @param slen The string size (<= strlen(str)).
97 * @return A pointer to an instance of the string on success.
98 * @c NULL on failure.
99 *
100 * This function retrieves an instance of @p str. If @p str is
101 * @c NULL, then @c NULL is returned. If @p str is already stored, it
102 * is just returned and its reference counter is increased. Otherwise
103 * it is added to the strings to be searched and a duplicated string
104 * of @p str is returned.
105 *
106 * This function does not check string size, but uses the
107 * exact given size. This can be used to share_common part of a larger
108 * buffer or substring.
109 *
110 * @see eina_ustringshare_add()
111 */
112EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, unsigned int slen) EINA_WARN_UNUSED_RESULT;
113
114/**
115 * @brief Retrieve an instance of a string for use in a program.
116 *
117 * @param str The NULL terminated string to retrieve an instance of.
118 * @return A pointer to an instance of the string on success.
119 * @c NULL on failure.
120 *
121 * This function retrieves an instance of @p str. If @p str is
122 * @c NULL, then @c NULL is returned. If @p str is already stored, it
123 * is just returned and its reference counter is increased. Otherwise
124 * it is added to the strings to be searched and a duplicated string
125 * of @p str is returned.
126 *
127 * The string @p str must be NULL terminated ('@\0') and its full
128 * length will be used. To use part of the string or non-null
129 * terminated, use eina_stringshare_add_length() instead.
130 *
131 * @see eina_ustringshare_add_length()
132 */
133EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WARN_UNUSED_RESULT;
134
135/**
136 * Increment references of the given shared string.
137 *
138 * @param str The shared string.
139 * @return A pointer to an instance of the string on success.
140 * @c NULL on failure.
141 *
142 * This is similar to eina_share_common_add(), but it's faster since it will
143 * avoid lookups if possible, but on the down side it requires the parameter
144 * to be shared before, in other words, it must be the return of a previous
145 * eina_ustringshare_add().
146 *
147 * There is no unref since this is the work of eina_ustringshare_del().
148 */
149EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str);
150
151/**
152 * @brief Note that the given string has lost an instance.
153 *
154 * @param str string The given string.
155 *
156 * This function decreases the reference counter associated to @p str
157 * if it exists. If that counter reaches 0, the memory associated to
158 * @p str is freed. If @p str is NULL, the function returns
159 * immediately.
160 *
161 * Note that if the given pointer is not shared or NULL, bad things
162 * will happen, likely a segmentation fault.
163 */
164EAPI void eina_ustringshare_del(const Eina_Unicode *str);
165
166/**
167 * @brief Note that the given string @b must be shared.
168 *
169 * @param str the shared string to know the length. It is safe to
170 * give NULL, in that case -1 is returned.
171 *
172 * This function is a cheap way to known the length of a shared
173 * string. Note that if the given pointer is not shared, bad
174 * things will happen, likely a segmentation fault. If in doubt, try
175 * strlen().
176 */
177EAPI int eina_ustringshare_strlen(const Eina_Unicode *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
178
179/**
180 * @brief Dump the contents of the share_common.
181 *
182 * This function dumps all strings in the share_common to stdout with a
183 * DDD: prefix per line and a memory usage summary.
184 */
185EAPI void eina_ustringshare_dump(void);
186
187static inline Eina_Bool eina_ustringshare_replace(const Eina_Unicode **p_str, const Eina_Unicode *news) EINA_ARG_NONNULL(1);
188static inline Eina_Bool eina_ustringshare_replace_length(const Eina_Unicode **p_str, const Eina_Unicode *news, unsigned int slen) EINA_ARG_NONNULL(1);
189
190#include "eina_inline_ustringshare.x"
191
192/**
193 * @}
194 */
195
196/**
197 * @}
198 */
199
200#endif /* EINA_STRINGSHARE_H_ */