Unicode String Buffer

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

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

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

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

## Functions
Eina_UStrbuf * | eina_ustrbuf_new (void)
| Create a new string buffer. More...
Eina_UStrbuf * | eina_ustrbuf_manage_new (Eina_Unicode *str)
| Create a new string buffer using the passed string. More...
Eina_UStrbuf * | eina_ustrbuf_manage_new_length (Eina_Unicode *str, size_t length)
| Create a new string buffer using the passed string. More...
void | eina_ustrbuf_free (Eina_UStrbuf *buf)
| Free a string buffer. More...
void | eina_ustrbuf_reset (Eina_UStrbuf *buf)
| Reset a string buffer. More...
Eina_Bool | eina_ustrbuf_append (Eina_UStrbuf *buf, const Eina_Unicode *str)
| Append a string to a buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_append_escaped (Eina_UStrbuf *buf, const Eina_Unicode *str)
| Append an escaped string to a buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_append_n (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen)
| Append a string to a buffer, reallocating as necessary, limited by the given length. More...
Eina_Bool | eina_ustrbuf_append_length (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length)
| Append a string of exact length to a buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_append_char (Eina_UStrbuf *buf, Eina_Unicode c)
| Append a character to a string buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_insert (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos)
| Insert a string to a buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_insert_escaped (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos)
| Insert an escaped string to a buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_insert_n (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos)
| Insert a string to a buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_insert_length (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos)
| Insert a string of exact length to a buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_insert_char (Eina_UStrbuf *buf, Eina_Unicode c, size_t pos)
| Insert a character to a string buffer, reallocating as necessary. More...
Eina_Bool | eina_ustrbuf_remove (Eina_UStrbuf *buf, size_t start, size_t end)
| Remove a slice of the given string buffer. More...
const Eina_Unicode * | eina_ustrbuf_string_get (const Eina_UStrbuf *buf)
| Retrieve a pointer to the contents of a string buffer. More...
Eina_Unicode * | eina_ustrbuf_string_steal (Eina_UStrbuf *buf)
| Steal the contents of a string buffer. More...
void | eina_ustrbuf_string_free (Eina_UStrbuf *buf)
| Free the contents of a string buffer but not the buffer. More...
size_t | eina_ustrbuf_length_get (const Eina_UStrbuf *buf)
| Retrieve the length of the string buffer content. More...

## Detailed Description

These functions provide unicode string buffers management.

The Unicode String Buffer data type is designed to be a mutable string, allowing to append, prepend or insert a string to a buffer.

## Macro Definition Documentation

## ◆ eina_ustrbuf_prepend

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

Prepend the given string to the given buffer.

Parameters

  buf | The string buffer to prepend to.
  str | The string to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This macro is calling eina_ustrbuf_insert() at position 0.If `buf` can't prepend it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## ◆ eina_ustrbuf_prepend_escaped

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

Prepend the given escaped string to the given buffer.

Parameters

  buf | The string buffer to prepend to.
  str | The string to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This macro is calling eina_ustrbuf_insert_escaped() at position 0. If `buf` can't prepend it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## ◆ eina_ustrbuf_prepend_n

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

Prepend the given escaped string to the given buffer.

Parameters

  buf | The string buffer to prepend to.
  str | The string to prepend.
  maxlen | The maximum number of Eina_Unicode *s to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This macro is calling eina_ustrbuf_insert_n() at position 0. If `buf` can't prepend it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## ◆ eina_ustrbuf_prepend_length

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

Prepend the given escaped string to the given buffer.

Parameters

  buf | The string buffer to prepend to.
  str | The string to prepend.
  length | The exact length to use.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This macro is calling eina_ustrbuf_insert_length() at position 0. If `buf` can't prepend it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## ◆ eina_ustrbuf_prepend_char

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

Prepend the given unicode character to the given buffer.

Parameters

  buf | The string buffer to prepend to.
  c | The Eina_Unicode character to prepend.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This macro is calling eina_ustrbuf_insert_Eina_Unicode *() at position 0. If `buf` can't prepend it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## Function Documentation

