Tizen Native API

This group discusses the functions that provide string buffers management.

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

Functions

Eina_Strbufeina_strbuf_new (void)
 Creates a new string buffer.
Eina_Strbufeina_strbuf_manage_new (char *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_strbuf_string_steal. The passed string must be malloced.
Eina_Strbufeina_strbuf_manage_new_length (char *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_strbuf_string_steal. The passed string must be malloced.
void eina_strbuf_free (Eina_Strbuf *buf)
 Frees a string buffer.
void eina_strbuf_reset (Eina_Strbuf *buf)
 Resets a string buffer.
Eina_Bool eina_strbuf_append (Eina_Strbuf *buf, const char *str)
 Appends a string to a buffer, reallocating as necessary.
Eina_Bool eina_strbuf_append_escaped (Eina_Strbuf *buf, const char *str)
 Appends an escaped string to a buffer, reallocating as necessary.
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_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_Bool eina_strbuf_append_char (Eina_Strbuf *buf, char c)
 Appends a character to a string buffer, reallocating as necessary.
Eina_Bool eina_strbuf_append_printf (Eina_Strbuf *buf, const char *fmt,...)
 Appends a string to a buffer, reallocating as necessary.
Eina_Bool eina_strbuf_append_vprintf (Eina_Strbuf *buf, const char *fmt, va_list args)
 Appends a string to a buffer, reallocating as necessary.
Eina_Bool eina_strbuf_insert (Eina_Strbuf *buf, const char *str, size_t pos)
 Inserts a string into a buffer, reallocating as necessary.
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_Bool eina_strbuf_insert_n (Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos)
 Inserts a string into a buffer, reallocating as necessary. Limited by maxlen.
Eina_Bool eina_strbuf_insert_length (Eina_Strbuf *buf, const char *str, size_t length, size_t pos)
 Inserts a string of exact length into a buffer, reallocating as necessary.
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_Bool eina_strbuf_insert_printf (Eina_Strbuf *buf, const char *fmt, size_t pos,...)
 Inserts a string into a buffer, reallocating as necessary.
Eina_Bool eina_strbuf_insert_vprintf (Eina_Strbuf *buf, const char *fmt, size_t pos, va_list args)
 Inserts a string into a buffer, reallocating as necessary.
Eina_Bool eina_strbuf_remove (Eina_Strbuf *buf, size_t start, size_t end)
 Removes a slice of the given string buffer.
const char * eina_strbuf_string_get (const Eina_Strbuf *buf)
 Gets a pointer to the contents of a string buffer.
char * eina_strbuf_string_steal (Eina_Strbuf *buf)
 Steals the contents of a string buffer.
void eina_strbuf_string_free (Eina_Strbuf *buf)
 Frees the contents of a string buffer but not the buffer.
size_t eina_strbuf_length_get (const Eina_Strbuf *buf)
 Gets the length of the string buffer's content.
Eina_Bool eina_strbuf_replace (Eina_Strbuf *buf, const char *str, const char *with, unsigned int n)
 Replaces the nth string with another string.
int eina_strbuf_replace_all (Eina_Strbuf *buf, const char *str, const char *with)
 Replaces all strings with another string.
void eina_strbuf_trim (Eina_Strbuf *buf)
 Trims the string buffer.
void eina_strbuf_ltrim (Eina_Strbuf *buf)
 Left trims the string buffer.
void eina_strbuf_rtrim (Eina_Strbuf *buf)
 Right trims the string buffer.

Typedefs

typedef struct _Eina_Strbuf Eina_Strbuf
 The structure type for a string buffer.

Defines

#define eina_strbuf_prepend(buf, str)   eina_strbuf_insert(buf, str, 0)
 Prepends the given string to the given buffer.
#define eina_strbuf_prepend_escaped(buf, str)   eina_strbuf_insert_escaped(buf, str, 0)
 Prepends the given escaped string to the given buffer.
#define eina_strbuf_prepend_n(buf, str, maxlen)   eina_strbuf_insert_n(buf, str, maxlen, 0)
 Prepends the given escaped string to the given buffer.
#define eina_strbuf_prepend_length(buf, str, length)   eina_strbuf_insert_length(buf, str, length, 0)
 Prepends the given escaped string to the given buffer.
#define eina_strbuf_prepend_char(buf, c)   eina_strbuf_insert_char(buf, c, 0)
 Prepends the given character to the given buffer.
#define eina_strbuf_prepend_printf(buf, fmt,...)   eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__)
 Prepends the given string to the given buffer.
#define eina_strbuf_prepend_vprintf(buf, fmt, args)   eina_strbuf_insert_vprintf(buf, fmt, 0, args)
 Prepends the given string to the given buffer.
#define eina_strbuf_replace_first(buf, str, with)   eina_strbuf_replace(buf, str, with, 1)
 Prepends the given character to the given buffer.

Define Documentation

#define eina_strbuf_prepend (   buf,
  str 
)    eina_strbuf_insert(buf, str, 0)

Prepends the given string to the given buffer.

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

Since :
2.3.1
Parameters:
bufThe string buffer to prepend to
strThe string to prepend
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
#define eina_strbuf_prepend_char (   buf,
 
)    eina_strbuf_insert_char(buf, c, 0)

