Typedefs

typedef const char Eina_Stringshare
 Interchangeable with "const char *" but still a good visual hint for the purpose.
 

Functions

Eina_Stringshareeina_stringshare_add_length (const char *str, unsigned int slen)
 Retrieve an instance of a string for use in a program.
 
Eina_Stringshareeina_stringshare_add (const char *str)
 Retrieve an instance of a string for use in a program.
 
Eina_Stringshareeina_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_Stringshareeina_stringshare_vprintf (const char *fmt, va_list args)
 Retrieve an instance of a string for use in a program from a format string.
 
Eina_Stringshareeina_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_Stringshareeina_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.
 
static Eina_Bool eina_stringshare_replace (Eina_Stringshare **p_str, const char *news)
 
static Eina_Bool eina_stringshare_replace_length (Eina_Stringshare **p_str, const char *news, unsigned int slen)
 

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 * eina_stringshare_add(const char *str)
Retrieve an instance of a string for use in a program.
Definition eina_stringshare.c:635
void eina_stringshare_del(Eina_Stringshare *str)
Note that the given string has lost an instance.
Definition eina_stringshare.c:577
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.

The following diagram gives an idea of what happens as you create strings with eina_stringshare_add():

For more information, see this example.

Typedef Documentation

◆ Eina_Stringshare

typedef const char Eina_Stringshare

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

◆ eina_stringshare_add_length()

Eina_Stringshare * eina_stringshare_add_length ( const char * str,
unsigned int slen )

Retrieve an instance of a string for use in a program.

Parameters
strThe string to retrieve an instance of.
slenThe string size (<= strlen(str)).
Returns
A pointer to an instance of the string on success. NULL on failure.

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.

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()
Examples
eina_stringshare_01.c.

Referenced by eina_stringshare_add(), and eina_stringshare_vprintf().

◆ eina_stringshare_add()

Eina_Stringshare * eina_stringshare_add ( const char * str)

Retrieve an instance of a string for use in a program.

Parameters
strThe NULL-terminated string to retrieve an instance of.
Returns
A pointer to an instance of the string on success. NULL on failure.

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.

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()
Examples
eina_hash_02.c, eina_list_04.c, and eina_stringshare_01.c.

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(), and eina_xattr_value_ls().

◆ eina_stringshare_printf()

Eina_Stringshare * eina_stringshare_printf ( const char * fmt,
... )

Retrieve an instance of a string for use in a program from a format string.

Parameters
fmtThe NULL-terminated format string to retrieve an instance of.
Returns
A pointer to an instance of the string on success. NULL on failure.

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 will be used. To use part of the format string or non-null terminated, use eina_stringshare_nprintf() instead.

See also
eina_stringshare_nprintf()
Examples
eina_stringshare_01.c.

◆ eina_stringshare_vprintf()

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
fmtThe NULL-terminated format string to retrieve an instance of.
argsThe va_args for fmt
Returns
A pointer to an instance of the string on success. NULL on failure.

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 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_nprintf()

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
lenThe length of the format string to use
fmtThe format string to retrieve an instance of.
Returns
A pointer to an instance of the string on success. NULL on failure.

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 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()
Examples
eina_stringshare_01.c.

◆ eina_stringshare_ref()

Eina_Stringshare Eina_Stringshare * eina_stringshare_ref ( Eina_Stringshare * str)

Increment references of the given shared string.

Parameters
strThe shared string.
Returns
A pointer to an instance of the string on success. 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 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().

Examples
eina_stringshare_01.c.

◆ eina_stringshare_del()

void eina_stringshare_del ( Eina_Stringshare * str)

Note that the given string has lost an instance.

Parameters
strstring The given string.

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.

Note
If the given pointer is not shared, bad things will happen, likely a segmentation fault.
Examples
eina_file_01.c, eina_hash_02.c, eina_list_04.c, and eina_stringshare_01.c.

Referenced by eina_error_msg_modify(), and eina_simple_xml_attribute_free().

◆ eina_stringshare_strlen()

int eina_stringshare_strlen ( Eina_Stringshare * str)

Note that the given string must be shared.

Parameters
strthe shared string to know the length. It is safe to give NULL, in that case 0 is returned.
Returns
The length of a shared string.

This function is a cheap way to known the length of a shared string.

Note
If the given pointer is not shared, bad things will happen, likely a segmentation fault. If in doubt, try strlen().
Examples
eina_stringshare_01.c.

◆ eina_stringshare_dump()

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.