Tizen Native API  3.0
Unicode String Buffer

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.

Functions

Eina_UStrbufeina_ustrbuf_new (void)
 Creates a new string buffer.
Eina_UStrbufeina_ustrbuf_manage_new (Eina_Unicode *str)
 Creates 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.
Eina_UStrbufeina_ustrbuf_manage_new_length (Eina_Unicode *str, size_t length)
 Creates 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.
void eina_ustrbuf_free (Eina_UStrbuf *buf)
 Frees a string buffer.
void eina_ustrbuf_reset (Eina_UStrbuf *buf)
 Resets a string buffer.
Eina_Bool eina_ustrbuf_append (Eina_UStrbuf *buf, const Eina_Unicode *str) 2)
 Appends a string to a buffer, reallocating as necessary.
Eina_Bool eina_ustrbuf_append_escaped (Eina_UStrbuf *buf, const Eina_Unicode *str) 2)
 Appends an escaped string to a buffer, reallocating as necessary.
Eina_Bool eina_ustrbuf_append_n (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) 2)
 Appends a string to a buffer, reallocating as necessary, limited by the given length.
Eina_Bool eina_ustrbuf_append_length (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) 2)
 Appends a string of exact length to a buffer, reallocating as necessary.
Eina_Bool eina_ustrbuf_append_char (Eina_UStrbuf *buf, Eina_Unicode c)
 Appends a character to a string buffer, reallocating as necessary.
Eina_Bool eina_ustrbuf_insert (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) 2)
 Inserts a string to a buffer, reallocating as necessary.
Eina_Bool eina_ustrbuf_insert_escaped (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) 2)
 Inserts an escaped string to a buffer, reallocating as necessary.
Eina_Bool eina_ustrbuf_insert_n (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) 2)
 Inserts a string to a buffer, reallocating as necessary. Limited by maxlen.
Eina_Bool eina_ustrbuf_insert_length (Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos) 2)
 Inserts a string of exact length to a buffer, reallocating as necessary.
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_Bool eina_ustrbuf_remove (Eina_UStrbuf *buf, size_t start, size_t end)
 Removes a slice of the given string buffer.
const Eina_Unicodeeina_ustrbuf_string_get (const Eina_UStrbuf *buf)
 Retrieves a pointer to the contents of a string buffer.
Eina_Unicodeeina_ustrbuf_string_steal (Eina_UStrbuf *buf)
 Steals the contents of a string buffer.
void eina_ustrbuf_string_free (Eina_UStrbuf *buf)
 Frees the contents of a string buffer but not the buffer.
size_t eina_ustrbuf_length_get (const Eina_UStrbuf *buf)
 Retrieves the length of the string buffer content.

Typedefs

typedef struct _Eina_Strbuf Eina_UStrbuf

Defines

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

Define Documentation

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

Prepends the given string to the given buffer.

Parameters:
bufThe string buffer to prepend to.
strThe 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.

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

Prepends the given unicode character to the given buffer.

Parameters:
bufThe string buffer to prepend to.
cThe 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.

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

Prepends the given escaped string to the given buffer.

Parameters:
bufThe string buffer to prepend to.
strThe 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.

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

Prepends the given escaped string to the given buffer.

Parameters:
bufThe string buffer to prepend to.
strThe string to prepend.
lengthThe 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.

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

Prepends the given escaped string to the given buffer.

Parameters:
bufThe string buffer to prepend to.
strThe string to prepend.
maxlenThe 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.


Typedef Documentation

Type for a string buffer.


Function Documentation

Appends a string to a buffer, reallocating as necessary.

Parameters:
bufThe string buffer to append to.
strThe 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()
Since :
2.3

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

Parameters:
bufThe string buffer to append to.
cThe 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.

Since :
2.3

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

Parameters:
bufThe string buffer to append to.
strThe 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.

Since :
2.3
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:
bufThe string buffer to append to.
strThe string to append.
lengthThe 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()
Since :
2.3
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:
bufThe string buffer to append to.
strThe string to append.
maxlenThe 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()
Since :
2.3

Frees a string buffer.

Parameters:
bufThe string buffer to free.

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

Since :
2.3
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:
bufThe string buffer to insert.
strThe string to insert.
posThe 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.

Since :
2.3
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:
bufThe string buffer to insert to.
cThe char to insert.
posThe 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.

Since :
2.3
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:
bufThe string buffer to insert to.
strThe string to insert.
posThe 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.

Since :
2.3
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:
bufThe string buffer to insert to.
strThe string to insert.
lengthThe exact length to use.
posThe 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()
Since :
2.3
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:
bufThe string buffer to insert to.
strThe string to insert.
maxlenThe maximum number of chars to insert.
posThe 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.

Since :
2.3
size_t eina_ustrbuf_length_get ( const Eina_UStrbuf buf)

Retrieves the length of the string buffer content.

Parameters:
bufThe string buffer.
Returns:
The current length of the string, in bytes.

This function returns the length of buf.

Since :
2.3

Creates 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:
strThe 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 (EFL) :
1.1.0
Since :
2.3
Eina_UStrbuf* eina_ustrbuf_manage_new_length ( Eina_Unicode str,
size_t  length 
)

Creates 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:
strThe string to manage
lengthThe 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 (EFL) :
1.2.0
Since :
2.3

Creates 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()
Since :
2.3
Eina_Bool eina_ustrbuf_remove ( Eina_UStrbuf buf,
size_t  start,
size_t  end 
)

Removes a slice of the given string buffer.

Parameters:
bufThe string buffer to remove a slice.
startThe initial (inclusive) slice position to start removing, in bytes.
endThe 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.

Since :
2.3

Resets a string buffer.

Parameters:
bufThe 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.

Since :
2.3

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

Parameters:
bufThe string buffer to free the string of.

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

Since :
2.3

Retrieves a pointer to the contents of a string buffer.

Parameters:
bufThe 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()
Since :
2.3

Steals the contents of a string buffer.

Parameters:
bufThe 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()
Since :
2.3