diff options
author | David Walter Seikel | 2012-04-22 09:19:23 +1000 |
---|---|---|
committer | David Walter Seikel | 2012-04-22 09:19:23 +1000 |
commit | c963d75dfdeec11f82e79e727062fbf89afa2c04 (patch) | |
tree | 895633dbf641110be46f117c29890c49b3ffc0bd /libraries/eina/src/include/eina_stringshare.h | |
parent | Adding the new extantz viewer and grid manager. (diff) | |
download | SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.zip SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.tar.gz SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.tar.bz2 SledjHamr-c963d75dfdeec11f82e79e727062fbf89afa2c04.tar.xz |
Update EFL to latest beta.
Diffstat (limited to 'libraries/eina/src/include/eina_stringshare.h')
-rw-r--r-- | libraries/eina/src/include/eina_stringshare.h | 43 |
1 files changed, 33 insertions, 10 deletions
diff --git a/libraries/eina/src/include/eina_stringshare.h b/libraries/eina/src/include/eina_stringshare.h index 862b2b2..8edadd2 100644 --- a/libraries/eina/src/include/eina_stringshare.h +++ b/libraries/eina/src/include/eina_stringshare.h | |||
@@ -126,6 +126,20 @@ | |||
126 | * string creation/destruction speed, reduces memory use and decreases | 126 | * string creation/destruction speed, reduces memory use and decreases |
127 | * memory fragmentation, so a win all-around. | 127 | * memory fragmentation, so a win all-around. |
128 | * | 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 | * | ||
129 | * The following diagram gives an idea of what happens as you create strings | 143 | * The following diagram gives an idea of what happens as you create strings |
130 | * with eina_stringshare_add(): | 144 | * with eina_stringshare_add(): |
131 | * | 145 | * |
@@ -148,6 +162,15 @@ | |||
148 | * @{ | 162 | * @{ |
149 | */ | 163 | */ |
150 | 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; | ||
151 | 174 | ||
152 | /** | 175 | /** |
153 | * @brief Retrieve an instance of a string for use in a program. | 176 | * @brief Retrieve an instance of a string for use in a program. |
@@ -168,7 +191,7 @@ | |||
168 | * | 191 | * |
169 | * @see eina_share_common_add() | 192 | * @see eina_share_common_add() |
170 | */ | 193 | */ |
171 | EAPI const char *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT; | 194 | EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT; |
172 | 195 | ||
173 | /** | 196 | /** |
174 | * @brief Retrieve an instance of a string for use in a program. | 197 | * @brief Retrieve an instance of a string for use in a program. |
@@ -188,7 +211,7 @@ EAPI const char *eina_stringshare_add_length(const char *str, unsigned in | |||
188 | * | 211 | * |
189 | * @see eina_stringshare_add_length() | 212 | * @see eina_stringshare_add_length() |
190 | */ | 213 | */ |
191 | EAPI const char *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT; | 214 | EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT; |
192 | 215 | ||
193 | /** | 216 | /** |
194 | * @brief Retrieve an instance of a string for use in a program | 217 | * @brief Retrieve an instance of a string for use in a program |
@@ -209,7 +232,7 @@ EAPI const char *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_R | |||
209 | * | 232 | * |
210 | * @see eina_stringshare_nprintf() | 233 | * @see eina_stringshare_nprintf() |
211 | */ | 234 | */ |
212 | EAPI const char *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2); | 235 | EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2); |
213 | 236 | ||
214 | /** | 237 | /** |
215 | * @brief Retrieve an instance of a string for use in a program | 238 | * @brief Retrieve an instance of a string for use in a program |
@@ -231,7 +254,7 @@ EAPI const char *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_ | |||
231 | * | 254 | * |
232 | * @see eina_stringshare_nprintf() | 255 | * @see eina_stringshare_nprintf() |
233 | */ | 256 | */ |
234 | EAPI const char *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT; | 257 | EAPI Eina_Stringshare *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT; |
235 | 258 | ||
236 | /** | 259 | /** |
237 | * @brief Retrieve an instance of a string for use in a program | 260 | * @brief Retrieve an instance of a string for use in a program |
@@ -251,7 +274,7 @@ EAPI const char *eina_stringshare_vprintf(const char *fmt, va_list args) | |||
251 | * | 274 | * |
252 | * @see eina_stringshare_printf() | 275 | * @see eina_stringshare_printf() |
253 | */ | 276 | */ |
254 | EAPI const char *eina_stringshare_nprintf(unsigned int len, const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(2, 3); | 277 | EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(2, 3); |
255 | 278 | ||
256 | /** | 279 | /** |
257 | * Increment references of the given shared string. | 280 | * Increment references of the given shared string. |
@@ -267,7 +290,7 @@ EAPI const char *eina_stringshare_nprintf(unsigned int len, const char *f | |||
267 | * | 290 | * |
268 | * There is no unref since this is the work of eina_share_common_del(). | 291 | * There is no unref since this is the work of eina_share_common_del(). |
269 | */ | 292 | */ |
270 | EAPI const char *eina_stringshare_ref(const char *str); | 293 | EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str); |
271 | 294 | ||
272 | /** | 295 | /** |
273 | * @brief Note that the given string has lost an instance. | 296 | * @brief Note that the given string has lost an instance. |
@@ -282,7 +305,7 @@ EAPI const char *eina_stringshare_ref(const char *str); | |||
282 | * Note that if the given pointer is not shared or NULL, bad things | 305 | * Note that if the given pointer is not shared or NULL, bad things |
283 | * will happen, likely a segmentation fault. | 306 | * will happen, likely a segmentation fault. |
284 | */ | 307 | */ |
285 | EAPI void eina_stringshare_del(const char *str); | 308 | EAPI void eina_stringshare_del(Eina_Stringshare *str); |
286 | 309 | ||
287 | /** | 310 | /** |
288 | * @brief Note that the given string @b must be shared. | 311 | * @brief Note that the given string @b must be shared. |
@@ -296,7 +319,7 @@ EAPI void eina_stringshare_del(const char *str); | |||
296 | * things will happen, likely a segmentation fault. If in doubt, try | 319 | * things will happen, likely a segmentation fault. If in doubt, try |
297 | * strlen(). | 320 | * strlen(). |
298 | */ | 321 | */ |
299 | EAPI int eina_stringshare_strlen(const char *str) EINA_PURE EINA_WARN_UNUSED_RESULT; | 322 | EAPI int eina_stringshare_strlen(Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT; |
300 | 323 | ||
301 | /** | 324 | /** |
302 | * @brief Dump the contents of the share_common. | 325 | * @brief Dump the contents of the share_common. |
@@ -306,8 +329,8 @@ EAPI int eina_stringshare_strlen(const char *str) EINA_PURE EINA_ | |||
306 | */ | 329 | */ |
307 | EAPI void eina_stringshare_dump(void); | 330 | EAPI void eina_stringshare_dump(void); |
308 | 331 | ||
309 | static inline Eina_Bool eina_stringshare_replace(const char **p_str, const char *news) EINA_ARG_NONNULL(1); | 332 | static inline Eina_Bool eina_stringshare_replace(Eina_Stringshare **p_str, const char *news) EINA_ARG_NONNULL(1); |
310 | static inline Eina_Bool eina_stringshare_replace_length(const char **p_str, const char *news, unsigned int slen) 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); |
311 | 334 | ||
312 | #include "eina_inline_stringshare.x" | 335 | #include "eina_inline_stringshare.x" |
313 | 336 | ||