Tizen Native API
|
Functions | |
Eina_Stringshare * | eina_stringshare_add_length (const char *str, unsigned int slen) |
Retrieves an instance of a string for use in a program. | |
Eina_Stringshare * | eina_stringshare_add (const char *str) |
Retrieves an instance of a string for use in a program. | |
Eina_Stringshare * | eina_stringshare_printf (const char *fmt,...) |
Retrieves an instance of a string for use in a program from a format string. | |
Eina_Stringshare * | eina_stringshare_vprintf (const char *fmt, va_list args) |
Retrieves an instance of a string for use in a program from a format string. | |
Eina_Stringshare * | eina_stringshare_nprintf (unsigned int len, const char *fmt,...) |
Retrieves an instance of a string for use in a program from a format string with size limitation. | |
Eina_Stringshare * | eina_stringshare_ref (Eina_Stringshare *str) |
Increments references of the given shared string. | |
void | eina_stringshare_del (Eina_Stringshare *str) |
Notes that the given string has lost an instance. | |
int | eina_stringshare_strlen (Eina_Stringshare *str) |
Notes that the given string must be shared. | |
void | eina_stringshare_dump (void) |
Dumps the contents of share_common. | |
static Eina_Bool | eina_stringshare_refplace (Eina_Stringshare **p_str, Eina_Stringshare *news) |
Replace the previously stringshared pointer with another stringshared pointer. | |
static Eina_Bool | eina_stringshare_replace (Eina_Stringshare **p_str, const char *news) |
Replace the previously stringshared pointer with new content. | |
static Eina_Bool | eina_stringshare_replace_length (Eina_Stringshare **p_str, const char *news, unsigned int slen) |
Replace the previously stringshared pointer with a new content. | |
Typedefs | |
typedef const char | Eina_Stringshare |
Interchangeable with "const char *", but still a good visual hint for the purpose. Maybe in the future we may even add strict type checking. |
This group discusses the functions that allow you to store a single copy of a string, and use it in multiple places throughout your program.
This is a method to reduce the number of duplicated strings kept in the 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 that this can have a significant impact as you scale the number of copies up. It improves the string creation/destruction speed, reduces memory use, and decreases memory fragmentation, so a win all-around.
const char *str = eina_stringshare_add("My string"); ... //Use str ... eina_stringshare_del(str);
It's very important to note that string shares are const
, changing them results in an undefined behavior. eina_stringshare_del() doesn't guarantee that the string share is freed, it releases a reference to it, but if other references to it still exist the string share lives until those are released.
The following diagram gives an idea of what happens as you create strings with eina_stringshare_add():
Interchangeable with "const char *", but still a good visual hint for the purpose. Maybe in the future we may even add strict type checking.
Eina_Stringshare* eina_stringshare_add | ( | const char * | str | ) |
Retrieves an instance of a string for use in a program.
This function retrieves an instance of str. If str is NULL
, then NULL
is returned. If str is already stored, it is just returned and its reference counter is increased. Otherwise a duplicated string of str is returned.
NULL
terminated ('\0') and its full length should be used. To use a part of the string or non-null terminated, use eina_stringshare_add_length() instead.[in] | str | The NULL-terminated string to retrieve an instance of |
NULL
on failureEina_Stringshare* eina_stringshare_add_length | ( | const char * | str, |
unsigned int | slen | ||
) |
Retrieves an instance of a string for use in a program.
This function retrieves an instance of str. If str is NULL
, then NULL
is returned. If str is already stored, it is just returned and its reference counter is increased. Otherwise a duplicated string of str is returned.
[in] | str | The string to retrieve an instance of |
[in] | slen | The string size (<= strlen(str)) |
NULL
on failurevoid eina_stringshare_del | ( | Eina_Stringshare * | str | ) |
Notes that the given string has lost an instance.
This function decreases the reference counter associated to str if it exists. If that counter reaches 0
, the memory associated to str is freed. If str is NULL
, the function returns immediately.
[in] | str | string The given string |
void eina_stringshare_dump | ( | void | ) |
Dumps the contents of share_common.
This function dumps all the strings from share_common to stdout with a DDD: prefix per line and a memory usage summary.
Eina_Stringshare* eina_stringshare_nprintf | ( | unsigned int | len, |
const char * | fmt, | ||
... | |||
) |
Retrieves an instance of a string for use in a program from a format string with size limitation.
This function retrieves an instance of fmt limited by len. If fmt is NULL
or len is < 1, then NULL
is returned. If the resulting string is already stored, it is just returned and its reference counter is increased. Otherwise a duplicated string is returned.
len length of the format string is used. To use the entire format string, use eina_stringshare_printf() instead.
[in] | len | The length of the format string to use |
[in] | fmt | The format string to retrieve an instance of |
NULL
on failureEina_Stringshare* eina_stringshare_printf | ( | const char * | fmt, |
... | |||
) |
Retrieves an instance of a string for use in a program from a format string.
This function retrieves an instance of fmt. If fmt is NULL
, then NULL
is returned. If fmt is already stored, it is just returned and its reference counter is increased. Otherwise a duplicated string is returned.
The format string fmt must be NULL-terminated ('\0') and its full length should be used. To use a part of the format string or non-null terminated, use eina_stringshare_nprintf() instead.
[in] | fmt | The NULL-terminated format string to retrieve an instance of |
NULL
on failureIncrements references of the given shared string.
[in] | str | The shared string |
NULL
on failure static Eina_Bool eina_stringshare_refplace | ( | Eina_Stringshare ** | p_str, |
Eina_Stringshare * | news | ||
) | [static] |
Replace the previously stringshared pointer with another stringshared pointer.
The string pointed by p_str must be previously stringshared or NULL
and it will be eina_stringshare_del(). The new string must also be stringshared and will be passed to eina_stringshare_ref() and then assigned to *p_str
. This function is identical to eina_stringshare_replace() except that it calls eina_stringshare_ref() instead of eina_stringshare_add()
[out] | p_str | pointer to the stringhare to be replaced. Must not be NULL , but *p_str may be NULL as it is a valid stringshare handle. |
[out] | news | new string to replace with, may be NULL . |
static Eina_Bool eina_stringshare_replace | ( | Eina_Stringshare ** | p_str, |
const char * | news | ||
) | [static] |
Replace the previously stringshared pointer with new content.
The string pointed by p_str must be previously stringshared or NULL
and it will be eina_stringshare_del(). The new string will be passed to eina_stringshare_add() and then assigned to *p_str
.
[in] | p_str | pointer to the stringhare to be replaced. Must not be NULL , but *p_str may be NULL as it is a valid stringshare handle. |
[in] | news | new string to be stringshared, may be NULL . |
EINA_TRUE
if the strings were different and thus replaced, EINA_FALSE
if the strings were the same after shared. static Eina_Bool eina_stringshare_replace_length | ( | Eina_Stringshare ** | p_str, |
const char * | news, | ||
unsigned int | slen | ||
) | [static] |
Replace the previously stringshared pointer with a new content.
The string pointed by p_str must be previously stringshared or NULL
and it will be eina_stringshare_del(). The new string will be passed to eina_stringshare_add_length() and then assigned to *p_str
.
[in] | p_str | pointer to the stringhare to be replaced. Must not be NULL , but *p_str may be NULL as it is a valid stringshare handle. |
[in] | news | new string to be stringshared, may be NULL . |
[in] | slen | The string size (<= strlen(str)). |
EINA_TRUE
if the strings were different and thus replaced, EINA_FALSE
if the strings were the same after shared. int eina_stringshare_strlen | ( | Eina_Stringshare * | str | ) |
Notes that the given string must be shared.
This function is a cheap way to known the length of a shared string.
[in] | str | The shared string to know the length of It is safe to give NULL , in which case 0 is returned. |
Eina_Stringshare* eina_stringshare_vprintf | ( | const char * | fmt, |
va_list | args | ||
) |
Retrieves an instance of a string for use in a program from a format string.
This function retrieves an instance of fmt with args. If fmt is NULL
, then NULL
is returned. If fmt with args is already stored, it is just returned and its reference counter is increased. Otherwise a duplicated string is returned.
The format string fmt must be NULL-terminated ('\0') and its full length should be used. To use a part of the format string or non-null terminated, use eina_stringshare_nprintf() instead.
[in] | fmt | The NULL-terminated format string to retrieve an instance of |
[in] | args | The va_args for fmt |
NULL
on failure