src/include/eina_stringshare.h

   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 @c NULL, the function returns
 303  * immediately.
 304  *
 305  * @note If the given pointer is not shared, bad things will happen, likely a
 306  * 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 @c NULL, in that case @c -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.
 319  *
 320  * @note If the given pointer is not shared, bad things will happen, likely a
 321  * segmentation fault. If in doubt, try strlen().
 322  */
 323 EAPI int                eina_stringshare_strlen(Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
 324
 325 /**
 326  * @brief Dump the contents of the share_common.
 327  *
 328  * This function dumps all strings in the share_common to stdout with a
 329  * DDD: prefix per line and a memory usage summary.
 330  */
 331 EAPI void               eina_stringshare_dump(void);
 332
 333 static inline Eina_Bool eina_stringshare_replace(Eina_Stringshare **p_str, const char *news) EINA_ARG_NONNULL(1);
 334 static inline Eina_Bool eina_stringshare_replace_length(Eina_Stringshare **p_str, const char *news, unsigned int slen) EINA_ARG_NONNULL(1);
 335
 336 #include "eina_inline_stringshare.x"
 337
 338 /**
 339  * @}
 340  */
 341
 342 /**
 343  * @}
 344  */
 345
 346 #endif /* EINA_STRINGSHARE_H_ */