String Buffer
Eina » Data Types

These functions provide string buffer management. More...

## Macros

#define | eina_strbuf_prepend(buf, str)
| Prepends a string to the given buffer.
#define | eina_strbuf_prepend_escaped(buf, str)
| Prepends an escaped string to the given buffer.
#define | eina_strbuf_prepend_n(buf, str, maxlen)
| Prepends an escaped string to the given buffer.
#define | eina_strbuf_prepend_length(buf, str, length)
| Prepends an escaped string to the given buffer.
#define | eina_strbuf_prepend_char(buf, c)
| Prepends a character to the given buffer.
#define | eina_strbuf_prepend_printf(buf, fmt, ...)
| Prepends data elements to the given buffer using printf-style formatting.
#define | eina_strbuf_prepend_vprintf(buf, fmt, args)
| Prepends the given string to the given buffer.
#define | eina_strbuf_replace_first(buf, str, with)
| Replaces the first occurrence of a substring with another string.
#define | eina_strbuf_prepend_strftime(buf, fmt, tm)
| Prepends a strftime-style timestamp to the buffer.

## Typedefs

typedef struct _Eina_Strbuf | Eina_Strbuf
| Type for a string buffer.

## Functions

EINA_API Eina_Strbuf * | eina_strbuf_new (void)
| Creates a new string buffer.
EINA_API Eina_Strbuf * | eina_strbuf_manage_new (char *str)
| Creates a new string buffer using the passed string.
EINA_API Eina_Strbuf * | eina_strbuf_manage_new_length (char *str, size_t length)
| Creates a new string buffer using the passed string.
EINA_API Eina_Strbuf * | eina_strbuf_manage_read_only_new_length (const char *str, size_t length)
| Creates a new string buffer using the passed string.
EINA_API void | eina_strbuf_free (Eina_Strbuf *buf)
| Frees a string buffer.
EINA_API void | eina_strbuf_reset (Eina_Strbuf *buf)
| Resets a string buffer.
EINA_API Eina_Bool | eina_strbuf_append (Eina_Strbuf *buf, const char *str)
| Appends a string to a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_append_escaped (Eina_Strbuf *buf, const char *str)
| Appends an escaped string to a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_append_n (Eina_Strbuf *buf, const char *str, size_t maxlen)
| Appends a string to a buffer, reallocating as necessary, limited by the given length.
EINA_API Eina_Bool | eina_strbuf_append_length (Eina_Strbuf *buf, const char *str, size_t length)
| Appends a string of exact length to a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_append_slice (Eina_Strbuf *buf, const Eina_Slice slice)
| Append a slice to a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_append_buffer (Eina_Strbuf *buf, const Eina_Strbuf *data)
| Appends an Eina_Strbuf to a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_append_char (Eina_Strbuf *buf, char c)
| Appends a character to a string buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_append_printf (Eina_Strbuf *buf, const char *fmt,...) EINA_PRINTF(2
| Appends data elements to a buffer using printf-style formatting.
EINA_API Eina_Bool EINA_API Eina_Bool | eina_strbuf_append_vprintf (Eina_Strbuf *buf, const char *fmt, va_list args)
| Appends data elements to a string buffer using a va_list.
EINA_API Eina_Bool | eina_strbuf_insert (Eina_Strbuf *buf, const char *str, size_t pos)
| Inserts a string into a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_insert_escaped (Eina_Strbuf *buf, const char *str, size_t pos)
| Inserts an escaped string into a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_insert_n (Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos)
| Inserts a string of a maximum length into a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_insert_length (Eina_Strbuf *buf, const char *str, size_t length, size_t pos)
| Inserts a string of an exact length into a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_insert_slice (Eina_Strbuf *buf, const Eina_Slice slice, size_t pos)
| Insert a slice into a buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_insert_char (Eina_Strbuf *buf, char c, size_t pos)
| Inserts a character into a string buffer, reallocating as necessary.
EINA_API Eina_Bool | eina_strbuf_insert_printf (Eina_Strbuf *buf, const char *fmt, size_t pos,...) EINA_PRINTF(2
| Inserts data elements into a buffer using printf-style formatting.
EINA_API Eina_Bool EINA_API Eina_Bool | eina_strbuf_insert_vprintf (Eina_Strbuf *buf, const char *fmt, size_t pos, va_list args)
| Inserts data elements into a buffer using a va_list.
EINA_API Eina_Bool | eina_strbuf_remove (Eina_Strbuf *buf, size_t start, size_t end)
| Removes a section from the given string buffer.
EINA_API const char * | eina_strbuf_string_get (const Eina_Strbuf *buf)
| Retrieves a pointer to the contents of a string buffer.
EINA_API char * | eina_strbuf_string_steal (Eina_Strbuf *buf)
| Steals the contents of a string buffer.
EINA_API void | eina_strbuf_string_free (Eina_Strbuf *buf)
| Frees the contents of a string buffer but not the buffer.
EINA_API size_t | eina_strbuf_length_get (const Eina_Strbuf *buf)
| Retrieves the length of the string buffer's content.
EINA_API Eina_Bool | eina_strbuf_replace (Eina_Strbuf *buf, const char *str, const char *with, unsigned int n)
| Replaces a substring in the buffer with another string.
EINA_API Eina_Bool | eina_strbuf_replace_last (Eina_Strbuf *buf, const char *str, const char *with)
| Replaces the last occurrence of a substring with another string.
EINA_API int | eina_strbuf_replace_all (Eina_Strbuf *buf, const char *str, const char *with)
| Replaces all matching substrings with another string.
EINA_API void | eina_strbuf_trim (Eina_Strbuf *buf)
| Trims the string buffer.
EINA_API void | eina_strbuf_ltrim (Eina_Strbuf *buf)
| Left trims the string buffer.
EINA_API void | eina_strbuf_rtrim (Eina_Strbuf *buf)
| Right trims the string buffer.
EINA_API void | eina_strbuf_tolower (Eina_Strbuf *buf)
| Converts the string to lower case.
EINA_API Eina_Strbuf * | eina_strbuf_substr_get (Eina_Strbuf *buf, size_t pos, size_t len)
| Obtains substring from a source string buffer.
EINA_API Eina_Slice | eina_strbuf_slice_get (const Eina_Strbuf *buf)
| Gets a read-only slice of the buffer contents.
EINA_API Eina_Rw_Slice | eina_strbuf_rw_slice_get (const Eina_Strbuf *buf)
| Gets a read-write slice of the buffer contents.
EINA_API char * | eina_strbuf_release (Eina_Strbuf *buf)
| Frees the buffer, returning its old contents.
EINA_API Eina_Bool | eina_strbuf_append_strftime (Eina_Strbuf *buf, const char *fmt, const struct tm *tm)
| Appends a strftime-style timestamp to the buffer.
EINA_API Eina_Bool | eina_strbuf_insert_strftime (Eina_Strbuf *buf, const char *fmt, const struct tm *tm, size_t pos)
| Inserts a strftime-style timestamp into the buffer.

## Detailed Description

These functions provide string buffer management.

The String Buffer data type is designed to be a mutable string, allowing the appending, prepending or insertion of a string to a buffer.

For more information see this example.

## Macro Definition Documentation

## eina_strbuf_prepend

#define eina_strbuf_prepend | ( |  | buf,
|  |  | str )

Value:
eina_strbuf_insert(buf, str, 0)
eina_strbuf_insert
EINA_API Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos)
Inserts a string into a buffer, reallocating as necessary.

