Typedefs | Functions
Stringshare

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...
 
static Eina_Slice eina_stringshare_slice_get (Eina_Stringshare *str)
 Return the read-only memory slice for this stringshare. More...
 
EINA_API Eina_Stringshareeina_stringshare_add_length (const char *str, unsigned int slen)
 Retrieves an instance of a string with a specific size for use in a program. More...
 
EINA_API Eina_Stringshareeina_stringshare_add (const char *str)
 Retrieves an instance of a string for use in a program. More...
 
EINA_API Eina_Stringshareeina_stringshare_printf (const char *fmt,...) EINA_PRINTF(1
 Retrieves an instance of a string for use in a program from a format string. More...
 
EINA_API Eina_Stringshare EINA_API Eina_Stringshareeina_stringshare_vprintf (const char *fmt, va_list args)
 Retrieves an instance of a string for use in a program from a format string. More...
 
EINA_API Eina_Stringshareeina_stringshare_nprintf (unsigned int len, const char *fmt,...) EINA_PRINTF(2
 Retrieves an instance of a string for use in a program from a format string with size limitation. More...
 
EINA_API Eina_Stringshare EINA_API Eina_Stringshareeina_stringshare_ref (Eina_Stringshare *str)
 Increment references of the given shared string. More...
 
EINA_API void eina_stringshare_del (Eina_Stringshare *str)
 Notes that the given string has lost an instance. More...
 
EINA_API int eina_stringshare_strlen (Eina_Stringshare *str)
 Notes that the given string must be shared. More...
 
EINA_API void eina_stringshare_dump (void)
 Dumps the contents of the share_common. More...
 
EINA_API Eina_Tmpstreina_tmpstr_add (const char *str)
 Adds a new temporary string based on the input string. More...
 
EINA_API Eina_Tmpstreina_tmpstr_add_length (const char *str, size_t length)
 Adds a new temporary string based on the input string and length. More...
 
EINA_DEPRECATED EINA_API size_t eina_tmpstr_strlen (Eina_Tmpstr *tmpstr)
 Deprecated Return the length of a temporary string including the '\0'. More...
 
EINA_API size_t eina_tmpstr_len (Eina_Tmpstr *tmpstr)
 Returns the length of a temporary string. More...
 
EINA_API void eina_tmpstr_del (Eina_Tmpstr *tmpstr)
 Deletes the temporary string if it is one, or ignore it if it is not. More...
 
EINA_API Eina_Tmpstreina_tmpstr_manage_new (char *str)
 Adds a new temporary string using the passed string. More...
 
EINA_API Eina_Tmpstreina_tmpstr_manage_new_length (char *str, size_t length)
 Adds a new temporary string using the passed string. 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_API Eina_Stringshare * eina_stringshare_add(const char *str)
Retrieves an instance of a string for use in a program.
Definition: eina_stringshare.c:606
EINA_API void eina_stringshare_del(Eina_Stringshare *str)
Notes that the given string has lost an instance.
Definition: eina_stringshare.c:533
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

◆ eina_stringshare_refplace()

static Eina_Bool eina_stringshare_refplace ( Eina_Stringshare **  p_str,
Eina_Stringshare news 
)
inlinestatic

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_strpointer to the stringhare to be replaced. Must not be NULL, but *p_str may be NULL as it is a valid stringshare handle.
newsnew 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.

◆ eina_stringshare_replace()

static Eina_Bool eina_stringshare_replace ( Eina_Stringshare **  p_str,
const char *  news 
)
inlinestatic

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_strpointer to the stringhare to be replaced. Must not be NULL, but *p_str may be NULL as it is a valid stringshare handle.
newsnew 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_drm2_output_relative_to_set(), ecore_wl2_window_class_set(), ecore_wl2_window_free(), ecore_wl2_window_role_set(), ecore_wl2_window_title_set(), edje_edit_color_class_description_set(), edje_edit_group_name_set(), edje_file_text_class_set(), edje_language_set(), eeze_disk_mount_point_set(), eeze_disk_mount_wrapper_set(), efreet_desktop_environment_set(), efreet_desktop_x_field_get(), elm_app_compile_bin_dir_set(), elm_app_compile_data_dir_set(), elm_app_compile_lib_dir_set(), elm_app_compile_locale_set(), elm_app_desktop_entry_set(), elm_app_info_set(), elm_app_name_set(), elm_config_accel_preference_set(), elm_config_preferred_engine_set(), elm_config_web_backend_set(), elm_icon_thumb_set(), elm_object_tooltip_style_set(), elm_photo_thumb_set(), elm_store_filesystem_directory_set(), elm_theme_set(), elm_thumb_reload(), elm_win_icon_name_set(), ethumb_file_free(), ethumb_file_set(), ethumb_thumb_category_set(), and ethumb_thumb_dir_path_set().

◆ eina_stringshare_replace_length()

static Eina_Bool eina_stringshare_replace_length ( Eina_Stringshare **  p_str,
const char *  news,
unsigned int  slen 
)
inlinestatic

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_strpointer to the stringhare to be replaced. Must not be NULL, but *p_str may be NULL as it is a valid stringshare handle.
newsnew string to be stringshared, may be NULL.
slenThe 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().

◆ eina_stringshare_slice_get()

static Eina_Slice eina_stringshare_slice_get ( Eina_Stringshare str)
inlinestatic

Return the read-only memory slice for this stringshare.

Parameters
strthe stringshare to get a slice.
Returns
A read-only slice.

References eina_stringshare_strlen(), _Eina_Slice::len, and _Eina_Slice::mem.

◆ eina_stringshare_add_length()

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

Retrieves an instance of a string with a specific size for use in a program.

Parameters
[in]strThe string to retrieve an instance of.
[in]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()

References eina_spinlock_release(), and eina_spinlock_take().

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

◆ eina_stringshare_add()

EINA_API Eina_Stringshare * eina_stringshare_add ( const char *  str)

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

Parameters
[in]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()

References eina_stringshare_add_length().

Referenced by ecore_con_socks4_remote_add(), ecore_con_socks5_remote_add(), ecore_con_ssl_server_cafile_add(), ecore_con_ssl_server_cert_add(), ecore_con_ssl_server_crl_add(), ecore_con_ssl_server_privkey_add(), ecore_con_url_custom_new(), ecore_con_url_new(), ecore_drm_device_find(), ecore_drm_tty_open(), ecore_evas_aux_hint_add(), ecore_evas_aux_hint_val_set(), ecore_wl2_window_aux_hints_supported_get(), edje_available_modules_get(), edje_edit_color_class_add(), edje_edit_color_classes_list_get(), edje_edit_color_classes_source_generate(), edje_edit_compiler_get(), edje_edit_data_add(), edje_edit_data_list_get(), edje_edit_data_source_generate(), edje_edit_data_value_get(), edje_edit_external_add(), edje_edit_externals_list_get(), 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_name_set(), edje_edit_image_add(), edje_edit_image_set_images_list_get(), edje_edit_image_set_list_get(), edje_edit_images_list_get(), edje_edit_part_above_get(), edje_edit_part_below_get(), edje_edit_part_copy(), edje_edit_part_item_index_name_get(), edje_edit_part_item_index_name_set(), edje_edit_part_item_index_source_get(), edje_edit_part_item_index_source_set(), edje_edit_part_item_source_get(), edje_edit_part_item_source_set(), edje_edit_part_items_list_get(), edje_edit_part_selected_state_get(), edje_edit_part_source_get(), edje_edit_parts_list_get(), edje_edit_program_add(), edje_edit_program_api_description_get(), edje_edit_program_api_name_get(), edje_edit_program_filter_part_get(), edje_edit_program_filter_state_get(), edje_edit_program_sample_name_get(), edje_edit_program_signal_get(), edje_edit_program_source_get(), edje_edit_program_state2_get(), edje_edit_program_state_get(), edje_edit_program_tone_name_get(), edje_edit_programs_list_get(), edje_edit_size_class_add(), edje_edit_size_classes_list_get(), edje_edit_sound_samples_list_get(), edje_edit_sound_samplesource_get(), edje_edit_sound_tone_add(), edje_edit_sound_tones_list_get(), edje_edit_state_add(), edje_edit_state_color_class_get(), edje_edit_state_color_class_set(), edje_edit_state_external_param_set(), edje_edit_state_font_get(), edje_edit_state_image_get(), edje_edit_state_map_light_get(), edje_edit_state_map_perspective_get(), edje_edit_state_map_rotation_center_get(), edje_edit_state_proxy_source_get(), edje_edit_state_text_class_get(), edje_edit_state_text_class_set(), edje_edit_state_text_get(), edje_edit_state_text_repch_get(), edje_edit_state_text_source_get(), edje_edit_state_text_source_set(), edje_edit_state_text_style_get(), edje_edit_state_text_text_source_get(), edje_edit_state_text_text_source_set(), edje_edit_state_tweens_list_get(), edje_edit_state_vector_get(), edje_edit_style_add(), edje_edit_style_tag_add(), edje_edit_style_tag_value_get(), edje_edit_style_tags_list_get(), edje_edit_styles_list_get(), edje_edit_text_class_add(), edje_edit_text_class_font_get(), edje_edit_text_classes_list_get(), edje_edit_vectors_list_get(), edje_file_text_class_set(), edje_mmap_collection_list(), edje_mmap_color_class_used_list(), edje_object_signal_callback_del_full(), edje_object_text_insert_filter_callback_add(), edje_object_text_markup_filter_callback_add(), 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_subsystem_sysname(), 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_parent_filtered(), eeze_udev_syspath_get_parents(), eeze_udev_syspath_get_property(), eeze_udev_syspath_get_subsystem(), eeze_udev_syspath_get_sysattr(), eeze_udev_syspath_get_sysattr_list(), eeze_udev_walk_get_sysattr(), efl_net_connman_access_point_new(), efl_net_connman_technology_new(), 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_file_set(), efreet_util_path_to_file_id(), eina_error_msg_get(), eina_error_msg_modify(), eina_error_msg_register(), eina_file_virtualize(), eina_simple_xml_attribute_new(), eina_stringshare_replace(), eina_xattr_value_ls(), eio_monitor_add(), eldbus_object_get(), eldbus_proxy_get(), eldbus_signal_handler_match_extra_vset(), elm_color_class_editor_add(), elm_color_class_util_edje_file_list(), elm_config_icon_theme_set(), elm_config_profile_derived_add(), elm_font_fontconfig_name_get(), elm_init(), elm_object_tooltip_text_set(), elm_prefs_file_set(), elm_quicklaunch_init(), elm_theme_copy(), elm_theme_get(), elm_validator_regexp_new(), elua_state_dirs_set(), elua_state_include_path_add(), elua_state_new(), elua_util_require(), emotion_object_extension_may_play_get(), evas_font_path_global_append(), evas_font_path_global_prepend(), evas_object_image_extension_can_load_get(), evas_object_textblock_replace_char_set(), and evas_textblock_style_set().

◆ eina_stringshare_printf()

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

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

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

Referenced by eina_file_virtualize(), and elm_prefs_file_set().

◆ eina_stringshare_vprintf()

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

Parameters
[in]fmtThe NULL-terminated format string to retrieve an instance of.
[in]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_API 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.

Parameters
[in]lenThe length of the format string to use
[in]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()

Increment references of the given shared string.

Parameters
[in,out]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().

References eina_spinlock_release(), and eina_spinlock_take().

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

◆ eina_stringshare_del()

EINA_API void eina_stringshare_del ( Eina_Stringshare str)

Notes that the given string has lost an instance.

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

References eina_spinlock_release(), and eina_spinlock_take().

Referenced by ecore_drm2_device_close(), ecore_drm_device_find(), ecore_drm_inputs_device_axis_size_set(), ecore_drm_tty_close(), ecore_drm_tty_open(), ecore_evas_aux_hint_add(), ecore_evas_aux_hint_del(), ecore_evas_aux_hint_val_set(), ecore_wl2_window_free(), ecore_wl_window_free(), edje_available_modules_get(), edje_edit_data_add(), edje_edit_group_data_add(), edje_edit_image_add(), edje_edit_image_usage_list_free(), edje_edit_limits_list_free(), edje_edit_part_item_index_name_set(), edje_edit_state_external_param_set(), edje_edit_string_free(), edje_edit_string_list_free(), edje_file_collection_list_free(), edje_file_text_class_del(), edje_object_signal_callback_del_full(), edje_object_text_insert_filter_callback_del(), edje_object_text_insert_filter_callback_del_full(), edje_object_text_markup_filter_callback_del(), edje_object_text_markup_filter_callback_del_full(), 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(), eeze_net_new(), efreet_desktop_category_del(), efreet_desktop_free(), efreet_desktop_x_field_set(), efreet_icon_extension_add(), efreet_util_path_to_file_id(), eina_error_msg_modify(), eina_file_clean_close(), eina_file_open(), eina_file_unlink(), eina_simple_xml_attribute_free(), eina_stringshare_refplace(), eina_stringshare_replace(), eina_stringshare_replace_length(), eio_monitor_add(), eio_monitor_stringshared_add(), eldbus_object_get(), eldbus_proxy_get(), elm_config_accel_preference_set(), elm_config_icon_theme_set(), elm_config_preferred_engine_set(), elm_config_profile_list_free(), elm_font_fontconfig_name_free(), elm_font_properties_free(), elm_icon_memfile_set(), elm_object_cursor_unset(), elm_quicklaunch_shutdown(), elm_shutdown(), elm_spinner_special_value_del(), elm_theme_color_class_list(), elm_theme_color_class_list_free(), elm_theme_flush(), elm_theme_set(), elm_validator_regexp_free(), elua_state_dirs_set(), elua_state_free(), elua_state_new(), elua_state_setup(), emotion_object_extension_may_play_get(), ethumb_client_thumb_exists(), evas_font_path_global_clear(), evas_object_image_extension_can_load_get(), evas_object_textblock_replace_char_set(), and evas_render_method_list_free().

◆ eina_stringshare_strlen()

EINA_API int eina_stringshare_strlen ( Eina_Stringshare str)

Notes that the given string must be shared.

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

Referenced by eina_stringshare_slice_get().

◆ eina_stringshare_dump()

EINA_API void eina_stringshare_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.

◆ eina_tmpstr_add()

EINA_API Eina_Tmpstr * eina_tmpstr_add ( const char *  str)

Adds a new temporary string based on the input string.

Parameters
[in]strThis is the input string that 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 (e.g. strdup(tmpstr) or printf("%s\n", tmpstr) etc.). This string should be considered read-only and immutable, and when you are done with the string you should delete it with eina_tmpstr_del().

Example usage:

Eina_Tmpstr *my_homedir(void) {
}
void my_rmfile(Eina_Tmpstr *str) {
if (!str) return;
unlink(str);
}
my_rmfile(my_homedir());
my_rmfile("/tmp/file");
EINA_API void eina_tmpstr_del(Eina_Tmpstr *tmpstr)
Deletes the temporary string if it is one, or ignore it if it is not.
Definition: eina_tmpstr.c:125
EINA_API Eina_Tmpstr * eina_tmpstr_add(const char *str)
Adds a new temporary string based on the input string.
Definition: eina_tmpstr.c:115
const char Eina_Tmpstr
Interchangeable with "const char *" but still a good visual hint for the purpose.
Definition: eina_tmpstr.h:121
EINA_API const char * eina_environment_home_get(void)
Returns the content of the environment referred by HOME on this system.
Definition: eina_util.c:52
See also
eina_tmpstr_del()
eina_tmpstr_add_length()
Since
1.8.0

References eina_tmpstr_add_length().

◆ eina_tmpstr_add_length()

EINA_API Eina_Tmpstr * eina_tmpstr_add_length ( const char *  str,
size_t  length 
)

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

Parameters
[in]strThis is the input string that is copied into the temp string.
[in]lengthThis 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 (e.g. strdup(tmpstr) or printf("%s\n", tmpstr) etc.). This string should be considered read-only and immutable, and when you are done with the string you should delete it with eina_tmpstr_del().

Note
If the length is greater than the actual string, but still '\0' terminated, there won't be any crash and the string will be correct, but eina_tmpstr_len will return an erroneous length. So if you want to have the correct length always call eina_tmpstr_add_length with length == strlen(str).
See also
eina_tmpstr_del()
eina_tmpstr_add()
Since
1.8.0

References EINA_FALSE, eina_lock_release(), and eina_lock_take().

Referenced by eina_file_current_directory_get(), and eina_tmpstr_add().

◆ eina_tmpstr_strlen()

EINA_DEPRECATED EINA_API size_t eina_tmpstr_strlen ( Eina_Tmpstr tmpstr)

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

Parameters
tmpstrThis 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'
Deprecated:
See also
eina_tmpstr_len()
Since
1.8.0

References eina_tmpstr_len().

◆ eina_tmpstr_len()

EINA_API size_t eina_tmpstr_len ( Eina_Tmpstr tmpstr)

Returns the length of a temporary string.

Parameters
[in]tmpstrThis is any C string pointer, but if it is a tmp string it will return the length faster.
Returns
The length of the string.
Since
1.14.0

References eina_lock_release(), and eina_lock_take().

Referenced by eina_file_path_sanitize(), and eina_tmpstr_strlen().

◆ eina_tmpstr_del()

EINA_API void eina_tmpstr_del ( Eina_Tmpstr tmpstr)

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

Parameters
[in]tmpstrThis 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

References eina_lock_release(), and eina_lock_take().

Referenced by eina_file_cleanup(), and eina_file_path_sanitize().

◆ eina_tmpstr_manage_new()

EINA_API Eina_Tmpstr * eina_tmpstr_manage_new ( char *  str)

Adds a new temporary string using the passed string.

The passed string is used directly as the buffer. The passed string must be malloced.

Parameters
[in]strThe input string to manage.
Returns
A pointer to the tmp string that is a standard C string.

This function creates a new temporary string. On error, NULL is returned. To free the resources, use eina_tmpstr_del().

See also
eina_tmpstr_del()
Since
1.17.0

References eina_tmpstr_manage_new_length().

◆ eina_tmpstr_manage_new_length()

EINA_API Eina_Tmpstr * eina_tmpstr_manage_new_length ( char *  str,
size_t  length 
)

Adds a new temporary string using the passed string.

The passed string is used directly as the buffer. The passed string must be malloced.

Parameters
[in]strThe input string to manage.
[in]lengthThe length of the string.
Returns
A pointer to the tmp string that is a standard C string.

This function creates a new temporary string. On error, NULL is returned. To free the resources, use eina_tmpstr_del().

See also
eina_tmpstr_manage_new()
eina_tmpstr_del()
Since
1.17.0

References eina_lock_release(), eina_lock_take(), and EINA_TRUE.

Referenced by eina_tmpstr_manage_new().