## ◆ eina_ustrbuf_new()

Eina_UStrbuf* eina_ustrbuf_new | ( | void |  | ) |

Create a new string buffer.

Returns
  Newly allocated string buffer instance.

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

See also
  eina_ustrbuf_free()
  eina_ustrbuf_append()
  eina_ustrbuf_string_get()

Referenced by evas_textblock_cursor_content_get(), and evas_textblock_cursor_copy().

## ◆ eina_ustrbuf_manage_new()

Eina_UStrbuf* eina_ustrbuf_manage_new | ( | Eina_Unicode * | str | ) |

Create a new string buffer using the passed string.

The passed string is used directly as the buffer, it's somehow the opposite function of eina_ustrbuf_string_steal . The passed string must be malloced.

Parameters

  str | the string to manage

Returns
  Newly allocated string buffer instance.

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

See also
  eina_ustrbuf_free()
  eina_ustrbuf_append()
  eina_ustrbuf_string_get()

Since
  1.1.0

## ◆ eina_ustrbuf_manage_new_length()

Eina_UStrbuf* eina_ustrbuf_manage_new_length | ( | Eina_Unicode * | str,
|  | size_t | length
| ) |  |

Create a new string buffer using the passed string.

The passed string is used directly as the buffer, it's somehow the opposite function of eina_ustrbuf_string_steal . The passed string must be malloced.

Parameters

  str | the string to manage
  length | the length of the string.

Returns
  Newly allocated string buffer instance.

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

See also
  eina_ustrbuf_manage_new()

Since
  1.2.0

## ◆ eina_ustrbuf_free()

void eina_ustrbuf_free | ( | Eina_UStrbuf * | buf | ) |

Free a string buffer.

Parameters

  buf | The string buffer to free.

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

Referenced by evas_textblock_cursor_content_get(), and evas_textblock_cursor_copy().

## ◆ eina_ustrbuf_reset()

void eina_ustrbuf_reset | ( | Eina_UStrbuf * | buf | ) |

Reset a string buffer.

Parameters

  buf | The string buffer to reset.

This function reset `buf:` the buffer len is set to 0, and the string is set to '\0'. No memory is free'd.

## ◆ eina_ustrbuf_append()

Eina_Bool eina_ustrbuf_append | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str
| ) |  |

Append a string to a buffer, reallocating as necessary.

Parameters

  buf | The string buffer to append to.
  str | The string to append.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

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. If `buf` can't append it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

See also
  eina_ustrbuf_append()
  eina_ustrbuf_append_length()

Referenced by evas_textblock_cursor_content_get().

## ◆ eina_ustrbuf_append_escaped()

Eina_Bool eina_ustrbuf_append_escaped | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str
| ) |  |

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

Parameters

  buf | The string buffer to append to.
  str | The string to append.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function appends the escaped string `str` to `buf`. If `str` can not be appended, EINA_FALSE is returned, otherwise, EINA_TRUE is returned.

## ◆ eina_ustrbuf_append_n()

Eina_Bool eina_ustrbuf_append_n | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str,
|  | size_t | maxlen
| ) |  |

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

Parameters

  buf | The string buffer to append to.
  str | The string to append.
  maxlen | The maximum number of characters to append.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function appends at most `maxlen` characters of `str` to `buf`. It can't appends 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`). If `str` can not be appended, EINA_FALSE is returned, otherwise, EINA_TRUE is returned.

See also
  eina_ustrbuf_append()
  eina_ustrbuf_append_length()

## ◆ eina_ustrbuf_append_length()

Eina_Bool eina_ustrbuf_append_length | ( | Eina_UStrbuf * | buf,
|  | const Eina_Unicode * | str,
|  | size_t | length
| ) |  |

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

Parameters

  buf | The string buffer to append to.
  str | The string to append.
  length | The exact length to use.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

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_strngshare. If `buf` can't append it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

See also
  eina_stringshare_length()
  eina_ustrbuf_append()
  eina_ustrbuf_append_n()

Referenced by evas_textblock_cursor_content_get(), and evas_textblock_cursor_copy().