Prepends the given character to the given buffer.

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

Since :
2.3.1
Parameters:
bufThe string buffer to prepend to
cThe character to prepend
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure.
#define eina_strbuf_prepend_escaped (   buf,
  str 
)    eina_strbuf_insert_escaped(buf, str, 0)

Prepends the given escaped string to the given buffer.

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

Since :
2.3.1
Parameters:
bufThe string buffer to prepend to
strThe string to prepend
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
#define eina_strbuf_prepend_length (   buf,
  str,
  length 
)    eina_strbuf_insert_length(buf, str, length, 0)

Prepends the given escaped string to the given buffer.

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

Since :
2.3.1
Parameters:
bufThe string buffer to prepend to
strThe string to prepend
lengthThe exact length to use
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
#define eina_strbuf_prepend_n (   buf,
  str,
  maxlen 
)    eina_strbuf_insert_n(buf, str, maxlen, 0)

Prepends the given escaped string to the given buffer.

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

Since :
2.3.1
Parameters:
bufThe string buffer to prepend to
strThe string to prepend
maxlenThe maximum number of chars to prepend
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
#define eina_strbuf_prepend_printf (   buf,
  fmt,
  ... 
)    eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__)

Prepends the given string to the given buffer.

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

Since :
2.3.1
Parameters:
bufThe string buffer to prepend to
fmtThe string to prepend
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
#define eina_strbuf_prepend_vprintf (   buf,
  fmt,
  args 
)    eina_strbuf_insert_vprintf(buf, fmt, 0, args)

Prepends the given string to the given buffer.

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

Since :
2.3.1
Parameters:
bufThe string buffer to prepend to
fmtThe string to prepend
argsThe variable arguments
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
#define eina_strbuf_replace_first (   buf,
  str,
  with 
)    eina_strbuf_replace(buf, str, with, 1)

Prepends the given character to the given buffer.

This macro calls eina_strbuf_replace() with the nth occurrence equal to 1. If buf can't replace it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Since :
2.3.1
Parameters:
bufThe string buffer to work with
strThe string to replace
withThe string to replace with
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure

Function Documentation

Eina_Bool eina_strbuf_append ( Eina_Strbuf buf,
const char *  str 
)

Appends a string to a buffer, reallocating as necessary.

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to append to
[in]strThe string to append
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
See also:
eina_strbuf_append()
eina_strbuf_append_length()

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

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to append to
[in]cThe character to append
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
Eina_Bool eina_strbuf_append_escaped ( Eina_Strbuf buf,
const char *  str 
)

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