Prepends a string to the given buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be prepended.

This macro simply calls eina_strbuf_insert() with position 0.

## eina_strbuf_prepend_escaped

#define eina_strbuf_prepend_escaped | ( |  | buf,
|  |  | str )

Value:
eina_strbuf_insert_escaped(buf, str, 0)
eina_strbuf_insert_escaped
EINA_API Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos)
Inserts an escaped string into a buffer, reallocating as necessary.

Prepends an escaped string to the given buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be prepended.

This macro simply calls eina_strbuf_insert_escaped() with position 0.

## eina_strbuf_prepend_n

#define eina_strbuf_prepend_n | ( |  | buf,
|  |  | str,
|  |  | maxlen )

Value:
eina_strbuf_insert_n(buf, str, maxlen, 0)
eina_strbuf_insert_n
EINA_API Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos)
Inserts a string of a maximum length into a buffer, reallocating as necessary.

Prepends an escaped string to the given buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to prepend.
  [in] | maxlen | The maximum number of chars to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be prepended.

This macro simply calls eina_strbuf_insert_n() with position 0.

## eina_strbuf_prepend_length

#define eina_strbuf_prepend_length | ( |  | buf,
|  |  | str,
|  |  | length )

Value:
eina_strbuf_insert_length(buf, str, length, 0)
eina_strbuf_insert_length
EINA_API Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size_t length, size_t pos)
Inserts a string of an exact length into a buffer, reallocating as necessary.

Prepends an escaped string to the given buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to prepend.
  [in] | length | The exact length to use.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be prepended.

This macro simply calls eina_strbuf_insert_length() with position 0.

## eina_strbuf_prepend_char

#define eina_strbuf_prepend_char | ( |  | buf,
|  |  | c )

Value:
eina_strbuf_insert_char(buf, c, 0)
eina_strbuf_insert_char
EINA_API Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos)
Inserts a character into a string buffer, reallocating as necessary.

Prepends a character to the given buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | c | The character to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This macro simply calls eina_strbuf_insert_char() with position 0.

## eina_strbuf_prepend_printf

#define eina_strbuf_prepend_printf | ( |  | buf,
|  |  | fmt,
|  |  | ... )

