From 703b83564337512ffe40d1083d0919fe665882f4 Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Thu, 7 Apr 2011 13:13:11 +0000 Subject: [PATCH] doxy -> .h SVN revision: 58445 --- legacy/eina/src/include/eina_stringshare.h | 180 +++++++++++++++++++++ legacy/eina/src/lib/eina_stringshare.c | 179 -------------------- 2 files changed, 180 insertions(+), 179 deletions(-) diff --git a/legacy/eina/src/include/eina_stringshare.h b/legacy/eina/src/include/eina_stringshare.h index f1486b1acc..f20ed5488f 100644 --- a/legacy/eina/src/include/eina_stringshare.h +++ b/legacy/eina/src/include/eina_stringshare.h @@ -55,6 +55,30 @@ #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 * @@ -67,14 +91,166 @@ * @{ */ + +/** + * @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); @@ -90,4 +266,8 @@ static inline Eina_Bool eina_stringshare_replace_length(const char **p_str, cons * @} */ +/** + * @} + */ + #endif /* EINA_STRINGSHARE_H_ */ diff --git a/legacy/eina/src/lib/eina_stringshare.c b/legacy/eina/src/lib/eina_stringshare.c index 235ca60751..63236f4a50 100644 --- a/legacy/eina/src/lib/eina_stringshare.c +++ b/legacy/eina/src/lib/eina_stringshare.c @@ -22,13 +22,6 @@ * if not, see . */ -/** - * @page tutorial_stringshare_page Stringshare Tutorial - * - * to be written... - * - */ - #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -561,43 +554,6 @@ eina_stringshare_shutdown(void) * 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) { @@ -632,26 +588,6 @@ 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) { @@ -675,25 +611,6 @@ 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) { @@ -715,26 +632,6 @@ 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, ...) { @@ -759,27 +656,6 @@ 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) { @@ -801,25 +677,6 @@ 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, ...) { @@ -845,20 +702,6 @@ 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) { @@ -901,17 +744,6 @@ 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) { @@ -934,12 +766,6 @@ 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) { @@ -947,8 +773,3 @@ eina_stringshare_dump(void) _eina_stringshare_small_dump, sizeof(_eina_stringshare_single)); } - -/** - * @} - */ -