src/include/eina_ustringshare.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_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  */
 112 EAPI 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  */
 133 EAPI 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  */
 149 EAPI 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 @c NULL, the function returns
 159  * immediately.
 160  *
 161  * @note If the given pointer is not shared, bad things will happen, likely a
 162  * segmentation fault.
 163  */
 164 EAPI 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 @c NULL, in that case @c -1 is returned.
 171  *
 172  * This function is a cheap way to known the length of a shared
 173  * string.
 174  *
 175  * @note If the given pointer is not shared, bad things will happen, likely a
 176  * segmentation fault. If in doubt, try strlen().
 177  */
 178 EAPI int                 eina_ustringshare_strlen(const Eina_Unicode *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
 179
 180 /**
 181  * @brief Dump the contents of the share_common.
 182  *
 183  * This function dumps all strings in the share_common to stdout with a
 184  * DDD: prefix per line and a memory usage summary.
 185  */
 186 EAPI void                eina_ustringshare_dump(void);
 187
 188 static inline Eina_Bool  eina_ustringshare_replace(const Eina_Unicode **p_str, const Eina_Unicode *news) EINA_ARG_NONNULL(1);
 189 static inline Eina_Bool  eina_ustringshare_replace_length(const Eina_Unicode **p_str, const Eina_Unicode *news, unsigned int slen) EINA_ARG_NONNULL(1);
 190
 191 #include "eina_inline_ustringshare.x"
 192
 193 /**
 194  * @}
 195  */
 196
 197 /**
 198  * @}
 199  */
 200
 201 #endif /* EINA_STRINGSHARE_H_ */