This function escapes and then appends the string str to buf. If str cannot be appended, EINA_FALSE is returned, otherwise, EINA_TRUE is returned.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to append to
[in]strThe string to append
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
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.

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to append to
[in]strThe string to append
[in]lengthThe exact length to use
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
See also:
eina_stringshare_length()
eina_strbuf_append()
eina_strbuf_append_n()
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.

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). If str cannot be appended, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to append to
[in]strThe string to append
[in]maxlenThe maximum number of characters to append
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
See also:
eina_strbuf_append()
eina_strbuf_append_length()
Eina_Bool eina_strbuf_append_printf ( Eina_Strbuf buf,
const char *  fmt,
  ... 
)

Appends a string to a buffer, reallocating as necessary.

This function appends the string defined by the format fmt to buf. fmt must be of a valid format from the printf family of functions. If it can't insert it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to append to
[in]fmtThe string to append
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
See also:
eina_strbuf_append()
Eina_Bool eina_strbuf_append_vprintf ( Eina_Strbuf buf,
const char *  fmt,
va_list  args 
)

Appends a string to a buffer, reallocating as necessary.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to append to
[in]fmtThe string to append
[in]argsThe variable arguments
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
See also:
eina_strbuf_append_printf()
void eina_strbuf_free ( Eina_Strbuf buf)

Frees a string buffer.

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to free
Eina_Bool eina_strbuf_insert ( Eina_Strbuf buf,
const char *  str,
size_t  pos 
)

Inserts a string into a buffer, reallocating as necessary.

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. If buf can't insert it, EINA_FALSE

Since :
2.3.1
Parameters:
[in]bufThe string buffer to insert into
[in]strThe string to insert
[in]posThe position at which to insert the string
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
Eina_Bool eina_strbuf_insert_char ( Eina_Strbuf buf,
char  c,
size_t  pos 
)

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

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to insert into
[in]cThe character to insert
[in]posThe position at which to insert the char
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
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.

This function escapes and inserts the string str into buf at position pos. If buf can't insert str, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to insert into
[in]strThe string to insert
[in]posThe position at which to insert the string
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
Eina_Bool eina_strbuf_insert_length ( Eina_Strbuf buf,
const char *  str,
size_t  length,
size_t  pos 
)

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

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to insert into
[in]strThe string to insert
[in]lengthThe exact length to use
[in]posThe position at which to insert the string
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
See also:
eina_stringshare_length()
eina_strbuf_insert()
eina_strbuf_insert_n()
Eina_Bool eina_strbuf_insert_n ( Eina_Strbuf buf,
const char *  str,
size_t  maxlen,
size_t  pos 
)

Inserts a string into a buffer, reallocating as necessary. Limited by maxlen.

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). If str cannot be inserted, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to insert into
[in]strThe string to insert
[in]maxlenThe maximum number of chars to insert
[in]posThe position at which to insert the string
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
Eina_Bool eina_strbuf_insert_printf ( Eina_Strbuf buf,
const char *  fmt,
size_t  pos,
  ... 
)

Inserts a string into a buffer, reallocating as necessary.

This function inserts a string as described by the format fmt into buf at the position pos. fmt must be of a valid format from the printf family of functions. If it can't insert it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to insert into
[in]fmtThe string to insert
[in]posThe position at which to insert the string
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
Eina_Bool eina_strbuf_insert_vprintf ( Eina_Strbuf buf,
const char *  fmt,
size_t  pos,
va_list  args 
)

Inserts a string into a buffer, reallocating as necessary.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to insert into
[in]fmtThe string to insert
[in]posThe position at which to insert the string
[in]argsThe variable arguments
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
See also:
eina_strbuf_insert_printf
size_t eina_strbuf_length_get ( const Eina_Strbuf buf)

Gets the length of the string buffer's content.

This function returns the length of buf.

Since :
2.3.1
Parameters:
[in]bufThe string buffer
Returns:
The current length of the string, in bytes
void eina_strbuf_ltrim ( Eina_Strbuf buf)

Left trims the string buffer.

This function skips whitespaces at the beginning of the buffer.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to work with

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_strbuf_string_steal. The passed string must be malloced.