Value:
eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__)

Prepends data elements to the given buffer using printf-style formatting.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | The string to prepend.
  [in] | ... | Variable list of data elements to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE if data could not be prepended.

This macro simply calls eina_strbuf_insert_printf() with position 0.

## eina_strbuf_prepend_vprintf

#define eina_strbuf_prepend_vprintf | ( |  | buf,
|  |  | fmt,
|  |  | args )

Value:
eina_strbuf_insert_vprintf(buf, fmt, 0, args)
eina_strbuf_insert_vprintf
EINA_API Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, size_t pos, va_list args)
Inserts data elements into a buffer using a va_list.
Definition eina_strbuf.c:139

Prepends the given string to the given buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | The string to prepend.
  [in] | args | The variable arguments.

Returns
  EINA_TRUE on success, EINA_FALSE if data could not be prepended.

This macro simply calls eina_strbuf_insert_vprintf() with position 0.

## eina_strbuf_replace_first

#define eina_strbuf_replace_first | ( |  | buf,
|  |  | str,
|  |  | with )

Value:
eina_strbuf_replace(buf, str, with, 1)
eina_strbuf_replace
EINA_API Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char *with, unsigned int n)
Replaces a substring in the buffer with another string.
Definition eina_strbuf_common.c:928

Replaces the first occurrence of a substring with another string.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The text to match.
  [in] | with | The replacement string.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be replaced in `buf`.

This macro simply calls eina_strbuf_replace() with `n` equal to `1`.

Examples
  entry_example.c.

## eina_strbuf_prepend_strftime

#define eina_strbuf_prepend_strftime | ( |  | buf,
|  |  | fmt,
|  |  | tm )

Value:
eina_strbuf_insert_strftime(buf, fmt, tm, 0)
eina_strbuf_insert_strftime
EINA_API Eina_Bool eina_strbuf_insert_strftime(Eina_Strbuf *buf, const char *format, const struct tm *tm, size_t pos)
Inserts a strftime-style timestamp into the buffer.
Definition eina_strbuf.c:234

Prepends a strftime-style timestamp to the buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | The formatting string.
  [in] | tm | The time value.

Returns
  EINA_TRUE on success, EINA_FALSE if `tm` could not be prepended.

This macro simply calls eina_strbuf_insert_strftime() with position 0.

Since
  1.21

## Function Documentation

## eina_strbuf_new()

EINA_API Eina_Strbuf * eina_strbuf_new | ( | void |  | ) |

Creates a new string buffer.

Returns
  Newly allocated string buffer instance, or `NULL` on error.

This function creates a new string buffer. To free the resources, use eina_strbuf_free().

See also
  eina_strbuf_free()
  eina_strbuf_append()
  eina_strbuf_string_get()

Examples
  eina_strbuf_01.c, and entry_example.c.

References EINA_API, EINA_MALLOC, and EINA_WARN_UNUSED_RESULT.

Referenced by ecore_file_app_exe_get(), edje_available_modules_get(), edje_edit_color_classes_source_generate(), edje_edit_data_source_generate(), edje_init(), edje_object_part_text_escaped_set(), eeze_disk_eject(), eeze_disk_mount(), eeze_disk_unmount(), eina_benchmark_run(), eina_log_print_cb_journald(), eina_simple_xml_node_dump(), elm_app_data_dir_get(), elm_textpath_text_user_style_set(), elm_theme_get(), evas_textblock_cursor_content_get(), evas_textblock_style_set(), evas_textblock_text_markup_to_utf8(), and evas_textblock_text_utf8_to_markup().

## eina_strbuf_manage_new()

EINA_API Eina_Strbuf * eina_strbuf_manage_new | ( | char * | str | ) |

Creates a new string buffer using the passed string.

Parameters

  [in] | str | The string to manage.

Returns
  Newly allocated string buffer instance, or `NULL` on error.

This function creates a new string buffer. The passed string is used directly as the buffer, it's effectively the inverse of eina_strbuf_string_steal(). The passed string must be malloc'd, and its ownership will transfer to Eina_Strbuf(do not free it with free()). To free the resources, use eina_strbuf_free().

See also
  eina_strbuf_free()
  eina_strbuf_append()
  eina_strbuf_string_get()

Since
  1.1.0

References EINA_API, EINA_MALLOC, and EINA_WARN_UNUSED_RESULT.

Referenced by eina_strbuf_substr_get().

## eina_strbuf_manage_new_length()

EINA_API Eina_Strbuf * eina_strbuf_manage_new_length | ( | char * | str,
|  | size_t | length )

Creates a new string buffer using the passed string.

Parameters

  [in] | str | The string to manage.
  [in] | length | The length of the string.

Returns
  Newly allocated string buffer instance, or `NULL` on error.

This function creates a new string buffer. The passed string is used directly as the buffer, it's effectively the inverse of eina_strbuf_string_steal(). The passed string must be malloc'd. To free the resources, use eina_strbuf_free().

