Eina_Unicode_String_Buffer_Group(3)

NAME
Eina_Unicode_String_Buffer_Group - Unicode String Buffer

 - These functions provide unicode string buffer management.

SYNOPSIS

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

  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.
EINA_API Eina_UStrbuf * eina_ustrbuf_manage_new (Eina_Unicode *str)
Creates a new string buffer using the passed string.
EINA_API Eina_UStrbuf * eina_ustrbuf_manage_new_length (Eina_Unicode *str, size_t length)
Creates a new string buffer using the passed string.
EINA_API void eina_ustrbuf_free (Eina_UStrbuf *buf)
Frees a string buffer.
EINA_API void eina_ustrbuf_reset (Eina_UStrbuf *buf)
Resets a string buffer.
EINA_API Eina_Bool eina_ustrbuf_append (Eina_UStrbuf *buf, const Eina_Unicode *str)
Appends a string to a buffer, reallocating as necessary.
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.
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.
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.
EINA_API Eina_Bool eina_ustrbuf_append_slice (Eina_UStrbuf *buf, const Eina_Slice slice)
Appends a slice to a buffer, reallocating as necessary.
EINA_API Eina_Bool eina_ustrbuf_append_char (Eina_UStrbuf *buf, Eina_Unicode c)
Appends a character to a string buffer, reallocating as necessary.
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.
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.
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.
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.
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.
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.
EINA_API Eina_Bool eina_ustrbuf_remove (Eina_UStrbuf *buf, size_t start, size_t end)
Removes a section of the given string buffer.
EINA_API const Eina_Unicode * eina_ustrbuf_string_get (const Eina_UStrbuf *buf)
Retrieves a pointer to the contents of a string buffer.
EINA_API Eina_Unicode * eina_ustrbuf_string_steal (Eina_UStrbuf *buf)
Steals the contents of a string buffer.
EINA_API void eina_ustrbuf_string_free (Eina_UStrbuf *buf)
Frees the contents of a string buffer but not the buffer.
EINA_API size_t eina_ustrbuf_length_get (const Eina_UStrbuf *buf)
Retrieves the length of the string buffer's content.
EINA_API Eina_Slice eina_ustrbuf_slice_get (const Eina_UStrbuf *buf)
Gets a read-only slice of the buffer contents.
EINA_API Eina_Rw_Slice eina_ustrbuf_rw_slice_get (const Eina_UStrbuf *buf)
Gets a read-write slice of the buffer contents.
EINA_API Eina_Unicode * eina_ustrbuf_release (Eina_UStrbuf *buf)
Frees the buffer, returning its old contents.

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

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

Prepends a string to the given buffer.

Parameters
    buf The string buffer.
    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.

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

Prepends an escaped string to the given buffer.

Parameters
    buf The string buffer.
    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.

  #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
    buf The string buffer.
    str The string to prepend.
    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.

  #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
    buf The string buffer.
    str The string to prepend.
    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.

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

Prepends a unicode character to the given buffer.

Parameters
    buf The string buffer.
    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_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_API Eina_UStrbuf* eina_ustrbuf_manage_new (Eina_Unicode * str)

Creates a new string buffer using the passed string.

Parameters
    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_API Eina_UStrbuf* eina_ustrbuf_manage_new_length (Eina_Unicode * str, size_t length)

Creates a new string buffer using the passed string.

Parameters
    str The string to manage.
    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_API void eina_ustrbuf_free (Eina_UStrbuf * buf)

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

  EINA_API void eina_ustrbuf_reset (Eina_UStrbuf * buf)

Resets a string buffer.

Parameters
    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_API Eina_Bool eina_ustrbuf_append (Eina_UStrbuf * buf, const Eina_Unicode * str)

Appends a string to a buffer, reallocating as necessary.

Parameters
    buf The string buffer.
    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_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
    buf The string buffer.
    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_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
    buf The string buffer.
    str The string to append.
    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_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
    buf The string buffer.
    str The string to append.
    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_API Eina_Bool eina_ustrbuf_append_slice (Eina_UStrbuf * buf, const Eina_Slice slice)

Appends a slice to a buffer, reallocating as necessary.

Parameters
    buf The string buffer.
    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_API Eina_Bool eina_ustrbuf_append_char (Eina_UStrbuf * buf, Eina_Unicode c)

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

Parameters
    buf The string buffer.
    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_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
    buf The string buffer.
    str The string to insert.
    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_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
    buf The string buffer.
    str The string to insert.
    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_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
    buf The string buffer.
    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 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_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
    buf The string buffer.
    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 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_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
    buf The string buffer.
    slice The slice to insert.
    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_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
    buf The string buffer.
    c The char to insert.
    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_API Eina_Bool eina_ustrbuf_remove (Eina_UStrbuf * buf, size_t start, size_t end)

Removes a section 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.

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

  EINA_API const Eina_Unicode* eina_ustrbuf_string_get (const Eina_UStrbuf * buf)

Retrieves 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, 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_API Eina_Unicode* eina_ustrbuf_string_steal (Eina_UStrbuf * buf)

Steals the contents of a string buffer.

Parameters
    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_API void eina_ustrbuf_string_free (Eina_UStrbuf * buf)

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

Parameters
    buf The string buffer.

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

  EINA_API size_t eina_ustrbuf_length_get (const Eina_UStrbuf * buf)

Retrieves the length of the string buffer's 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_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_API Eina_Slice eina_ustrbuf_slice_get (const Eina_UStrbuf * buf)

Gets a read-only slice of the buffer contents.

Parameters
    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_API Eina_Rw_Slice eina_ustrbuf_rw_slice_get (const Eina_UStrbuf * buf)

Gets a read-write slice of the buffer contents.

Parameters
    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_API Eina_Unicode* eina_ustrbuf_release (Eina_UStrbuf * buf)

Frees the buffer, returning its old contents.

Parameters
    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

Author

Generated automatically by Doxygen for EFL from the source code.