Unicode String Buffer

Macros | Typedefs | Functions
Unicode String Buffer
Eina » Data Types

These functions provide unicode string buffer management. More...

## Macros
#define | eina_ustrbuf_prepend(buf, str) eina_ustrbuf_insert(buf, str, 0)
| Prepends a string to the given buffer. More...
#define | eina_ustrbuf_prepend_escaped(buf, str) eina_ustrbuf_insert_escaped(buf, str, 0)
| Prepends an escaped string to the given buffer. More...
#define | eina_ustrbuf_prepend_n(buf, str, maxlen) eina_ustrbuf_insert_n(buf, str, maxlen, 0)
| Prepends an escaped string to the given buffer. More...
#define | eina_ustrbuf_prepend_length(buf, str, length) eina_ustrbuf_insert_length(buf, str, length, 0)
| Prepends an escaped string to the given buffer. More...
#define | eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0)
| Prepends a unicode character to the given buffer. More...

## Typedefs
typedef struct _Eina_Strbuf | Eina_UStrbuf
| Type for a unicode string buffer.

## Functions
EINA_API Eina_UStrbuf * | eina_ustrbuf_new (void)
| Creates a new unicode string buffer. More...
EINA_API Eina_UStrbuf * | eina_ustrbuf_manage_new (Eina_Unicode *str)
| Creates a new string buffer using the passed string. More...
EINA_API Eina_UStrbuf * | eina_ustrbuf_manage_new_length (Eina_Unicode *str, size_t length)
| Creates a new string buffer using the passed string. More...
EINA_API void | eina_ustrbuf_free (Eina_UStrbuf *buf)
| Frees a string buffer. More...
EINA_API void | eina_ustrbuf_reset (Eina_UStrbuf *buf)
| Resets a string buffer. More...
EINA_API Eina_Bool | eina_ustrbuf_append (Eina_UStrbuf *buf, const Eina_Unicode *str)
| Appends a string to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_append_escaped (Eina_UStrbuf *buf, const Eina_Unicode *str)
| Appends an escaped string to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_append_n (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen)
| Appends a string to a buffer, reallocating as necessary, limited by the given length. More...
EINA_API Eina_Bool | eina_ustrbuf_append_length (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length)
| Appends a string of exact length to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_append_slice (Eina_UStrbuf *buf, const Eina_Slice slice)
| Appends a slice to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_append_char (Eina_UStrbuf *buf, Eina_Unicode c)
| Appends a character to a string buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_insert (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos)
| Inserts a string to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_insert_escaped (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos)
| Inserts an escaped string to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_insert_n (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos)
| Inserts a string to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_insert_length (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos)
| Inserts a string of exact length to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_insert_slice (Eina_UStrbuf *buf, const Eina_Slice slice, size_t pos)
| Inserts a slice to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_insert_char (Eina_UStrbuf *buf, Eina_Unicode c, size_t pos)
| Inserts a character to a string buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_ustrbuf_remove (Eina_UStrbuf *buf, size_t start, size_t end)
| Removes a section of the given string buffer. More...
EINA_API const Eina_Unicode * | eina_ustrbuf_string_get (const Eina_UStrbuf *buf)
| Retrieves a pointer to the contents of a string buffer. More...
EINA_API Eina_Unicode * | eina_ustrbuf_string_steal (Eina_UStrbuf *buf)
| Steals the contents of a string buffer. More...
EINA_API void | eina_ustrbuf_string_free (Eina_UStrbuf *buf)
| Frees the contents of a string buffer but not the buffer. More...
EINA_API size_t | eina_ustrbuf_length_get (const Eina_UStrbuf *buf)
| Retrieves the length of the string buffer's content. More...
EINA_API Eina_Slice | eina_ustrbuf_slice_get (const Eina_UStrbuf *buf)
| Gets a read-only slice of the buffer contents. More...
EINA_API Eina_Rw_Slice | eina_ustrbuf_rw_slice_get (const Eina_UStrbuf *buf)
| Gets a read-write slice of the buffer contents. More...
EINA_API Eina_Unicode * | eina_ustrbuf_release (Eina_UStrbuf *buf)
| Frees the buffer, returning its old contents. More...

## Detailed Description

These functions provide unicode string buffer management.

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

## Macro Definition Documentation

## ◆ eina_ustrbuf_prepend

#define eina_ustrbuf_prepend | ( |  | buf,
|  |  | str
| ) |  | eina_ustrbuf_insert(buf, str, 0)

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_ustrbuf_insert() with position 0.

## ◆ eina_ustrbuf_prepend_escaped