See also
  eina_strbuf_manage_new()

Since
  1.2.0

References EINA_API, EINA_MALLOC, and EINA_WARN_UNUSED_RESULT.

## eina_strbuf_manage_read_only_new_length()

EINA_API Eina_Strbuf * eina_strbuf_manage_read_only_new_length | ( | const char * | str,
|  | size_t | length )

Creates a new string buffer using the passed string.

Parameters

  [in] | str | The string to manage.
  [in] | length | The length of the string.

Returns
  Newly allocated string buffer instance, or `NULL` on error.

This function creates a new string buffer. The passed string is used directly as the buffer, it's effectively the inverse of eina_strbuf_string_steal(). The passed string is expected to be static or otherwise on the stack rather than the malloc'd string required by eina_strbuf_manage_new_length(). To free the resources, use eina_strbuf_free().

See also
  eina_strbuf_manage_new()
  eina_strbuf_manage_new_length()

Since
  1.9.0

Examples
  eina_strbuf_01.c.

References EINA_API, EINA_MALLOC, and EINA_WARN_UNUSED_RESULT.

## eina_strbuf_free()

EINA_API void eina_strbuf_free | ( | Eina_Strbuf * | buf | ) |

Frees a string buffer.

Parameters

  [in,out] | buf | The string buffer to free.

This function frees the memory of `buf`. `buf` must have been created by eina_strbuf_new().

Examples
  eina_strbuf_01.c, and entry_example.c.

References EINA_API.

Referenced by ecore_evas_aux_hint_add(), ecore_evas_aux_hint_del(), ecore_evas_aux_hint_val_set(), ecore_file_app_exe_get(), edje_available_modules_get(), edje_edit_color_classes_source_generate(), edje_edit_data_source_generate(), edje_edit_full_source_generate(), edje_edit_print_internal_status(), edje_init(), edje_object_part_text_escaped_set(), eeze_disk_free(), eina_benchmark_run(), eina_log_print_cb_journald(), eina_simple_xml_node_dump(), elm_app_data_dir_get(), elm_textpath_text_user_style_set(), elm_theme_get(), evas_textblock_cursor_content_get(), evas_textblock_style_set(), evas_textblock_text_markup_to_utf8(), and evas_textblock_text_utf8_to_markup().

## eina_strbuf_reset()

EINA_API void eina_strbuf_reset | ( | Eina_Strbuf * | buf | ) |

Resets a string buffer.

Parameters

  [in,out] | buf | The string buffer.

This function resets `buf:` the buffer len is set to 0, and the string data is set to '\0'. No memory is freed.

Examples
  eina_strbuf_01.c.

References EINA_API.

Referenced by edje_available_modules_get(), and evas_textblock_style_set().

## eina_strbuf_append()

EINA_API Eina_Bool eina_strbuf_append | ( | Eina_Strbuf * | buf,
|  | const char * | str )

Appends a string to a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to append.

Returns
  EINA_TRUE on success, EINA_FALSE on failure such as if `str` could not be appended.

This function appends `str` to `buf`. It computes the length of `str`, so is slightly slower than eina_strbuf_append_length(). If the length is known beforehand, consider using that variant.

See also
  eina_strbuf_append()
  eina_strbuf_append_length()

Examples
  entry_example.c.

References EINA_API.

Referenced by ecore_file_app_exe_get(), edje_object_part_text_escaped_set(), eeze_disk_mount(), eina_benchmark_run(), eina_strbuf_append_strftime(), elm_app_data_dir_get(), elm_textpath_text_user_style_set(), and evas_textblock_text_markup_to_utf8().

## eina_strbuf_append_escaped()

EINA_API Eina_Bool eina_strbuf_append_escaped | ( | Eina_Strbuf * | buf,
|  | const char * | str )

Appends an escaped string to a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to append.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be appended.

This function escapes and then appends the string `str` to `buf`.

Examples
  eina_strbuf_01.c.

References EINA_API.

## eina_strbuf_append_n()

EINA_API Eina_Bool eina_strbuf_append_n | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | size_t | maxlen )

Appends a string to a buffer, reallocating as necessary, limited by the given length.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to append.
  [in] | maxlen | The maximum number of characters to append.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be appended.

This function appends at most `maxlen` characters of `str` to `buf`. It can't append more than the length of `str`. It computes the length of `str`, so it is slightly slower than eina_strbuf_append_length(). If the length is known beforehand, consider using that variant (`maxlen` should then be checked so that it is greater than the size of `str`).

See also
  eina_strbuf_append()
  eina_strbuf_append_length()

References EINA_API.

## eina_strbuf_append_length()

EINA_API Eina_Bool eina_strbuf_append_length | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | size_t | length )

Appends a string of exact length to a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to append.
  [in] | length | The exact length to use.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be appended.

