- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

Typedefs | Functions
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
| "Eina_Stringshare *" is interchangeable with "const char *" but still a good visual hint for the purpose. More...
typedef const char | Eina_Tmpstr
| Interchangeable with "const char *" but still a good visual hint for the purpose. More...

## Functions
static Eina_Bool | eina_stringshare_refplace (Eina_Stringshare **p_str, Eina_Stringshare *news)
| Replace the previously stringshared pointer with another stringshared pointer. More...
static Eina_Bool | eina_stringshare_replace (Eina_Stringshare **p_str, const char *news)
| Replace the previously stringshared pointer with new content. More...
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. More...
EAPI Eina_Stringshare * | eina_stringshare_add_length (const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT
| Retrieve an instance of a string with a specific size for use in a program. More...
EAPI Eina_Stringshare * | eina_stringshare_add (const char *str) EINA_WARN_UNUSED_RESULT
| Retrieve an instance of a string for use in a program. More...
EAPI Eina_Stringshare * | eina_stringshare_printf (const char *fmt,...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1
| Retrieve an instance of a string for use in a program from a format string. More...
EAPI Eina_Stringshare EAPI Eina_Stringshare * | eina_stringshare_vprintf (const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT
| Retrieve an instance of a string for use in a program from a format string. More...
EAPI Eina_Stringshare * | eina_stringshare_nprintf (unsigned int len, const char *fmt,...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(2
| Retrieve an instance of a string for use in a program from a format string with size limitation. More...
EAPI Eina_Stringshare EAPI Eina_Stringshare * | eina_stringshare_ref (Eina_Stringshare *str)
| Increment references of the given shared string. More...
EAPI void | eina_stringshare_del (Eina_Stringshare *str)
| Note that the given string has lost an instance. More...
EAPI int | eina_stringshare_strlen (Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT
| Note that the given string must be shared. More...
EAPI void | eina_stringshare_dump (void)
| Dump the contents of the share_common. More...
EAPI Eina_Tmpstr * | eina_tmpstr_add (const char *str) EINA_WARN_UNUSED_RESULT
| Add a new temporary string based on the input string. More...
EAPI Eina_Tmpstr * | eina_tmpstr_add_length (const char *str, size_t length)
| Add a new temporary string based on the input string and length. More...
EAPI size_t | eina_tmpstr_strlen (Eina_Tmpstr *tmpstr)
| Return the length of a temporary string including the '\0'. More...
EAPI void | eina_tmpstr_del (Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1)
| Delete the temporary string if it is one, or ignore it if it is not. More...

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

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

"Eina_Stringshare *" is 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

Eina_Tmpstr

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

This indicates the string is temporary and should be freed after use.

Since
  1.8.0

## Function Documentation

static Eina_Bool eina_stringshare_refplace | ( | Eina_Stringshare ** | p_str,
|  | Eina_Stringshare * | news
| ) |  |
| inline 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()

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 replace with, may be `NULL`.

Returns
  EINA_TRUE if the strings were different and thus replaced, EINA_FALSE if the strings were the same after shared.

Since
  1.8

References EINA_FALSE, eina_stringshare_del(), eina_stringshare_ref(), and EINA_TRUE.

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

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.

Examples:
  eina_stringshare_01.c.

References EINA_FALSE, eina_stringshare_add(), eina_stringshare_del(), and EINA_TRUE.

Referenced by ecore_con_ssl_server_verify_name_set(), ecore_con_url_url_set(), edje_edit_group_name_set(), edje_text_class_set(), eeze_disk_mount_point_set(), eeze_disk_mount_wrapper_set(), efreet_desktop_environment_set(), emotion_object_file_set(), evas_device_description_set(), and evas_device_name_set().

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

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_stringshare_add_length(), eina_stringshare_del(), and EINA_TRUE.

Referenced by eeze_net_scan().

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

Retrieve an instance of a string with a specific size 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.

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

Referenced by eet_open(), efreet_icon_deprecated_user_dir_get(), efreet_icon_user_dir_get(), eina_stringshare_add(), eina_stringshare_replace_length(), and eina_stringshare_vprintf().

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

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

References eina_stringshare_add_length().

Referenced by ecore_con_socks4_remote_add(), ecore_con_socks5_remote_add(), edje_available_modules_get(), edje_color_class_set(), edje_edit_color_class_add(), edje_edit_color_class_name_set(), edje_edit_color_classes_list_get(), edje_edit_compiler_get(), edje_edit_data_add(), edje_edit_data_list_get(), edje_edit_data_value_get(), edje_edit_data_value_set(), edje_edit_external_add(), edje_edit_externals_list_get(), edje_edit_font_add(), edje_edit_font_path_get(), edje_edit_fonts_list_get(), edje_edit_group_add(), edje_edit_group_alias_add(), edje_edit_group_aliased_get(), edje_edit_group_aliases_get(), edje_edit_group_copy(), edje_edit_group_data_add(), edje_edit_group_data_list_get(), edje_edit_group_data_value_get(), edje_edit_group_data_value_set(), edje_edit_group_name_set(), edje_edit_image_add(), edje_edit_image_data_add(), edje_edit_images_list_get(), edje_edit_part_above_get(), edje_edit_part_below_get(), edje_edit_part_clip_to_get(), edje_edit_part_name_set(), edje_edit_part_selected_state_get(), edje_edit_part_source_get(), edje_edit_part_source_set(), edje_edit_part_states_list_get(), edje_edit_parts_list_get(), edje_edit_program_add(), edje_edit_program_afters_get(), edje_edit_program_api_description_get(), edje_edit_program_api_description_set(), edje_edit_program_api_name_get(), edje_edit_program_api_name_set(), edje_edit_program_name_set(), edje_edit_program_signal_get(), edje_edit_program_signal_set(), edje_edit_program_source_get(), edje_edit_program_source_set(), edje_edit_program_state2_get(), edje_edit_program_state2_set(), edje_edit_program_state_get(), edje_edit_program_state_set(), edje_edit_program_targets_get(), edje_edit_programs_list_get(), edje_edit_state_add(), edje_edit_state_color_class_get(), edje_edit_state_color_class_set(), edje_edit_state_copy(), edje_edit_state_external_param_set(), edje_edit_state_font_get(), edje_edit_state_font_set(), edje_edit_state_image_get(), edje_edit_state_name_set(), edje_edit_state_text_get(), edje_edit_state_text_set(), edje_edit_state_text_source_get(), edje_edit_state_text_style_get(), edje_edit_state_text_style_set(), edje_edit_state_tweens_list_get(), edje_edit_style_add(), edje_edit_style_tag_add(), edje_edit_style_tag_name_set(), edje_edit_style_tag_value_get(), edje_edit_style_tag_value_set(), edje_edit_style_tags_list_get(), edje_edit_styles_list_get(), edje_mmap_collection_list(), edje_text_class_set(), eet_alias_get(), eet_eina_stream_data_descriptor_class_set(), eet_mmap(), eet_node_hash_new(), eet_node_list_append(), eet_node_struct_append(), eeze_disk_mount_point_get(), eeze_disk_new(), eeze_disk_new_from_mount(), eeze_disk_udev_get_parent(), eeze_disk_udev_get_property(), eeze_disk_udev_get_sysattr(), eeze_disk_udev_walk_get_sysattr(), eeze_net_new(), eeze_udev_devpath_get_syspath(), eeze_udev_find_by_filter(), eeze_udev_find_by_sysattr(), eeze_udev_find_by_type(), eeze_udev_find_similar_from_syspath(), eeze_udev_syspath_get_devname(), eeze_udev_syspath_get_devpath(), eeze_udev_syspath_get_parent(), eeze_udev_syspath_get_parents(), eeze_udev_syspath_get_property(), eeze_udev_syspath_get_subsystem(), eeze_udev_syspath_get_sysattr(), eeze_udev_walk_get_sysattr(), efreet_desktop_category_add(), efreet_desktop_string_list_parse(), efreet_desktop_type_add(), efreet_desktop_x_field_get(), efreet_desktop_x_field_set(), efreet_icon_extension_add(), efreet_menu_async_parse(), efreet_menu_desktop_insert(), efreet_menu_file_set(), efreet_menu_kde_legacy_init(), efreet_menu_new(), efreet_mime_type_icon_get(), efreet_trash_dir_get(), efreet_uri_decode(), efreet_uri_encode(), efreet_util_path_to_file_id(), eina_error_msg_modify(), eina_error_msg_register(), eina_simple_xml_attribute_new(), eina_simple_xml_node_tag_new(), eina_stringshare_replace(), eina_xattr_value_ls(), eio_dir_copy(), eio_dir_direct_ls(), eio_dir_move(), eio_dir_stat_ls(), eio_dir_unlink(), eio_eet_data_image_write_cipher(), eio_eet_data_read_cipher(), eio_eet_data_write_cipher(), eio_eet_open(), eio_eet_read_cipher(), eio_eet_read_direct(), eio_eet_write_cipher(), eio_file_chmod(), eio_file_chown(), eio_file_copy(), eio_file_direct_ls(), eio_file_direct_stat(), eio_file_ls(), eio_file_mkdir(), eio_file_move(), eio_file_open(), eio_file_stat_ls(), eio_file_unlink(), eio_file_xattr(), eio_monitor_add(), eldbus_object_get(), eldbus_proxy_get(), eldbus_signal_handler_match_extra_vset(), emotion_object_extension_may_play_get(), evas_object_image_extension_can_load_get(), and evas_object_smart_callback_priority_add().

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

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.

EAPI Eina_Stringshare EAPI 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.

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

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

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.

EAPI Eina_Stringshare EAPI 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.

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

Referenced by efreet_trash_dir_get(), eina_stringshare_refplace(), eio_monitor_stringshared_add(), and ethumb_client_thumb_exists().

EAPI void eina_stringshare_del | ( | Eina_Stringshare * | str | ) |

Note that the given string has lost an instance.

Parameters

  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 ecore_con_server_add(), ecore_con_url_free(), ecore_wl_window_free(), edje_available_modules_get(), edje_color_class_del(), edje_edit_data_add(), edje_edit_font_add(), edje_edit_group_data_add(), edje_edit_image_add(), edje_edit_image_usage_list_free(), edje_edit_state_external_param_set(), edje_edit_string_free(), edje_edit_string_list_free(), edje_file_collection_list_free(), edje_text_class_del(), eet_eina_stream_data_descriptor_class_set(), eet_node_del(), eet_node_list_append(), eet_node_struct_append(), eeze_disk_mount(), eeze_disk_mount_wrapper_set(), eeze_disk_new(), eeze_disk_new_from_mount(), eeze_disk_removable_get(), eeze_disk_scan(), eeze_net_free(), efreet_desktop_category_del(), efreet_desktop_free(), efreet_desktop_x_field_set(), efreet_icon_extension_add(), efreet_menu_kde_legacy_init(), efreet_mime_type_icon_get(), efreet_trash_delete_uri(), efreet_trash_dir_get(), efreet_util_path_to_file_id(), eina_error_msg_modify(), eina_simple_xml_attribute_free(), eina_stringshare_refplace(), eina_stringshare_replace(), eina_stringshare_replace_length(), eio_monitor_add(), eldbus_object_get(), eldbus_proxy_get(), emotion_object_extension_may_play_get(), emotion_object_init(), ethumb_client_generate_cancel(), ethumb_client_generate_cancel_all(), ethumb_client_thumb_exists(), evas_object_image_extension_can_load_get(), and evas_render_method_list_free().

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

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

EAPI Eina_Tmpstr* eina_tmpstr_add | ( | const char * | str | ) |

Add a new temporary string based on the input string.

Parameters

  str | This is the input stringthat is copied into the temp string.

Returns
  A pointer to the tmp string that is a standard C string.

When you add a temporary string (tmpstr) it is expected to have a very short lifespan, and at any one time only a few of these are intended to exist. This is not intended for longer term storage of strings. The intended use is the ability to safely pass strings as return values from functions directly into parameters of new functions and then have the string be cleaned up automatically by the caller.

If `str` is NULL, or no memory space exists to store the tmpstr, then NULL will be returned, otherwise a valid string pointer will be returned that you can treat as any other C string (eg strdup(tmpstr) or printf("%s\n", tmpstr) etc.). This string should be considered read-only and immutable, and when youa re done with the string yo should delete it with eina_tmpstr_del().

Example usage:

Eina_Tmpstr *my_homedir(void) {
return eina_tmpstr_add(getenv("HOME"));
}
void my_rmfile(Eina_Tmpstr *str) {
if (!str) return;
unlink(str);
eina_tmpstr_del(str);
}
my_rmfile(my_homedir());
my_rmfile("/tmp/file");

See Also
  eina_tmpstr_del()
  eina_tmpstr_add_length()

Since
  1.8.0

References eina_tmpstr_add_length().

Referenced by eina_file_mkdtemp(), and eina_file_mkstemp().

EAPI Eina_Tmpstr* eina_tmpstr_add_length | ( | const char * | str,
|  | size_t | length
| ) |  |

Add a new temporary string based on the input string and length.

Parameters

  str | This is the input stringthat is copied into the temp string.
  length | This is the maximum length and the allocated length of the temp string.

Returns
  A pointer to the tmp string that is a standard C string.

When you add a temporary string (tmpstr) it is expected to have a very short lifespan, and at any one time only a few of these are intended to exist. This is not intended for longer term storage of strings. The intended use is the ability to safely pass strings as return values from functions directly into parameters of new functions and then have the string be cleaned up automatically by the caller.

If `str` is NULL, or no memory space exists to store the tmpstr, then NULL will be returned, otherwise a valid string pointer will be returned that you can treat as any other C string (eg strdup(tmpstr) or printf("%s\n", tmpstr) etc.). This string should be considered read-only and immutable, and when youa re done with the string yo should delete it with eina_tmpstr_del().

See Also
  eina_tmpstr_del()
  eina_tmpstr_add()

Since
  1.8.0

Referenced by eina_tmpstr_add().

EAPI size_t eina_tmpstr_strlen | ( | Eina_Tmpstr * | tmpstr | ) |

Return the length of a temporary string including the '\0'.

Parameters

  tmpstr | This is any C string pointer, but if it is a tmp string it will return the length faster.

Returns
  The length of the string including the '\0';

Since
  1.8.0

Referenced by eina_file_path_sanitize().

EAPI void eina_tmpstr_del | ( | Eina_Tmpstr * | tmpstr | ) |

Delete the temporary string if it is one, or ignore it if it is not.

Parameters

  tmpstr | This is any C string pointer, but if it is a tmp string it is freed.

This will delete the given temporary string `tmpstr` if it is a valid temporary string, or otherwise it will ignore it and do nothing so this can be used safely with non-temporary strings.

See Also
  eina_tmpstr_add()

Since
  1.8.0