## ◆ eina_ustrbuf_append_char()

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

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

Parameters

  buf | The string buffer to append to.
  c | The char to append.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function inserts `c` to `buf`. If it can not insert it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## ◆ eina_ustrbuf_insert()

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

Insert a string to a buffer, reallocating as necessary.

Parameters

  buf | The string buffer to insert.
  str | The string to insert.
  pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

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. If `buf` can't insert it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## ◆ eina_ustrbuf_insert_escaped()

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

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

Parameters

  buf | The string buffer to insert to.
  str | The string to insert.
  pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function inserts the escaped string `str` to `buf` at position `pos`. If `buf` can't insert `str`, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

## ◆ eina_ustrbuf_insert_n()

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

Insert a string to a buffer, reallocating as necessary.

Limited by maxlen.

Parameters

  buf | The string buffer to insert to.
  str | The string to insert.
  maxlen | The maximum number of chars to insert.
  pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function inserts `str` ot `buf` at position `pos`, with at most `maxlen` bytes. The number of inserted characters can not 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`). If `str` can not be inserted, EINA_FALSE is returned, otherwise, EINA_TRUE is returned.

## ◆ eina_ustrbuf_insert_length()

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

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

Parameters

  buf | The string buffer to insert to.
  str | The string to insert.
  length | The exact length to use.
  pos | The position to insert the string.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function inserts `str` to `buf`. `str` must be of size at most `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_strngshare. If `buf` can't insert it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

See also
  eina_stringshare_length()
  eina_ustrbuf_insert()
  eina_ustrbuf_insert_n()

Referenced by evas_textblock_cursor_text_append().

## ◆ eina_ustrbuf_insert_char()

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

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

Parameters

  buf | The string buffer to insert to.
  c | The char to insert.
  pos | The position to insert the char.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

This function inserts `c` to `buf` at position `pos`. If `buf` can't append it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Referenced by evas_textblock_cursor_format_append().

## ◆ eina_ustrbuf_remove()

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

Remove a slice of the given string buffer.

Parameters

  buf | The string buffer to remove a slice.
  start | The initial (inclusive) slice position to start removing, in bytes.
  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. It returns EINA_FALSE on failure, EINA_TRUE otherwise.

Referenced by evas_textblock_cursor_char_delete(), evas_textblock_cursor_copy(), evas_textblock_cursor_range_delete(), and evas_textblock_node_format_prev_get().

## ◆ eina_ustrbuf_string_get()

const Eina_Unicode* eina_ustrbuf_string_get | ( | const Eina_UStrbuf * | buf | ) |

Retrieve a pointer to the contents of a string buffer.

Parameters

  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, any eina_ustrbuf_append() or similar will make that pointer invalid.

See also
  eina_ustrbuf_string_steal()

Referenced by evas_object_textblock_text_markup_prepend(), evas_textblock_cursor_char_delete(), evas_textblock_cursor_char_next(), evas_textblock_cursor_content_get(), evas_textblock_cursor_copy(), evas_textblock_cursor_format_is_visible_get(), evas_textblock_cursor_text_prepend(), evas_textblock_cursor_word_end(), and evas_textblock_cursor_word_start().

## ◆ eina_ustrbuf_string_steal()

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

Steal the contents of a string buffer.

Parameters

  buf | The string buffer to steal.

Returns
  The current string in the string buffer.

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

void eina_ustrbuf_string_free | ( | Eina_UStrbuf * | buf | ) |

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

Parameters

  buf | The string buffer to free the string of.

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

## ◆ eina_ustrbuf_length_get()

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

Retrieve the length of the string buffer content.

Parameters

  buf | The string buffer.

Returns
  The current length of the string, in bytes.

This function returns the length of `buf`.

Referenced by evas_object_textblock_text_markup_prepend(), evas_textblock_cursor_char_delete(), evas_textblock_cursor_content_get(), evas_textblock_cursor_copy(), evas_textblock_cursor_line_char_last(), 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_text_prepend(), evas_textblock_cursor_word_end(), and evas_textblock_cursor_word_start().