This function appends `str` to `buf`. `str` must be of size at most `length`. It is slightly faster than eina_strbuf_append() as it does not compute the size of `str`. It is useful when dealing with strings of known size, such as eina_stringshare.

See also
  eina_stringshare_length()
  eina_strbuf_append()
  eina_strbuf_append_n()

Examples
  eina_strbuf_01.c.

References EINA_API.

Referenced by edje_object_part_text_escaped_set(), eina_strbuf_append_vprintf(), elm_app_data_dir_get(), evas_textblock_style_set(), and evas_textblock_text_markup_to_utf8().

## eina_strbuf_append_slice()

EINA_API Eina_Bool eina_strbuf_append_slice | ( | Eina_Strbuf * | buf,
|  | const Eina_Slice | slice )

Append a slice to a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | slice | The slice to append.

Returns
  EINA_TRUE on success, EINA_FALSE if `slice` could not be appended.

This function appends `slice` to `buf`.

Since
  1.19.0

References EINA_API.

## eina_strbuf_append_buffer()

EINA_API Eina_Bool eina_strbuf_append_buffer | ( | Eina_Strbuf * | buf,
|  | const Eina_Strbuf * | data )

Appends an Eina_Strbuf to a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | data | The string buffer to append.

Returns
  EINA_TRUE on success, EINA_FALSE if `data` could not be appended.

This function appends `data` to `buf`. `data` must be allocated and different from `NULL`. It is slightly faster than eina_strbuf_append() as it does not compute the size of `str`.

See also
  eina_strbuf_append()
  eina_strbuf_append_n()
  eina_strbuf_append_length()

Since
  1.9.0

References EINA_API.

## eina_strbuf_append_char()

EINA_API Eina_Bool eina_strbuf_append_char | ( | Eina_Strbuf * | buf,
|  | char | c )

Appends a character to a string buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | c | The character to append.

Returns
  EINA_TRUE on success, EINA_FALSE if `c` could not be appended.

This function appends `c` to `buf`.

Examples
  eina_strbuf_01.c.

References EINA_API.

Referenced by ecore_file_app_exe_get(), elm_theme_get(), and evas_textblock_style_set().

## eina_strbuf_append_printf()

EINA_API Eina_Bool eina_strbuf_append_printf | ( | Eina_Strbuf * | buf,
|  | const char * | fmt,
|  |  | ... )

Appends data elements to a buffer using printf-style formatting.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | A formatting string.
  [in] | ... | Variable list of data parameters to be appended.

Returns
  EINA_TRUE on success, EINA_FALSE if formatted string could not be appended.

This function appends the string defined by the format `fmt` to `buf`, reallocating as necessary. `fmt` must be of a valid format for the printf family of functions.

See also
  eina_strbuf_append()

References EINA_API, EINA_ARG_NONNULL, EINA_PRINTF, and eina_strbuf_append_vprintf().

## eina_strbuf_append_vprintf()

EINA_API Eina_Bool EINA_API Eina_Bool eina_strbuf_append_vprintf | ( | Eina_Strbuf * | buf,
|  | const char * | fmt,
|  | va_list | args )

Appends data elements to a string buffer using a va_list.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | A formatting string.
  [in] | args | The variable arguments.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

See also
  eina_strbuf_append_printf()

References EINA_FALSE, and eina_strbuf_append_length().

Referenced by eina_strbuf_append_printf().

## eina_strbuf_insert()

EINA_API Eina_Bool eina_strbuf_insert | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | size_t | pos )

Inserts a string into a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to insert.
  [in] | pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be inserted.

This function inserts `str` into `buf` at position `pos`. It computes the length of `str`, so is slightly slower than eina_strbuf_insert_length(). If the length is known beforehand, consider using that variant.

References EINA_API, EINA_ARG_NONNULL, and eina_strbuf_insert().

Referenced by eina_strbuf_insert(), and eina_strbuf_insert_vprintf().

## eina_strbuf_insert_escaped()

EINA_API Eina_Bool eina_strbuf_insert_escaped | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | size_t | pos )

Inserts an escaped string into a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to insert.
  [in] | pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be inserted.

This function escapes and inserts the string `str` into `buf` at position `pos`.

Examples
  eina_strbuf_01.c.

References EINA_API, EINA_ARG_NONNULL, and eina_strbuf_insert_escaped().

Referenced by eina_strbuf_insert_escaped().

## eina_strbuf_insert_n()

EINA_API Eina_Bool eina_strbuf_insert_n | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | size_t | maxlen,
|  | size_t | pos )

Inserts a string of a maximum length into a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to insert.
  [in] | maxlen | The maximum number of chars to insert.
  [in] | pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE if `str` could not be inserted.

This function inserts `str` into `buf` at position `pos`, with at most `maxlen` bytes. The number of inserted characters cannot be greater than the length of `str`. It computes the length of `str`, so is slightly slower than eina_strbuf_insert_length(). If the length is known beforehand, consider using that variant (`maxlen` should then be checked so that it is greater than the size of `str`).

