These functions provide string buffer management. More...

Typedefs
typedef struct _Eina_Strbuf	Eina_Binbuf
	Type for a binary string buffer.

Functions
EAPI Eina_Binbuf *	eina_binbuf_new (void) EINA_MALLOC EINA_WARN_UNUSED_RESULT
	Creates a new binary string buffer. More...

EAPI Eina_Binbuf *	eina_binbuf_manage_new (const unsigned char *str, size_t length, Eina_Bool ro) EINA_MALLOC EINA_WARN_UNUSED_RESULT
	Creates a new string buffer using the passed string. More...

EAPI Eina_Binbuf *	eina_binbuf_manage_new_length (unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED
	Creates a new string buffer using the passed string. More...

EAPI Eina_Binbuf *	eina_binbuf_manage_read_only_new_length (const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED
	Creates a new string buffer using the passed string. More...

EAPI void	eina_binbuf_free (Eina_Binbuf *buf) EINA_ARG_NONNULL(1)
	Frees a string buffer. More...

EAPI void	eina_binbuf_reset (Eina_Binbuf *buf) EINA_ARG_NONNULL(1)
	Resets a string buffer. More...

EAPI Eina_Rw_Slice	eina_binbuf_expand (Eina_Binbuf *buf, size_t minimum_unused_space) EINA_ARG_NONNULL(1)
	Expands a buffer, making room for at least `minimum_unused_space`. More...

EAPI Eina_Bool	eina_binbuf_use (Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NONNULL(1)
	Marks more bytes as used. More...

EAPI Eina_Bool	eina_binbuf_append_length (Eina_Binbuf buf, const unsigned char str, size_t length) EINA_ARG_NONNULL(1
	Appends a string of exact length to a buffer, reallocating as necessary. More...

EAPI Eina_Bool EAPI Eina_Bool	eina_binbuf_append_slice (Eina_Binbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1)
	Appends a slice to a buffer, reallocating as necessary. More...

EAPI Eina_Bool	eina_binbuf_append_buffer (Eina_Binbuf buf, const Eina_Binbuf data) EINA_ARG_NONNULL(1
	Appends an Eina_Binbuf to a buffer, reallocating as necessary. More...

EAPI Eina_Bool EAPI Eina_Bool	eina_binbuf_append_char (Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1)
	Appends a character to a string buffer, reallocating as necessary. More...

EAPI Eina_Bool	eina_binbuf_insert_length (Eina_Binbuf buf, const unsigned char str, size_t length, size_t pos) EINA_ARG_NONNULL(1
	Inserts a string of exact length into a buffer, reallocating as necessary. More...

EAPI Eina_Bool EAPI Eina_Bool	eina_binbuf_insert_slice (Eina_Binbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1)
	Inserts a slice into a buffer, reallocating as necessary. More...

EAPI Eina_Bool	eina_binbuf_insert_char (Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1)
	Inserts a character into a string buffer, reallocating as necessary. More...

EAPI Eina_Bool	eina_binbuf_remove (Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1)
	Removes a slice of the given string buffer. More...

EAPI const unsigned char *	eina_binbuf_string_get (const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT
	Retrieves a pointer to the contents of a string buffer. More...

EAPI unsigned char *	eina_binbuf_string_steal (Eina_Binbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
	Steals the contents of a string buffer. More...

EAPI void	eina_binbuf_string_free (Eina_Binbuf *buf) EINA_ARG_NONNULL(1)
	Frees the contents of a string buffer but not the buffer. More...

EAPI size_t	eina_binbuf_length_get (const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT
	Retrieves the length of the string buffer's content. More...

EAPI Eina_Slice	eina_binbuf_slice_get (const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
	Gets a read-only slice of the buffer contents. More...

EAPI Eina_Rw_Slice	eina_binbuf_rw_slice_get (const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
	Gets a read-write slice of the buffer contents. More...

EAPI unsigned char *	eina_binbuf_release (Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
	Frees the buffer, returning its old contents. More...

Detailed Description

These functions provide string buffer management.

The Binary Buffer data type is designed to be a mutable string, allowing the appending, prepending or insertion of a string to a buffer.

Function Documentation

◆ eina_binbuf_new()

EAPI Eina_Binbuf* eina_binbuf_new ( void )

Creates a new binary 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_binbuf_free().

See also: eina_binbuf_free(); eina_binbuf_append(); eina_binbuf_string_get()

Referenced by ecore_con_server_send(), and eina_value_to_binbuf().

◆ eina_binbuf_manage_new()

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

Parameters

[in]	str	The string to manage.
[in]	length	The length of the string.
[in]	ro	The passed string will not be touched if set to EINA_TRUE.

Returns: Newly allocated string buffer instance, or NULL on error.

This function creates a new binary string buffer. The passed string is used directly as the buffer, it's effectively the inverse of eina_binbuf_string_steal().

If ro is EINA_TRUE, then str will be treated as read-only. Other routines using this buffer that would normally modify the string, will instead create a separate copy to modify and return.

To free the resources, use eina_binbuf_free().

See also: eina_binbuf_manage_new(); eina_binbuf_manage_new_length(); eina_binbuf_manage_read_only_new_length()

Since: 1.14.0

Referenced by ecore_con_eet_raw_send(), eet_alias(), eet_write_cipher(), and emile_decompress().

◆ eina_binbuf_manage_new_length()

EAPI Eina_Binbuf* eina_binbuf_manage_new_length	(	unsigned char *	str,
		size_t	length
	)

Creates a new string buffer using the passed string.

Parameters

[in]	str	The string to manage.
[in]	length	The length of the string.

Returns: Newly allocated string buffer instance, or NULL on error.

This function creates a new string buffer. To free the resources, use eina_binbuf_free().

See also: eina_binbuf_manage_new()

Since: 1.2.0

◆ eina_binbuf_manage_read_only_new_length()

EAPI Eina_Binbuf* eina_binbuf_manage_read_only_new_length	(	const unsigned char *	str,
		size_t	length
	)

Creates a new string buffer using the passed string.

Parameters

[in]	str	The string to start from.
[in]	length	The length of the string.

Returns: Newly allocated string buffer instance, or NULL on error.

This function creates a new read-only string buffer. The passed string is used directly as the buffer, it's effectively the inverse of eina_binbuf_string_steal(). Other routines using this buffer that would normally modify the string, will instead create a separate copy to modify and return.

To free the resources, use eina_binbuf_free().

See also: eina_binbuf_manage_new()

Since: 1.9.0

◆ eina_binbuf_free()

EAPI void eina_binbuf_free ( Eina_Binbuf * buf )

Frees a string buffer.

Parameters

[in,out] buf The string buffer.

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

Referenced by ecore_con_eet_raw_send(), eet_alias_get(), eet_read_direct(), and emile_decompress().

◆ eina_binbuf_reset()

EAPI void eina_binbuf_reset ( Eina_Binbuf * buf )

Resets a string buffer.

Parameters

[in,out] buf The string buffer.

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

◆ eina_binbuf_expand()

EAPI Eina_Rw_Slice eina_binbuf_expand	(	Eina_Binbuf *	buf,
		size_t	minimum_unused_space
	)

Expands a buffer, making room for at least minimum_unused_space.

Parameters

[in,out]	buf	The Buffer to expand.
[in]	minimum_unused_space	The minimum unused allocated space, in bytes, at the end of the buffer. Zero can be used to query the available slice of unused bytes.

Returns: The slice of unused bytes. The slice length may be zero if minimum_unused_space couldn't be allocated, otherwise it will be at least minimum_unused_space. After bytes are used, mark them as such using eina_binbuf_use().

One of the properties of the buffer is that it may overallocate space, thus it may have more than eina_binbuf_length_get() bytes allocated. How much depends on the buffer growth logic, but this function allows requesting a minimum amount of bytes to be allocated at the end of the buffer.

This is particularly useful to write directly to buffer's memory (i.e.: a call to read(2)). After the bytes are used call eina_binbuf_use() to mark them as such, so eina_binbuf_length_get() will account for the new bytes.

See also: eina_binbuf_rw_slice_get(); eina_binbuf_use()

Since: 1.19

◆ eina_binbuf_use()

EAPI Eina_Bool eina_binbuf_use	(	Eina_Binbuf *	buf,
		size_t	extra_bytes
	)

Marks more bytes as used.

Parameters

[in,out]	buf	The string buffer.
[in]	extra_bytes	the number of bytes to be considered used, must be between zero and the length of the slice returned by eina_binbuf_expand().

Returns: EINA_TRUE on success, EINA_FALSE on failure, such as extra_bytes is too big or buf is NULL.

This function should be used after eina_binbuf_expand(), marking the extra bytes returned there as used, then they will be taken into account by other functions, such as eina_binbuf_length_get().

See also: eina_binbuf_expand()

Since: 1.19

◆ eina_binbuf_append_length()

EAPI 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

[in,out]	buf	The string buffer.
[in]	str	The string to append.
[in]	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_binbuf_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_binbuf_append(); eina_binbuf_append_n()

Referenced by ecore_con_server_send(), and eina_value_to_binbuf().

◆ eina_binbuf_append_slice()

EAPI Eina_Bool EAPI Eina_Bool eina_binbuf_append_slice	(	Eina_Binbuf *	buf,
		const Eina_Slice	slice
	)

Appends a slice to a buffer, reallocating as necessary.

Parameters

[in,out]	buf	The string buffer.
[in]	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

◆ eina_binbuf_append_buffer()

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

Appends an Eina_Binbuf to a buffer, reallocating as necessary.

Parameters

[in,out]	buf	The string buffer.
[in]	data	The string buffer to append.

Returns: EINA_TRUE on success, EINA_FALSE if data could not be appended.

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

See also: eina_binbuf_append(); eina_binbuf_append_n(); eina_binbuf_append_length()

Since: 1.9.0

◆ eina_binbuf_append_char()

EAPI Eina_Bool EAPI Eina_Bool eina_binbuf_append_char	(	Eina_Binbuf *	buf,
		unsigned char	c
	)

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

Parameters

[in,out]	buf	The string buffer.
[in]	c	The char to append.

Returns: EINA_TRUE on success, EINA_FALSE if c could not be inserted.

This function appends c to buf.

◆ eina_binbuf_insert_length()

EAPI 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 into a buffer, reallocating as necessary.

Parameters

[in,out]	buf	The string buffer.
[in]	str	The string to insert.
[in]	length	The exact length to use.
[in]	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_binbuf_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_binbuf_insert(); eina_binbuf_insert_n()

◆ eina_binbuf_insert_slice()

EAPI Eina_Bool EAPI Eina_Bool eina_binbuf_insert_slice	(	Eina_Binbuf *	buf,
		const Eina_Slice	slice,
		size_t	pos
	)

Inserts a slice into a buffer, reallocating as necessary.

Parameters

[in,out]	buf	The string buffer.
[in]	slice	The slice to insert.
[in]	pos	The position to insert the string.

Returns: EINA_TRUE on success, EINA_FALSE if slice could not be inserted.

This function inserts slice into buf at position pos.

Since: 1.19.0

◆ eina_binbuf_insert_char()

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

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

Parameters

[in,out]	buf	The string buffer.
[in]	c	The char to insert.
[in]	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_binbuf_remove()

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

Removes a slice of the given string buffer.

Parameters

[in,out]	buf	The string buffer.
[in]	start	The initial (inclusive) slice position to start removing, in bytes.
[in]	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.

◆ eina_binbuf_string_get()

EAPI const unsigned char* eina_binbuf_string_get ( const Eina_Binbuf * buf )

Retrieves a pointer to the contents of a string buffer.

Parameters

[in] buf The string buffer.

Returns: The string that is contained in buf.

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_binbuf_append() or similar functions will make the pointer invalid.

See also: eina_binbuf_string_steal()

Referenced by eet_alias_get(), and eet_read_direct().

◆ eina_binbuf_string_steal()

EAPI unsigned char* eina_binbuf_string_steal ( Eina_Binbuf * buf )

Steals the contents of a string buffer.

Parameters

[in,out] 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_binbuf_string_get()

◆ eina_binbuf_string_free()

EAPI void eina_binbuf_string_free ( Eina_Binbuf * buf )

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

Parameters

[in,out] buf The string buffer.

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

◆ eina_binbuf_length_get()

EAPI size_t eina_binbuf_length_get ( const Eina_Binbuf * buf )

Retrieves the length of the string buffer's content.

Parameters

[in] buf The string buffer.

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

This function returns the length of buf.

Referenced by eet_alias_get(), and eet_read_direct().

◆ eina_binbuf_slice_get()

EAPI Eina_Slice eina_binbuf_slice_get ( const Eina_Binbuf * buf )

Gets a read-only slice of the buffer contents.

Parameters

[in] buf The string buffer.

Returns: A read-only slice of the current contents. It may become invalid as soon as buf is changed.

Since: 1.19

◆ eina_binbuf_rw_slice_get()

EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get ( const Eina_Binbuf * buf )

Gets a read-write slice of the buffer contents.

Parameters

[in,out] buf The string buffer.

Returns: A read-write slice for the current contents. It may become invalid as soon as buf is changed, such as through calls like eina_binbuf_append() or eina_binbuf_remove().

See also: eina_binbuf_expand()

Since: 1.19

◆ eina_binbuf_release()

EAPI unsigned char* eina_binbuf_release ( Eina_Binbuf * buf )

Frees the buffer, returning its old contents.

Parameters

[in,out] buf The string buffer.

Returns: The content contained by buf. The caller must release the memory of the returned string by calling free().

Since: 1.19

Typedefs

Functions

Detailed Description

Function Documentation

◆ eina_binbuf_new()

◆ eina_binbuf_manage_new()

◆ eina_binbuf_manage_new_length()

◆ eina_binbuf_manage_read_only_new_length()

◆ eina_binbuf_free()

◆ eina_binbuf_reset()

◆ eina_binbuf_expand()

◆ eina_binbuf_use()

◆ eina_binbuf_append_length()

◆ eina_binbuf_append_slice()

◆ eina_binbuf_append_buffer()

◆ eina_binbuf_append_char()

◆ eina_binbuf_insert_length()

◆ eina_binbuf_insert_slice()

◆ eina_binbuf_insert_char()

◆ eina_binbuf_remove()

◆ eina_binbuf_string_get()

◆ eina_binbuf_string_steal()

◆ eina_binbuf_string_free()

◆ eina_binbuf_length_get()

◆ eina_binbuf_slice_get()

◆ eina_binbuf_rw_slice_get()

◆ eina_binbuf_release()