#include "eina_types.h"
/**
+ * @addtogroup Eina_Stringshare_Group Stringshare
+ *
+ * These functions allow you to store one copy of a string, and use it
+ * throughout your program.
+ *
+ * This is a method to reduce the number of duplicated strings kept in
+ * memory. It's pretty common for the same strings to be dynamically
+ * allocated repeatedly between applications and libraries, especially in
+ * circumstances where you could have multiple copies of a structure that
+ * allocates the string. So rather than duplicating and freeing these
+ * strings, you request a read-only pointer to an existing string and
+ * only incur the overhead of a hash lookup.
+ *
+ * It sounds like micro-optimizing, but profiling has shown this can have
+ * a significant impact as you scale the number of copies up. It improves
+ * string creation/destruction speed, reduces memory use and decreases
+ * memory fragmentation, so a win all-around.
+ *
+ * For more information, you can look at the @ref tutorial_stringshare_page.
+ *
+ * @{
+ */
+
+/**
* @addtogroup Eina_Data_Types_Group Data Types
*
* @{
* @{
*/
+
+/**
+ * @brief Retrieve an instance of a string for use in a program.
+ *
+ * @param str The string to retrieve an instance of.
+ * @param slen The string size (<= strlen(str)).
+ * @return A pointer to an instance of the string on success.
+ * @c NULL on failure.
+ *
+ * This function retrieves an instance of @p str. If @p str is
+ * @c NULL, then @c NULL is returned. If @p str is already stored, it
+ * is just returned and its reference counter is increased. Otherwise
+ * it is added to the strings to be searched and a duplicated string
+ * of @p str is returned.
+ *
+ * This function does not check string size, but uses the
+ * exact given size. This can be used to share_common part of a larger
+ * buffer or substring.
+ *
+ * @see eina_share_common_add()
+ */
EAPI const char *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Retrieve an instance of a string for use in a program.
+ *
+ * @param str The NULL terminated string to retrieve an instance of.
+ * @return A pointer to an instance of the string on success.
+ * @c NULL on failure.
+ *
+ * This function retrieves an instance of @p str. If @p str is
+ * @c NULL, then @c NULL is returned. If @p str is already stored, it
+ * is just returned and its reference counter is increased. Otherwise
+ * it is added to the strings to be searched and a duplicated string
+ * of @p str is returned.
+ *
+ * The string @p str must be NULL terminated ('@\0') and its full
+ * length will be used. To use part of the string or non-null
+ * terminated, use eina_stringshare_add_length() instead.
+ *
+ * @see eina_stringshare_add_length()
+ */
EAPI const char *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Retrieve an instance of a string for use in a program
+ * from a format string.
+ *
+ * @param fmt The NULL terminated format string to retrieve an instance of.
+ * @return A pointer to an instance of the string on success.
+ * @c NULL on failure.
+ *
+ * This function retrieves an instance of @p fmt. If @p fmt is
+ * @c NULL, then @c NULL is returned. If @p fmt is already stored, it
+ * is just returned and its reference counter is increased. Otherwise
+ * it is added to the strings to be searched and a duplicated string
+ * is returned.
+ *
+ * The format string @p fmt must be NULL terminated ('@\0') and its full
+ * length will be used. To use part of the format string or non-null
+ * terminated, use eina_stringshare_nprintf() instead.
+ *
+ * @see eina_stringshare_nprintf()
+ */
EAPI const char *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2);
+
+/**
+ * @brief Retrieve an instance of a string for use in a program
+ * from a format string.
+ *
+ * @param fmt The NULL terminated format string to retrieve an instance of.
+ * @param args The va_args for @p fmt
+ * @return A pointer to an instance of the string on success.
+ * @c NULL on failure.
+ *
+ * This function retrieves an instance of @p fmt with @p args. If @p fmt is
+ * @c NULL, then @c NULL is returned. If @p fmt with @p args is already stored, it
+ * is just returned and its reference counter is increased. Otherwise
+ * it is added to the strings to be searched and a duplicated string
+ * is returned.
+ *
+ * The format string @p fmt must be NULL terminated ('@\0') and its full
+ * length will be used. To use part of the format string or non-null
+ * terminated, use eina_stringshare_nprintf() instead.
+ *
+ * @see eina_stringshare_nprintf()
+ */
EAPI const char *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Retrieve an instance of a string for use in a program
+ * from a format string with size limitation.
+ * @param len The length of the format string to use
+ * @param fmt The format string to retrieve an instance of.
+ * @return A pointer to an instance of the string on success.
+ * @c NULL on failure.
+ *
+ * This function retrieves an instance of @p fmt limited by @p len. If @p fmt is
+ * @c NULL or @p len is < 1, then @c NULL is returned. If the resulting string
+ * is already stored, it is returned and its reference counter is increased. Otherwise
+ * it is added to the strings to be searched and a duplicated string
+ * is returned.
+ *
+ * @p len length of the format string will be used. To use the
+ * entire format string, use eina_stringshare_printf() instead.
+ *
+ * @see eina_stringshare_printf()
+ */
EAPI const char *eina_stringshare_nprintf(unsigned int len, const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(2, 3);
+
+/**
+ * Increment references of the given shared string.
+ *
+ * @param str The shared string.
+ * @return A pointer to an instance of the string on success.
+ * @c NULL on failure.
+ *
+ * This is similar to eina_share_common_add(), but it's faster since it will
+ * avoid lookups if possible, but on the down side it requires the parameter
+ * to be shared before, in other words, it must be the return of a previous
+ * eina_share_common_add().
+ *
+ * There is no unref since this is the work of eina_share_common_del().
+ */
EAPI const char *eina_stringshare_ref(const char *str);
+
+/**
+ * @brief Note that the given string has lost an instance.
+ *
+ * @param str string The given string.
+ *
+ * This function decreases the reference counter associated to @p str
+ * if it exists. If that counter reaches 0, the memory associated to
+ * @p str is freed. If @p str is NULL, the function returns
+ * immediately.
+ *
+ * Note that if the given pointer is not shared or NULL, bad things
+ * will happen, likely a segmentation fault.
+ */
EAPI void eina_stringshare_del(const char *str);
+
+/**
+ * @brief Note that the given string @b must be shared.
+ *
+ * @param str the shared string to know the length. It is safe to
+ * give NULL, in that case -1 is returned.
+ *
+ * This function is a cheap way to known the length of a shared
+ * string. Note that if the given pointer is not shared, bad
+ * things will happen, likely a segmentation fault. If in doubt, try
+ * strlen().
+ */
EAPI int eina_stringshare_strlen(const char *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Dump the contents of the share_common.
+ *
+ * This function dumps all strings in the share_common to stdout with a
+ * DDD: prefix per line and a memory usage summary.
+ */
EAPI void eina_stringshare_dump(void);
static inline Eina_Bool eina_stringshare_replace(const char **p_str, const char *news) EINA_ARG_NONNULL(1);
* @}
*/
+/**
+ * @}
+ */
+
#endif /* EINA_STRINGSHARE_H_ */
* if not, see <http://www.gnu.org/licenses/>.
*/
-/**
- * @page tutorial_stringshare_page Stringshare Tutorial
- *
- * to be written...
- *
- */
-
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
* API *
*============================================================================*/
-/**
- * @addtogroup Eina_Stringshare_Group Stringshare
- *
- * These functions allow you to store one copy of a string, and use it
- * throughout your program.
- *
- * This is a method to reduce the number of duplicated strings kept in
- * memory. It's pretty common for the same strings to be dynamically
- * allocated repeatedly between applications and libraries, especially in
- * circumstances where you could have multiple copies of a structure that
- * allocates the string. So rather than duplicating and freeing these
- * strings, you request a read-only pointer to an existing string and
- * only incur the overhead of a hash lookup.
- *
- * It sounds like micro-optimizing, but profiling has shown this can have
- * a significant impact as you scale the number of copies up. It improves
- * string creation/destruction speed, reduces memory use and decreases
- * memory fragmentation, so a win all-around.
- *
- * For more information, you can look at the @ref tutorial_stringshare_page.
- *
- * @{
- */
-
-/**
- * @brief Note that the given string has lost an instance.
- *
- * @param str string The given string.
- *
- * This function decreases the reference counter associated to @p str
- * if it exists. If that counter reaches 0, the memory associated to
- * @p str is freed. If @p str is NULL, the function returns
- * immediately.
- *
- * Note that if the given pointer is not shared or NULL, bad things
- * will happen, likely a segmentation fault.
- */
EAPI void
eina_stringshare_del(const char *str)
{
eina_share_common_del(stringshare_share, str);
}
-/**
- * @brief Retrieve an instance of a string for use in a program.
- *
- * @param str The string to retrieve an instance of.
- * @param slen The string size (<= strlen(str)).
- * @return A pointer to an instance of the string on success.
- * @c NULL on failure.
- *
- * This function retrieves an instance of @p str. If @p str is
- * @c NULL, then @c NULL is returned. If @p str is already stored, it
- * is just returned and its reference counter is increased. Otherwise
- * it is added to the strings to be searched and a duplicated string
- * of @p str is returned.
- *
- * This function does not check string size, but uses the
- * exact given size. This can be used to share_common part of a larger
- * buffer or substring.
- *
- * @see eina_share_common_add()
- */
EAPI const char *
eina_stringshare_add_length(const char *str, unsigned int slen)
{
sizeof(char), sizeof(char));
}
-/**
- * @brief Retrieve an instance of a string for use in a program.
- *
- * @param str The NULL terminated string to retrieve an instance of.
- * @return A pointer to an instance of the string on success.
- * @c NULL on failure.
- *
- * This function retrieves an instance of @p str. If @p str is
- * @c NULL, then @c NULL is returned. If @p str is already stored, it
- * is just returned and its reference counter is increased. Otherwise
- * it is added to the strings to be searched and a duplicated string
- * of @p str is returned.
- *
- * The string @p str must be NULL terminated ('@\0') and its full
- * length will be used. To use part of the string or non-null
- * terminated, use eina_stringshare_add_length() instead.
- *
- * @see eina_stringshare_add_length()
- */
EAPI const char *
eina_stringshare_add(const char *str)
{
return eina_stringshare_add_length(str, slen);
}
-/**
- * @brief Retrieve an instance of a string for use in a program
- * from a format string.
- *
- * @param fmt The NULL terminated format string to retrieve an instance of.
- * @return A pointer to an instance of the string on success.
- * @c NULL on failure.
- *
- * This function retrieves an instance of @p fmt. If @p fmt is
- * @c NULL, then @c NULL is returned. If @p fmt is already stored, it
- * is just returned and its reference counter is increased. Otherwise
- * it is added to the strings to be searched and a duplicated string
- * is returned.
- *
- * The format string @p fmt must be NULL terminated ('@\0') and its full
- * length will be used. To use part of the format string or non-null
- * terminated, use eina_stringshare_nprintf() instead.
- *
- * @see eina_stringshare_nprintf()
- */
EAPI const char *
eina_stringshare_printf(const char *fmt, ...)
{
return ret;
}
-/**
- * @brief Retrieve an instance of a string for use in a program
- * from a format string.
- *
- * @param fmt The NULL terminated format string to retrieve an instance of.
- * @param args The va_args for @p fmt
- * @return A pointer to an instance of the string on success.
- * @c NULL on failure.
- *
- * This function retrieves an instance of @p fmt with @p args. If @p fmt is
- * @c NULL, then @c NULL is returned. If @p fmt with @p args is already stored, it
- * is just returned and its reference counter is increased. Otherwise
- * it is added to the strings to be searched and a duplicated string
- * is returned.
- *
- * The format string @p fmt must be NULL terminated ('@\0') and its full
- * length will be used. To use part of the format string or non-null
- * terminated, use eina_stringshare_nprintf() instead.
- *
- * @see eina_stringshare_nprintf()
- */
EAPI const char *
eina_stringshare_vprintf(const char *fmt, va_list args)
{
return ret;
}
-/**
- * @brief Retrieve an instance of a string for use in a program
- * from a format string with size limitation.
- * @param len The length of the format string to use
- * @param fmt The format string to retrieve an instance of.
- * @return A pointer to an instance of the string on success.
- * @c NULL on failure.
- *
- * This function retrieves an instance of @p fmt limited by @p len. If @p fmt is
- * @c NULL or @p len is < 1, then @c NULL is returned. If the resulting string
- * is already stored, it is returned and its reference counter is increased. Otherwise
- * it is added to the strings to be searched and a duplicated string
- * is returned.
- *
- * @p len length of the format string will be used. To use the
- * entire format string, use eina_stringshare_printf() instead.
- *
- * @see eina_stringshare_printf()
- */
EAPI const char *
eina_stringshare_nprintf(unsigned int len, const char *fmt, ...)
{
return eina_stringshare_add_length(tmp, len);
}
-/**
- * Increment references of the given shared string.
- *
- * @param str The shared string.
- * @return A pointer to an instance of the string on success.
- * @c NULL on failure.
- *
- * This is similar to eina_share_common_add(), but it's faster since it will
- * avoid lookups if possible, but on the down side it requires the parameter
- * to be shared before, in other words, it must be the return of a previous
- * eina_share_common_add().
- *
- * There is no unref since this is the work of eina_share_common_del().
- */
EAPI const char *
eina_stringshare_ref(const char *str)
{
return eina_share_common_ref(stringshare_share, str);
}
-/**
- * @brief Note that the given string @b must be shared.
- *
- * @param str the shared string to know the length. It is safe to
- * give NULL, in that case -1 is returned.
- *
- * This function is a cheap way to known the length of a shared
- * string. Note that if the given pointer is not shared, bad
- * things will happen, likely a segmentation fault. If in doubt, try
- * strlen().
- */
EAPI int
eina_stringshare_strlen(const char *str)
{
return len;
}
-/**
- * @brief Dump the contents of the share_common.
- *
- * This function dumps all strings in the share_common to stdout with a
- * DDD: prefix per line and a memory usage summary.
- */
EAPI void
eina_stringshare_dump(void)
{
_eina_stringshare_small_dump,
sizeof(_eina_stringshare_single));
}
-
-/**
- * @}
- */
-
projects / framework / uifw / eina.git / commitdiff