References EINA_API, EINA_ARG_NONNULL, and eina_strbuf_insert_n().

Referenced by eina_strbuf_insert_n().

## eina_strbuf_insert_length()

EINA_API Eina_Bool eina_strbuf_insert_length | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | size_t | length,
|  | size_t | pos )

Inserts a string of an exact length into a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The string to insert.
  [in] | length | The exact length to use.
  [in] | pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE if `string` could not be inserted.

This function inserts `str` into `buf`. `str` must be no longer than `length`. It is slightly faster than eina_strbuf_insert() as it does not compute the size of `str`. It is useful when dealing with strings of known size, such as eina_stringshare.

See also
  eina_stringshare_length()
  eina_strbuf_insert()
  eina_strbuf_insert_n()

References EINA_API, EINA_ARG_NONNULL, and eina_strbuf_insert_length().

Referenced by eina_strbuf_insert_length(), and eina_strbuf_insert_strftime().

## eina_strbuf_insert_slice()

EINA_API Eina_Bool eina_strbuf_insert_slice | ( | Eina_Strbuf * | buf,
|  | const Eina_Slice | slice,
|  | size_t | pos )

Insert a slice into a buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | slice | The slice to insert.
  [in] | pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE if `slice` could not be inserted.

This function inserts `slice` into `buf` at position `pos`.

Since
  1.19.0

References EINA_API, EINA_ARG_NONNULL, and eina_strbuf_insert_slice().

Referenced by eina_strbuf_insert_slice().

## eina_strbuf_insert_char()

EINA_API Eina_Bool eina_strbuf_insert_char | ( | Eina_Strbuf * | buf,
|  | char | c,
|  | size_t | pos )

Inserts a character into a string buffer, reallocating as necessary.

Parameters

  [in,out] | buf | The string buffer.
  [in] | c | The character to insert.
  [in] | pos | The position to insert the character.

Returns
  EINA_TRUE on success, EINA_FALSE if `c` could not be inserted.

This function inserts `c` into `buf` at position `pos`.

References EINA_API, EINA_ARG_NONNULL, and eina_strbuf_insert_char().

Referenced by eina_strbuf_insert_char().

## eina_strbuf_insert_printf()

EINA_API Eina_Bool eina_strbuf_insert_printf | ( | Eina_Strbuf * | buf,
|  | const char * | fmt,
|  | size_t | pos,
|  |  | ... )

Inserts data elements into a buffer using printf-style formatting.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | The string to insert.
  [in] | pos | The position to insert the string.
  [in] | ... | Variable list of data parameters to be inserted.

Returns
  EINA_TRUE on success, EINA_FALSE if the string could not be inserted.

This function inserts a string as described by the format `fmt` into `buf` at the position `pos`. `fmt` must be of a valid format for printf family of functions.

References EINA_API, EINA_ARG_NONNULL, EINA_PRINTF, and eina_strbuf_insert_vprintf().

## eina_strbuf_insert_vprintf()

EINA_API Eina_Bool EINA_API Eina_Bool eina_strbuf_insert_vprintf | ( | Eina_Strbuf * | buf,
|  | const char * | fmt,
|  | size_t | pos,
|  | va_list | args )

Inserts data elements into a buffer using a va_list.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | The string to insert.
  [in] | pos | The position to insert the string.
  [in] | args | The variable arguments.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

See also
  eina_strbuf_insert_printf

References EINA_FALSE, and eina_strbuf_insert().

Referenced by eina_strbuf_insert_printf().

## eina_strbuf_remove()

EINA_API Eina_Bool eina_strbuf_remove | ( | Eina_Strbuf * | buf,
|  | size_t | start,
|  | size_t | end )

Removes a section from the given string buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | start | The initial (inclusive) byte position to start removal.
  [in] | end | The final (non-inclusive) byte position to end removal.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function removes a slice of `buf`, starting at `start` (inclusive) and ending at `end` (non-inclusive). Both values are in bytes.

Examples
  eina_strbuf_01.c.

References EINA_API.

## eina_strbuf_string_get()

EINA_API const char * eina_strbuf_string_get | ( | const Eina_Strbuf * | buf | ) |

Retrieves a pointer to the contents of a string buffer.

Parameters

  [in] | buf | The string buffer.

Returns
  The current string in the string buffer.

This function returns the string contained in `buf`. The returned value must not be modified and will no longer be valid if `buf` is modified. In other words, calling eina_strbuf_append() or similar functions will make this pointer invalid. The pointer returned by this function must not be freed.

See also
  eina_strbuf_string_steal()

Examples
  eina_strbuf_01.c, and entry_example.c.

References EINA_API, and EINA_WARN_UNUSED_RESULT.

