Stringshare
[Data Types]
These functions allow you to store a single copy of a string, and use in multiple places throughout your program.
More...Typedefs | |
typedef const char | Eina_Stringshare |
Interchangeable with "const char *" but still a good visual hint for the purpose. | |
Functions | |
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. | |
Eina_Stringshare * | eina_stringshare_add_length (const char *str, unsigned int slen) |
Retrieve an instance of a string for use in a program. | |
Eina_Stringshare * | eina_stringshare_add (const char *str) |
Retrieve an instance of a string for use in a program. | |
Eina_Stringshare * | eina_stringshare_printf (const char *fmt,...) EINA_PRINTF(1 |
Retrieve an instance of a string for use in a program from a format string. | |
Eina_Stringshare *Eina_Stringshare * | eina_stringshare_vprintf (const char *fmt, va_list args) |
Retrieve 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,...) EINA_PRINTF(2 |
Retrieve an instance of a string for use in a program from a format string with size limitation. | |
Eina_Stringshare *Eina_Stringshare * | eina_stringshare_ref (Eina_Stringshare *str) |
Increment references of the given shared string. | |
void | eina_stringshare_del (Eina_Stringshare *str) |
Note that the given string has lost an instance. | |
int | eina_stringshare_strlen (Eina_Stringshare *str) |
Note that the given string must be shared. | |
void | eina_stringshare_dump (void) |
Dump the contents of the share_common. |
Detailed Description
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 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.
Using eina stringshares usually boils down to:
const char *str = eina_stringshare_add("My string"); ... //Use str ... eina_stringshare_del(str);
- Note:
- It's very important to note that string shares are
const
, changing them will result in undefined behavior.eina_stringshare_del() doesn't guarantee the string share will be freed, it releases a reference to it, but if other references to it still exist the string share will live until those are released.

For more information, see this example.
Typedef Documentation
Interchangeable with "const char *" but still a good visual hint for the purpose.
Maybe in the far far future we'll even add strict type checking.
- Since:
- 1.2.0
Function Documentation
static Eina_Bool eina_stringshare_replace | ( | Eina_Stringshare ** | p_str, | |
const char * | news | |||
) | [inline, static] |
Replace the previously stringshared pointer with new content.
The string pointed by p_str should 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
.
- Parameters:
-
p_str pointer to the stringhare to be replaced. Must not be NULL
, but*p_str
may beNULL
as it is a valid stringshare handle.news new string to be stringshared, may be NULL
.
- Returns:
- EINA_TRUE if the strings were different and thus replaced, EINA_FALSE if the strings were the same after shared.
References EINA_FALSE, eina_stringshare_add(), eina_stringshare_del(), and EINA_TRUE.
static Eina_Bool eina_stringshare_replace_length | ( | Eina_Stringshare ** | p_str, | |
const char * | news, | |||
unsigned int | slen | |||
) | [inline, static] |
Replace the previously stringshared pointer with a new content.
The string pointed by p_str should 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
.
- Parameters:
-
p_str pointer to the stringhare to be replaced. Must not be NULL
, but*p_str
may beNULL
as it is a valid stringshare handle.news new string to be stringshared, may be NULL
.slen The string size (<= strlen(str)).
- Returns:
- EINA_TRUE if the strings were different and thus replaced, EINA_FALSE if the strings were the same after shared.
References EINA_FALSE, eina_stringshare_add_length(), eina_stringshare_del(), and EINA_TRUE.
Eina_Stringshare* eina_stringshare_add_length | ( | const char * | str, | |
unsigned int | slen | |||
) |
Retrieve an instance of a string for use in a program.
- Parameters:
-
str The string to retrieve an instance of. slen The string size (<= strlen(str)).
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
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.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 also:
- eina_share_common_add()
References eina_lock_release(), and eina_lock_take().
Referenced by eina_stringshare_add(), eina_stringshare_replace_length(), and eina_stringshare_vprintf().
Eina_Stringshare* eina_stringshare_add | ( | const char * | str | ) |
Retrieve an instance of a string for use in a program.
- Parameters:
-
str The NULL-terminated string to retrieve an instance of.
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
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.
The string 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 also:
- eina_stringshare_add_length()
References eina_stringshare_add_length().
Referenced by eina_error_msg_modify(), eina_error_msg_register(), eina_simple_xml_attribute_new(), eina_simple_xml_node_tag_new(), eina_stringshare_replace(), and eina_xattr_value_ls().
Eina_Stringshare* eina_stringshare_printf | ( | const char * | fmt, | |
... | ||||
) |
Retrieve an instance of a string for use in a program from a format string.
- Parameters:
-
fmt The NULL-terminated format string to retrieve an instance of.
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
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 will be used. To use part of the format string or non-null terminated, use eina_stringshare_nprintf() instead.
- See also:
- eina_stringshare_nprintf()
Eina_Stringshare* Eina_Stringshare* eina_stringshare_vprintf | ( | const char * | fmt, | |
va_list | args | |||
) |
Retrieve an instance of a string for use in a program from a format string.
- Parameters:
-
fmt The NULL-terminated format string to retrieve an instance of. args The va_args for fmt
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
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 will be used. To use part of the format string or non-null terminated, use eina_stringshare_nprintf() instead.
- See also:
- eina_stringshare_nprintf()
References eina_stringshare_add_length().
Eina_Stringshare* eina_stringshare_nprintf | ( | unsigned int | len, | |
const char * | fmt, | |||
... | ||||
) |
Retrieve an instance of a string for use in a program from a format string with size limitation.
- Parameters:
-
len The length of the format string to use fmt The format string to retrieve an instance of.
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
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 returned and its reference counter is increased. Otherwise a duplicated string is returned.
len
length of the format string will be used. To use the entire format string, use eina_stringshare_printf() instead.
- See also:
- eina_stringshare_printf()
Eina_Stringshare* Eina_Stringshare* eina_stringshare_ref | ( | Eina_Stringshare * | str | ) |
Increment references of the given shared string.
- Parameters:
-
str The shared string.
- Returns:
- A pointer to an instance of the string on success.
NULL
on failure.
There is no unref since this is the work of eina_share_common_del().
References eina_lock_release(), and eina_lock_take().
void eina_stringshare_del | ( | Eina_Stringshare * | str | ) |
Note that the given string has lost an instance.
- Parameters:
-
str string The given string.
str
if it exists. If that counter reaches 0, the memory associated to str
is freed. If 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.
References eina_lock_release(), and eina_lock_take().
Referenced by eina_error_msg_modify(), eina_simple_xml_attribute_free(), eina_stringshare_replace(), and eina_stringshare_replace_length().
int eina_stringshare_strlen | ( | Eina_Stringshare * | str | ) |
Note that the given string must be shared.
- Parameters:
-
str the shared string to know the length. It is safe to give NULL
, in that case-1
is returned.
- Returns:
- The length of a shared string.
void eina_stringshare_dump | ( | void | ) |
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.