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

Eina: Eina_Stringshare documentation. 

SVN revision: 60559
This commit is contained in:
Jonas M. Gastal 2011-06-21 20:45:50 +00:00
parent 2344ff2a81
commit 7a1da7d624
2 changed files with 109 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
legacy/eina/src/examples/eina_stringshare_01.c Normal file
View File

@ -0,0 +1,45 @@
//Compile with:
//gcc -g `pkg-config --cflags --libs eina` eina_stringshare_01.c -o eina_stringshare_01
#include <stdio.h>
#include <Eina.h>
int
main(int argc, char **argv)
{
const char *str, *str2;
const char *prologe = "The Cylons were created by man. They rebelled. They "
"evolved.";
const char *prologe2 = "%d Cylon models. %d are known. %d live in secret. "
"%d will be revealed.";
const char *prologe3 = "There are many copies. And they have a plan.";
eina_init();
str = eina_stringshare_add_length(prologe, 31);
printf("%s\n", str);
printf("length: %d\n", eina_stringshare_strlen(str));
eina_stringshare_del(str);
str = eina_stringshare_printf(prologe2, 12, 7, 4, 1);
printf("%s\n", str);
eina_stringshare_del(str);
str = eina_stringshare_nprintf(45, "%s", prologe3);
printf("%s\n", str);
str2 = eina_stringshare_add(prologe3);
printf("%s\n", str2);
eina_stringshare_ref(str2);
eina_stringshare_del(str2);
printf("%s\n", str2);
eina_stringshare_replace(&str, prologe);
printf("%s\n", str);
eina_stringshare_del(str);
eina_stringshare_del(str2);
eina_shutdown();
return 0;
}

80
legacy/eina/src/include/eina_stringshare.h
View File

@ -55,11 +55,63 @@
#include "eina_types.h"
/**
* @page eina_stringshare_example_01_page
* @dontinclude eina_stringshare_01.c
*
* Like all examples we start by including Eina:
* @skip #include
* @line #include
*
* Here we declare some variables and initialize eina:
* @until eina_init
*
* We start the substantive part of the example by showing how to make a part
* of a string shared and how to get the length of a shared string:
* @until stringshare_strlen
* As we add shared strings we also need to delete them when done using them:
* @line del
*
* There are many ways of creating shared strings including an equivalent to
* sprintf:
* @until del
*
* An equivalent to snprintf:
* @until printf
*
* But the simplest way of creating a shared string is through
* eina_stringshare_add():
* @until printf
*
* Sometimes you already have a pointer to a shared string and want to use it,
* so to make sure the provider of the pointer won't free it while you're using
* it you can increase the shared string's ref count:
* @until printf
*
* Whenever you have a pointer to a shared string and would like to change it's
* value you should use eina_stringshare_replace():
* @until printf
* @warning @b Don't use eina_stringshare_del() followed by
* eina_share_common_add(), under some circunstances you might end up deleting
* a shared string some other piece of code is using.
*
* We created str but haven't deleted it yet, and while we called
* eina_stringshare_del() on str2, we created it and then increased the ref
* count so it's still alive:
* @until str2
*
* You can see the full source code @ref eina_stringshare_example_01 "here".
*/
/**
* @page eina_stringshare_example_01
* @include eina_stringshare_01.c
* @example eina_stringshare_01.c
*/
/**
* @addtogroup Eina_Stringshare_Group Stringshare
*
* These functions allow you to store one copy of a string, and use it
* throughout your program.
* These functions allow you to store a single copy of a string, and use in
* multiple places 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
@ -74,7 +126,8 @@
* 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.
* For more information, see @ref eina_stringshare_example_01_page
* "this example".
*
* @{
*/
@ -103,8 +156,7 @@
* 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.
* 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
@ -124,8 +176,7 @@ EAPI const char *eina_stringshare_add_length(const char *str, unsigned in
* 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.
* 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
@ -146,8 +197,7 @@ EAPI const char *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_R
* 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.
* 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
@ -169,8 +219,7 @@ EAPI const char *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_
* 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.
* 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
@ -190,9 +239,8 @@ EAPI const char *eina_stringshare_vprintf(const char *fmt, va_list args)
*
* 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.
* is already stored, it is returned and its reference counter is increased.
* Otherwise 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.
@ -210,8 +258,8 @@ EAPI const char *eina_stringshare_nprintf(unsigned int len, const char *f
*
* 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().
* to be shared string. In other words, it must be the return of a previous
* call to one of the stringshare functions.
*
* There is no unref since this is the work of eina_share_common_del().
*/