Referenced by ecore_evas_aux_hint_add(), ecore_evas_aux_hint_del(), ecore_evas_aux_hint_val_set(), edje_available_modules_get(), edje_edit_color_classes_source_generate(), edje_edit_data_source_generate(), edje_init(), edje_object_part_text_escaped_set(), eeze_disk_eject(), eeze_disk_mount(), eeze_disk_unmount(), eina_benchmark_run(), eina_log_print_cb_journald(), eldbus_signal_handler_match_extra_vset(), eldbus_signal_handler_ref(), eldbus_signal_handler_unref(), elm_textpath_text_user_style_set(), elm_theme_get(), and evas_textblock_style_set().

## eina_strbuf_string_steal()

EINA_API char * eina_strbuf_string_steal | ( | Eina_Strbuf * | buf | ) |

Steals the contents of a string buffer.

Parameters

  [in,out] | buf | The string buffer.

Returns
  The string that was contained in `buf`.

This function returns the string contained in `buf`. `buf` is then initialized and does not own the returned string anymore. The caller must release the memory of the returned string by calling free().

See also
  eina_strbuf_string_get()

References EINA_API, EINA_ARG_NONNULL, EINA_MALLOC, eina_strbuf_string_steal(), and EINA_WARN_UNUSED_RESULT.

Referenced by ecore_file_app_exe_get(), edje_edit_full_source_generate(), eina_simple_xml_node_dump(), eina_strbuf_string_steal(), elm_app_data_dir_get(), evas_textblock_cursor_content_get(), evas_textblock_text_markup_to_utf8(), and evas_textblock_text_utf8_to_markup().

## eina_strbuf_string_free()

EINA_API void eina_strbuf_string_free | ( | Eina_Strbuf * | buf | ) |

Frees the contents of a string buffer but not the buffer.

Parameters

  [in,out] | buf | The string buffer.

This function frees the string contained in `buf` without freeing `buf`.

References EINA_API, EINA_ARG_NONNULL, and eina_strbuf_string_free().

Referenced by eeze_disk_mount(), eeze_disk_unmount(), and eina_strbuf_string_free().

## eina_strbuf_length_get()

EINA_API size_t eina_strbuf_length_get | ( | const Eina_Strbuf * | buf | ) |

Retrieves the length of the string buffer's content.

Parameters

  [in,out] | buf | The string buffer.

Returns
  The current length of the string, in bytes.

This function returns the length of `buf`.

Examples
  eina_strbuf_01.c.

References EINA_API, EINA_ARG_NONNULL, eina_strbuf_length_get(), eina_strbuf_replace(), and EINA_WARN_UNUSED_RESULT.

Referenced by eina_strbuf_length_get().

## eina_strbuf_replace()

EINA_API Eina_Bool eina_strbuf_replace | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | const char * | with,
|  | unsigned int | n )

Replaces a substring in the buffer with another string.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The text to match.
  [in] | with | The replacement string.
  [in] | n | The indexed occurrence to be replaced.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function replaces the n-th occurrence of `str` in `buf` with `with`.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and EINA_UNLIKELY.

Referenced by eina_strbuf_length_get().

## eina_strbuf_replace_last()

EINA_API Eina_Bool eina_strbuf_replace_last | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | const char * | with )

Replaces the last occurrence of a substring with another string.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The text to match.
  [in] | with | The replacement string.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function replaces the last occurrence of `str` in `buf` with `with`.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and EINA_UNLIKELY.

## eina_strbuf_replace_all()

EINA_API int eina_strbuf_replace_all | ( | Eina_Strbuf * | buf,
|  | const char * | str,
|  | const char * | with )

Replaces all matching substrings with another string.

Parameters

  [in,out] | buf | The string buffer.
  [in] | str | The text to match.
  [in] | with | The replacement string.

Returns
  Number of replacements made, or `0` on failure.

This function replaces all the occurrences of `str` in `buf` with the string `with`.

Examples
  eina_strbuf_01.c.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_UNLIKELY.

Referenced by eina_benchmark_run().

## eina_strbuf_trim()

EINA_API void eina_strbuf_trim | ( | Eina_Strbuf * | buf | ) |

Trims the string buffer.

Parameters

  [in,out] | buf | The string buffer.

This function removes whitespace at the beginning and end of the buffer's string.

## eina_strbuf_ltrim()

EINA_API void eina_strbuf_ltrim | ( | Eina_Strbuf * | buf | ) |

Left trims the string buffer.

Parameters

  [in,out] | buf | The string buffer.

This function removes whitespace at the beginning of the buffer's string.

## eina_strbuf_rtrim()

EINA_API void eina_strbuf_rtrim | ( | Eina_Strbuf * | buf | ) |

Right trims the string buffer.

Parameters

  [in,out] | buf | The string buffer.

This function removes whitespace at the end of the buffer's string.

## eina_strbuf_tolower()

