enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

doxy -> .h 

SVN revision: 58450
This commit is contained in:
Carsten Haitzler 2011-04-07 13:17:25 +00:00
parent b5b34a6fe3
commit 8945479719
4 changed files with 132 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
legacy/eina/src/include/eina_ustrbuf.h
View File

@ -6,6 +6,17 @@
#include "eina_types.h"
#include "eina_unicode.h"
/**
* @addtogroup Eina_Unicode_String_Buffer_Group Unicode String Buffer
*
* @brief These functions provide unicode string buffers management.
*
* The Unicode String Buffer data type is designed to be a mutable string,
* allowing to append, prepend or insert a string to a buffer.
*
* @{
*/
/**
* @addtogroup Eina_Data_Types_Group Data Types
*
@ -415,4 +426,8 @@ eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_U
* @}
*/
/**
* @}
*/
#endif /* EINA_STRBUF_H */

117
legacy/eina/src/include/eina_ustringshare.h
View File

@ -54,6 +54,30 @@
#include "eina_types.h"
#include "eina_unicode.h"
/**
* @addtogroup Eina_UStringshare_Group Unicode 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_ustringshare_page.
*
* @{
*/
/**
* @addtogroup Eina_Data_Types_Group Data Types
*
@ -66,11 +90,100 @@
* @{
*/
/**
* @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_ustringshare_add()
*/
EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *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_ustringshare_add_length()
*/
EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WARN_UNUSED_RESULT;
/**
* 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_ustringshare_add().
*
* There is no unref since this is the work of eina_ustringshare_del().
*/
EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *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_ustringshare_del(const Eina_Unicode *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_ustringshare_strlen(const Eina_Unicode *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_ustringshare_dump(void);
static inline Eina_Bool eina_ustringshare_replace(const Eina_Unicode **p_str, const Eina_Unicode *news) EINA_ARG_NONNULL(1);
@ -86,4 +199,8 @@ static inline Eina_Bool eina_ustringshare_replace_length(const Eina_Unicode **p
* @}
*/
/**
* @}
*/
#endif /* EINA_STRINGSHARE_H_ */

15
legacy/eina/src/lib/eina_ustrbuf.c
View File

@ -71,19 +71,4 @@ static const char __USTRBUF_MAGIC_STR[] = "Eina UStrbuf";
* API *
*============================================================================*/
/**
* @addtogroup Eina_Unicode_String_Buffer_Group Unicode String Buffer
*
* @brief These functions provide unicode string buffers management.
*
* The Unicode String Buffer data type is designed to be a mutable string,
* allowing to append, prepend or insert a string to a buffer.
*
* @{
*/
#include "eina_strbuf_template_c.x"
/**
* @}
*/

111
legacy/eina/src/lib/eina_ustringshare.c
View File

@ -81,43 +81,7 @@ eina_ustringshare_shutdown(void)
/*============================================================================*
* API *
*============================================================================*/
/**
* @addtogroup Eina_UStringshare_Group Unicode 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_ustringshare_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_ustringshare_del(const Eina_Unicode *str)
{
@ -127,26 +91,6 @@ eina_ustringshare_del(const Eina_Unicode *str)
eina_share_common_del(ustringshare_share,(const char *)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_ustringshare_add()
*/
EAPI const Eina_Unicode *
eina_ustringshare_add_length(const Eina_Unicode *str, unsigned int slen)
{
@ -159,25 +103,6 @@ eina_ustringshare_add_length(const Eina_Unicode *str, unsigned int slen)
Eina_Unicode));
}
/**
* @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_ustringshare_add_length()
*/
EAPI const Eina_Unicode *
eina_ustringshare_add(const Eina_Unicode *str)
{
@ -185,20 +110,6 @@ eina_ustringshare_add(const Eina_Unicode *str)
return eina_ustringshare_add_length(str, slen);
}
/**
* 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_ustringshare_add().
*
* There is no unref since this is the work of eina_ustringshare_del().
*/
EAPI const Eina_Unicode *
eina_ustringshare_ref(const Eina_Unicode *str)
{
@ -206,17 +117,6 @@ eina_ustringshare_ref(const Eina_Unicode *str)
(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_ustringshare_strlen(const Eina_Unicode *str)
{
@ -225,19 +125,8 @@ eina_ustringshare_strlen(const Eina_Unicode *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_ustringshare_dump(void)
{
eina_share_common_dump(ustringshare_share, NULL, 0);
}
/**
* @}
*/