#define eina_ustrbuf_prepend_escaped | ( |  | buf,
|  |  | str
| ) |  | eina_ustrbuf_insert_escaped(buf, str, 0)

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_ustrbuf_insert_escaped() with position 0.

## ◆ eina_ustrbuf_prepend_n

#define eina_ustrbuf_prepend_n | ( |  | buf,
|  |  | str,
|  |  | maxlen
| ) |  | eina_ustrbuf_insert_n(buf, str, maxlen, 0)

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 Eina_Unicode *s to prepend.

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

This macro simply calls eina_ustrbuf_insert_n() with position 0.

## ◆ eina_ustrbuf_prepend_length

#define eina_ustrbuf_prepend_length | ( |  | buf,
|  |  | str,
|  |  | length
| ) |  | eina_ustrbuf_insert_length(buf, str, length, 0)

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_ustrbuf_insert_length() with position 0.

## ◆ eina_ustrbuf_prepend_char

#define eina_ustrbuf_prepend_char | ( |  | buf,
|  |  | c
| ) |  | eina_ustrbuf_insert_char(buf, c, 0)

Prepends a unicode character to the given buffer.

Parameters

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

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

This macro is calling eina_ustrbuf_insert_Eina_Unicode() at position 0.

## Function Documentation

## ◆ eina_ustrbuf_new()

EINA_API Eina_UStrbuf* eina_ustrbuf_new | ( | void |  | ) |

Creates a new unicode 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_ustrbuf_free().

See also
  eina_ustrbuf_free()
  eina_ustrbuf_append()
  eina_ustrbuf_string_get()

## ◆ eina_ustrbuf_manage_new()