EINA_API void eina_strbuf_tolower | ( | Eina_Strbuf * | buf | ) |

Converts the string to lower case.

Parameters

  [in,out] | buf | The string buffer.

This function converts all the characters in the buffer's string to lower case.

Since
  1.17

References eina_str_tolower().

## eina_strbuf_substr_get()

EINA_API Eina_Strbuf * eina_strbuf_substr_get | ( | Eina_Strbuf * | buf,
|  | size_t | pos,
|  | size_t | len )

Obtains substring from a source string buffer.

Parameters

  [in] | buf | The string buffer.
  [in] | pos | The (0-based) position where the substring starts.
  [in] | len | The length from `pos` that should be copied.

Returns
  A string buffer containing the substring, or `NULL` if invalid parameters were specified.

This function creates a Eina_Strbuf containing a copy of a substring of buf starting at `pos` with `len` length. If len is 0, then an empty strbuf will be returned.

Since
  1.17

References eina_strbuf_manage_new().

## eina_strbuf_slice_get()

EINA_API Eina_Slice eina_strbuf_slice_get | ( | const Eina_Strbuf * | buf | ) |

Gets a read-only slice of the buffer contents.

Parameters

  [in] | buf | The string buffer.

Returns
  A read-only slice of the current contents. It may become invalid as soon as `buf` is changed.

Since
  1.19

References EINA_API, and EINA_WARN_UNUSED_RESULT.

## eina_strbuf_rw_slice_get()

EINA_API Eina_Rw_Slice eina_strbuf_rw_slice_get | ( | const Eina_Strbuf * | buf | ) |

Gets a read-write slice of the buffer contents.

Parameters

  [in] | buf | The string buffer.

Returns
  A read-write slice for the current contents. It may become invalid as soon as the `buf` is changed, such as through calls like eina_strbuf_append() or eina_strbuf_remove().

Since
  1.19.0

References EINA_API, and EINA_WARN_UNUSED_RESULT.

## eina_strbuf_release()

EINA_API char * eina_strbuf_release | ( | Eina_Strbuf * | buf | ) |

Frees the buffer, returning its old contents.

Parameters

  [in,out] | buf | The string buffer.

Returns
  The string contained by buf. The caller must release the memory of the returned string by calling free().

Since
  1.19

References EINA_API, and EINA_WARN_UNUSED_RESULT.

## eina_strbuf_append_strftime()

EINA_API Eina_Bool eina_strbuf_append_strftime | ( | Eina_Strbuf * | buf,
|  | const char * | fmt,
|  | const struct tm * | tm )

Appends a strftime-style timestamp to the buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | The formatting string.
  [in] | tm | The time value.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function appends a timestamp to the buffer, formatted using strftime. A string of the exact size required by strftime's output is added to the end.

Example usage:

time_t curr_time;
struct tm *info;
Eina_Strbuf *buf = eina_strbuf_new();
curr_time = time(NULL);
info = localtime(&curr_time);
eina_strbuf_append_strftime(buf, "%I:%M%p", info);
//after use
eina_strbuf_free(buf);
eina_strbuf_new
EINA_API Eina_Strbuf * eina_strbuf_new(void)
Creates a new string buffer.
eina_strbuf_append_strftime
EINA_API Eina_Bool eina_strbuf_append_strftime(Eina_Strbuf *buf, const char *format, const struct tm *tm)
Appends a strftime-style timestamp to the buffer.
Definition eina_strbuf.c:220
eina_strbuf_free
EINA_API void eina_strbuf_free(Eina_Strbuf *buf)
Frees a string buffer.
Eina_Strbuf
struct _Eina_Strbuf Eina_Strbuf
Type for a string buffer.
Definition eina_strbuf.h:68

Since
  1.21

References EINA_FALSE, eina_strbuf_append(), eina_strftime(), and EINA_TRUE.

## eina_strbuf_insert_strftime()

EINA_API Eina_Bool eina_strbuf_insert_strftime | ( | Eina_Strbuf * | buf,
|  | const char * | fmt,
|  | const struct tm * | tm,
|  | size_t | pos )

Inserts a strftime-style timestamp into the buffer.

Parameters

  [in,out] | buf | The string buffer.
  [in] | fmt | The formatting string.
  [in] | tm | The time value.
  [in] | pos | The position in the buffer to insert the timestamp.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function inserts a timestamp into the buffer, formatted using strftime. The buffer's length will be increased by the exact amount required by strftime's output.

Example usage:

time_t curr_time;
struct tm *info;
Eina_Strbuf *buf = eina_strbuf_new();
curr_time = time(NULL);
info = localtime(&curr_time);
eina_strbuf_insert_strftime(buf, "%I:%M%p", info, 2);
//after use
eina_strbuf_free(buf);

Since
  1.21

References EINA_FALSE, eina_strbuf_insert_length(), eina_strftime(), and EINA_TRUE.