Binary Buffer

---

These functions provide string buffers management.

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

Functions
Eina_Binbuf *	eina_binbuf_new (void)
	Creates a new string buffer.
Eina_Binbuf *	eina_binbuf_manage_new_length (unsigned 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_binbuf_string_steal . The passed string must be malloced.
Eina_Binbuf *	eina_binbuf_manage_new (const unsigned char *str, size_t length, Eina_Bool ro)
	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_binbuf_string_steal .
void	eina_binbuf_free (Eina_Binbuf *buf)
	Frees a string buffer.
void	eina_binbuf_reset (Eina_Binbuf *buf)
	Resets a string buffer.
Eina_Bool	eina_binbuf_append_length (Eina_Binbuf *buf, const unsigned char *str, size_t length)
	Appends a string of exact length to a buffer, reallocating as necessary.
Eina_Bool	eina_binbuf_append_buffer (Eina_Binbuf *buf, const Eina_Binbuf *data)
	Appends an Eina_Binbuf to a buffer, reallocating as necessary.
Eina_Bool	eina_binbuf_append_char (Eina_Binbuf *buf, unsigned char c)
	Appends a character to a string buffer, reallocating as necessary.
Eina_Bool	eina_binbuf_insert_length (Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos)
	Inserts a string of exact length to a buffer, reallocating as necessary.
Eina_Bool	eina_binbuf_insert_char (Eina_Binbuf *buf, unsigned char c, size_t pos)
	Inserts a character to a string buffer, reallocating as necessary.
Eina_Bool	eina_binbuf_remove (Eina_Binbuf *buf, size_t start, size_t end)
	Removes a slice of the given string buffer.
const unsigned char *	eina_binbuf_string_get (const Eina_Binbuf *buf)
	Retrieves a pointer to the contents of a string buffer.
unsigned char *	eina_binbuf_string_steal (Eina_Binbuf *buf)
	Steals the contents of a string buffer.
void	eina_binbuf_string_free (Eina_Binbuf *buf)
	Frees the contents of a string buffer but not the buffer.
size_t	eina_binbuf_length_get (const Eina_Binbuf *buf)
	Retrieves the length of the string buffer content.
Typedefs
typedef struct _Eina_Strbuf	Eina_Binbuf

---

Typedef Documentation

Eina_Binbuf

Type for a string buffer.

---

Function Documentation

Eina_Bool eina_binbuf_append_buffer	(	Eina_Binbuf *	buf,
		const Eina_Binbuf *	data
	)

Appends an Eina_Binbuf to a buffer, reallocating as necessary.

Parameters:

buf	The string buffer to append to.
data	The string buffer to append.

Returns:

EINA_TRUE on success, EINA_FALSE on failure.

This function appends data to buf. data must be allocated and different from NULL. It is slightly faster than eina_binbuf_append() as it does not compute the size of str. If buf can't append it, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

See also:

eina_binbuf_append()

eina_binbuf_append_n()

eina_binbuf_append_length()

Since (EFL) :

1.9.0

Since :

3.0

Eina_Bool eina_binbuf_append_char	(	Eina_Binbuf *	buf,
		unsigned char	c
	)

Appends 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.

Since :

2.3

Eina_Bool eina_binbuf_append_length	(	Eina_Binbuf *	buf,
		const unsigned char *	str,
		size_t	length
	)

Appends 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_binbuf_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_binbuf_append()

eina_binbuf_append_n()

Since :

2.3

void eina_binbuf_free

(

Eina_Binbuf *

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

Since :

2.3

Eina_Bool eina_binbuf_insert_char	(	Eina_Binbuf *	buf,
		unsigned char	c,
		size_t	pos
	)

Inserts 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.

Since :

2.3

Eina_Bool eina_binbuf_insert_length	(	Eina_Binbuf *	buf,
		const unsigned char *	str,
		size_t	length,
		size_t	pos
	)

Inserts 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_binbuf_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_binbuf_insert()

eina_binbuf_insert_n()

Since :

2.3

size_t eina_binbuf_length_get

(

const Eina_Binbuf *

buf

)

Retrieves 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.

Since :

2.3

Eina_Binbuf* eina_binbuf_manage_new	(	const unsigned char *	str,
		size_t	length,
		Eina_Bool	ro
	)

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_binbuf_string_steal .

Parameters:

str	The string to start from.
length	The length of the string.
ro	The passed string will not be touched if set to EINA_TRUE.

Returns:

Newly allocated string buffer instance.

This function creates a new string buffer. On error, NULL is returned. To free the resources, use eina_binbuf_free(). It will not touch the buffer if ro is set to EINA_TRUE, but it will also not copy it. If ro is set to EINA_TRUE any change operation will create a fresh new memory, copy old data there and starting modifying that one.

See also:

eina_binbuf_manage_new()

eina_binbuf_manage_new_length()

eina_binbuf_manage_read_only_new_length()

Since (EFL) :

1.14.0

Since :

3.0

Eina_Binbuf* eina_binbuf_manage_new_length	(	unsigned 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_binbuf_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_binbuf_free().

See also:

eina_binbuf_manage_new()

Since (EFL) :

1.2.0

Since :

2.3

Eina_Binbuf* eina_binbuf_new

(

void

)

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

See also:

eina_binbuf_free()

eina_binbuf_append()

eina_binbuf_string_get()

Since :

2.3

Eina_Bool eina_binbuf_remove	(	Eina_Binbuf *	buf,
		size_t	start,
		size_t	end
	)

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

Since :

2.3

void eina_binbuf_reset

(

Eina_Binbuf *

buf

)

Resets 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.

Since :

2.3

void eina_binbuf_string_free

(

Eina_Binbuf *

buf

)

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

Since :

2.3

const unsigned char* eina_binbuf_string_get

(

const Eina_Binbuf *

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

See also:

eina_binbuf_string_steal()

Since :

2.3

unsigned char* eina_binbuf_string_steal

(

Eina_Binbuf *

buf

)

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

Since :

2.3