EINA_API Eina_UStrbuf* eina_ustrbuf_manage_new | ( | Eina_Unicode * | 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 unicode string buffer. The passed string is used directly as the buffer, it's effectively the inverse of eina_ustrbuf_string_steal(). The passed string must be malloc'd. To free the resources, use eina_ustrbuf_free().

See also
  eina_ustrbuf_free()
  eina_ustrbuf_append()
  eina_ustrbuf_string_get()

Since
  1.1.0

## ◆ eina_ustrbuf_manage_new_length()

EINA_API Eina_UStrbuf* eina_ustrbuf_manage_new_length | ( | Eina_Unicode * | 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_ustrbuf_string_steal(). The passed string must be malloc'd. To free the resources, use eina_ustrbuf_free().

See also
  eina_ustrbuf_manage_new()

Since
  1.2.0

## ◆ eina_ustrbuf_free()

EINA_API void eina_ustrbuf_free | ( | Eina_UStrbuf * | 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_ustrbuf_new().

## ◆ eina_ustrbuf_reset()

EINA_API void eina_ustrbuf_reset | ( | Eina_UStrbuf * | 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.

## ◆ eina_ustrbuf_append()

EINA_API Eina_Bool eina_ustrbuf_append | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | 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_ustrbuf_append_length(). If the length is known beforehand, consider using that variant.

See also
  eina_ustrbuf_append()
  eina_ustrbuf_append_length()

## ◆ eina_ustrbuf_append_escaped()

EINA_API Eina_Bool eina_ustrbuf_append_escaped | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | 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 appends the escaped string `str` to `buf`.

## ◆ eina_ustrbuf_append_n()

EINA_API Eina_Bool eina_ustrbuf_append_n | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | 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 is slightly slower than eina_ustrbuf_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_ustrbuf_append()
  eina_ustrbuf_append_length()

## ◆ eina_ustrbuf_append_length()

EINA_API Eina_Bool eina_ustrbuf_append_length | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | 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_ustrbuf_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_ustrbuf_append()
  eina_ustrbuf_append_n()

## ◆ eina_ustrbuf_append_slice()

EINA_API Eina_Bool eina_ustrbuf_append_slice | ( | Eina_UStrbuf * | buf,
|  | const Eina_Slice | slice
| ) |  |

Appends 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

## ◆ eina_ustrbuf_append_char()

EINA_API Eina_Bool eina_ustrbuf_append_char | ( | Eina_UStrbuf * | buf,
|  | Eina_Unicode | c
| ) |  |

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

Parameters

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

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

This function appends `c` to `buf`.

## ◆ eina_ustrbuf_insert()

EINA_API Eina_Bool eina_ustrbuf_insert | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str,
|  | size_t | pos
| ) |  |

Inserts a string to 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` to `buf` at position `pos`. It computes the length of `str`, so is slightly slower than eina_ustrbuf_insert_length(). If the length is known beforehand, consider using that variant.

## ◆ eina_ustrbuf_insert_escaped()

EINA_API Eina_Bool eina_ustrbuf_insert_escaped | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str,
|  | size_t | pos
| ) |  |

Inserts an escaped string to 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 the escaped string `str` to `buf` at position `pos`.

## ◆ eina_ustrbuf_insert_n()

EINA_API Eina_Bool eina_ustrbuf_insert_n | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str,
|  | size_t | maxlen,
|  | size_t | pos
| ) |  |

Inserts a string to a buffer, reallocating as necessary.

Limited by maxlen.

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

## ◆ eina_ustrbuf_insert_length()

EINA_API Eina_Bool eina_ustrbuf_insert_length | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str,
|  | size_t | length,
|  | size_t | pos
| ) |  |

Inserts a string of exact length to 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 `str` could not be inserted.

This function inserts `str` into `buf`. `str` must be no longer than `length`. It is slightly faster than eina_ustrbuf_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_ustrbuf_insert()
  eina_ustrbuf_insert_n()

## ◆ eina_ustrbuf_insert_slice()

EINA_API Eina_Bool eina_ustrbuf_insert_slice | ( | Eina_UStrbuf * | buf,
|  | const Eina_Slice | slice,
|  | size_t | pos
| ) |  |

Inserts a slice to 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` to `buf` at position `pos`.

Since
  1.19.0

## ◆ eina_ustrbuf_insert_char()

EINA_API Eina_Bool eina_ustrbuf_insert_char | ( | Eina_UStrbuf * | buf,
|  | Eina_Unicode | c,
|  | size_t | pos
| ) |  |

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

Parameters

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

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

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

## ◆ eina_ustrbuf_remove()

EINA_API Eina_Bool eina_ustrbuf_remove | ( | Eina_UStrbuf * | buf,
|  | size_t | start,
|  | size_t | end
| ) |  |

Removes a section of the given string buffer.

Parameters

  [in,out] | buf | The string buffer to remove a slice.
  [in] | start | The initial (inclusive) slice position to start removing, in bytes.
  [in] | end | The final (non-inclusive) slice position to finish removing, in bytes.

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.

Referenced by evas_textblock_cursor_char_delete(), evas_textblock_cursor_range_delete(), and evas_textblock_node_format_remove_pair().

## ◆ eina_ustrbuf_string_get()

EINA_API const Eina_Unicode* eina_ustrbuf_string_get | ( | const Eina_UStrbuf * | 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_ustrbuf_append() or similar functions will make this pointer invalid.

See also
  eina_ustrbuf_string_steal()

Referenced by evas_textblock_cursor_char_delete(), evas_textblock_cursor_content_get(), evas_textblock_cursor_word_end(), and evas_textblock_cursor_word_start().

## ◆ eina_ustrbuf_string_steal()

EINA_API Eina_Unicode* eina_ustrbuf_string_steal | ( | Eina_UStrbuf * | buf | ) |

Steals the contents of a string buffer.

Parameters

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

## ◆ eina_ustrbuf_string_free()

EINA_API void eina_ustrbuf_string_free | ( | Eina_UStrbuf * | 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`.

## ◆ eina_ustrbuf_length_get()

EINA_API size_t eina_ustrbuf_length_get | ( | const Eina_UStrbuf * | buf | ) |

Retrieves the length of the string buffer's content.

Parameters

  [in] | buf | The string buffer.

Returns
  The current length of the string, in bytes.

This function returns the length of `buf`.

Referenced by evas_textblock_cursor_char_delete(), evas_textblock_cursor_paragraph_char_last(), evas_textblock_cursor_paragraph_text_length_get(), evas_textblock_cursor_pos_get(), evas_textblock_cursor_pos_set(), evas_textblock_cursor_range_delete(), evas_textblock_cursor_word_end(), and evas_textblock_cursor_word_start().

## ◆ eina_ustrbuf_slice_get()

EINA_API Eina_Slice eina_ustrbuf_slice_get | ( | const Eina_UStrbuf * | buf | ) |

Gets a read-only slice of the buffer contents.

Parameters

  [in] | buf | The string buffer.

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

Since
  1.19

## ◆ eina_ustrbuf_rw_slice_get()

EINA_API Eina_Rw_Slice eina_ustrbuf_rw_slice_get | ( | const Eina_UStrbuf * | 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_ustrbuf_append() or eina_ustrbuf_remove().

Since
  1.19.0

## ◆ eina_ustrbuf_release()

EINA_API Eina_Unicode* eina_ustrbuf_release | ( | Eina_UStrbuf * | 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