This function creates a new string buffer. On error, NULL is returned and Eina error is set to EINA_ERROR_OUT_OF_MEMORY. To free the resources, use eina_strbuf_free().

Since (EFL) :
1.1.0
Since :
2.3.1
Parameters:
[in]strThe string to manage
Returns:
A newly allocated string buffer instance
See also:
eina_strbuf_free()
eina_strbuf_append()
eina_strbuf_string_get()
Eina_Strbuf* eina_strbuf_manage_new_length ( char *  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_strbuf_string_steal. The passed string must be malloced.

This function creates a new string buffer. On error, NULL is returned and Eina error is set to EINA_ERROR_OUT_OF_MEMORY. To free the resources, use eina_strbuf_free().

Since (EFL) :
1.2.0
Since :
2.3.1
Parameters:
[in]strThe string to manage
[in]lengthThe length of the string
Returns:
A newly allocated string buffer instance
See also:
eina_strbuf_manage_new()

Creates a new string buffer.

This function creates a new string buffer. On error, NULL is returned and Eina error is set to EINA_ERROR_OUT_OF_MEMORY. To free the resources, use eina_strbuf_free().

Since :
2.3.1
Returns:
A newly allocated string buffer instance
See also:
eina_strbuf_free()
eina_strbuf_append()
eina_strbuf_string_get()
Eina_Bool eina_strbuf_remove ( Eina_Strbuf buf,
size_t  start,
size_t  end 
)

Removes a slice of the given string buffer.

This function removes a slice of buf, starting from start (inclusive) and ending at end (non-inclusive). Both the values are in bytes. It returns EINA_FALSE on failure, otherwise it returns EINA_TRUE.

Since :
2.3.1
Parameters:
bufThe string buffer to remove a slice of
startThe initial (inclusive) slice position to start removing from, in bytes
endThe final (non-inclusive) slice position to finish removing at, in bytes
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
Eina_Bool eina_strbuf_replace ( Eina_Strbuf buf,
const char *  str,
const char *  with,
unsigned int  n 
)

Replaces the nth string with another string.

This function replaces the nth occurrence of str in buf with with. It returns EINA_FALSE on failure, otherwise EINA_TRUE.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to work with
[in]strThe string to replace
[in]withThe string to replace with
[in]nThe number of the fitting string
Returns:
EINA_TRUE on success, otherwise EINA_FALSE on failure
int eina_strbuf_replace_all ( Eina_Strbuf buf,
const char *  str,
const char *  with 
)

Replaces all strings with another string.

This function replaces all the occurrences of str in buf with the string with. This function returns the number of times str has been replaced. On failure, it returns 0.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to work with
[in]strThe string to replace
[in]withThe string to replace with
Returns:
The frequency with which the string is replaced
void eina_strbuf_reset ( Eina_Strbuf buf)

Resets a string buffer.

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to reset
void eina_strbuf_rtrim ( Eina_Strbuf buf)

Right trims the string buffer.

This function skips whitespaces at the end of the buffer.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to work with

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

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

Since :
2.3.1
Parameters:
[in]bufThe string buffer to free the string from
const char* eina_strbuf_string_get ( const Eina_Strbuf buf)

Gets a pointer to the contents of a string buffer.

This function returns the string contained in buf. The returned value must not be modified as it is longer valid if buf is modified. In other words, any eina_strbuf_append() or similar makes that pointer invalid. The pointer returned by this function must not be freed.

Since :
2.3.1
Parameters:
[in]bufThe string buffer
Returns:
The current string in the string buffer
See also:
eina_strbuf_string_steal()

Steals the contents of a 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().

Since :
2.3.1
Parameters:
[in]bufThe string buffer to steal from
Returns:
The current string in the string buffer
See also:
eina_strbuf_string_get()
void eina_strbuf_trim ( Eina_Strbuf buf)

Trims the string buffer.

This function skips whitespaces at the beginning and the end of the buffer.

Since :
2.3.1
Parameters:
[in]bufThe string buffer to work with