Unicode Stringshare

Functions
Unicode Stringshare
Eina » Data Types

These functions allow you to store one copy of a string, and use it throughout your program. More...

## Functions
static Eina_Bool | eina_ustringshare_replace (const Eina_Unicode **p_str, const Eina_Unicode *news)
| Replace the previously stringshared pointer with new content. More...
static Eina_Bool | eina_ustringshare_replace_length (const Eina_Unicode **p_str, const Eina_Unicode *news, unsigned int slen)
| Replace the previously stringshared pointer with a new content. More...
EINA_API const Eina_Unicode * | eina_ustringshare_add_length (const Eina_Unicode *str, unsigned int slen)
| Retrieves an instance of a string for use in a program. More...
EINA_API const Eina_Unicode * | eina_ustringshare_add (const Eina_Unicode *str)
| Retrieves an instance of a string for use in a program. More...
EINA_API const Eina_Unicode * | eina_ustringshare_ref (const Eina_Unicode *str)
| Increments references of the given shared string. More...
EINA_API void | eina_ustringshare_del (const Eina_Unicode *str)
| Notes that the given string has lost an instance. More...
EINA_API int | eina_ustringshare_strlen (const Eina_Unicode *str)
| Notes that the given string must be shared. More...
EINA_API void | eina_ustringshare_dump (void)
| Dumps the contents of the share_common. More...

## Detailed Description

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 UStringshare Tutorial.

## Function Documentation

## ◆ eina_ustringshare_replace()

static Eina_Bool eina_ustringshare_replace | ( | const Eina_Unicode ** | p_str,
|  | const Eina_Unicode * | news
| ) |  |
| inlinestatic

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_ustringshare_del(). The new string will be passed to eina_ustringshare_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 be `NULL` 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_TRUE, eina_ustringshare_add(), and eina_ustringshare_del().

## ◆ eina_ustringshare_replace_length()

static Eina_Bool eina_ustringshare_replace_length | ( | const Eina_Unicode ** | p_str,
|  | const Eina_Unicode * | news,
|  | unsigned int | slen
| ) |  |
| inlinestatic

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_ustringshare_del(). The new string will be passed to eina_ustringshare_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 be `NULL` 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_TRUE, eina_ustringshare_add_length(), and eina_ustringshare_del().

## ◆ eina_ustringshare_add_length()

EINA_API const Eina_Unicode* eina_ustringshare_add_length | ( | const Eina_Unicode * | str,
|  | unsigned int | slen
| ) |  |

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

Parameters

  [in] | str | The string to retrieve an instance of.
  [in] | slen | The 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 it is added to the strings to be searched and 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_ustringshare_add()

Referenced by eina_ustringshare_replace_length().

## ◆ eina_ustringshare_add()

EINA_API const Eina_Unicode* eina_ustringshare_add | ( | const Eina_Unicode * | str | ) |

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

Parameters

  [in] | str | The 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 it is added to the strings to be searched and 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_ustringshare_add_length()

Referenced by eina_ustringshare_replace().

## ◆ eina_ustringshare_ref()

EINA_API const Eina_Unicode* eina_ustringshare_ref | ( | const Eina_Unicode * | str | ) |

Increments references of the given shared string.

Parameters

  [in] | str | The 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 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().

## ◆ eina_ustringshare_del()

EINA_API void eina_ustringshare_del | ( | const Eina_Unicode * | str | ) |

Notes that the given string has lost an instance.

Parameters

  [in] | str | String 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.

Referenced by eina_ustringshare_replace(), and eina_ustringshare_replace_length().

## ◆ eina_ustringshare_strlen()

EINA_API int eina_ustringshare_strlen | ( | const Eina_Unicode * | str | ) |

Notes that the given string must be shared.

Parameters

  [in] | 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.

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

## ◆ eina_ustringshare_dump()

EINA_API void eina_ustringshare_dump | ( | void |  | ) |

Dumps 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.