Binary Buffer

Typedefs | Functions
Binary Buffer
Eina » Data Types

These functions provide string buffer management. More...

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

## Functions
EINA_API Eina_Binbuf * | eina_binbuf_new (void)
| Creates a new binary string buffer. More...
EINA_API 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. More...
EINA_API Eina_Binbuf * | eina_binbuf_manage_new_length (unsigned char *str, size_t length) EINA_DEPRECATED
| Creates a new string buffer using the passed string. More...
EINA_API Eina_Binbuf * | eina_binbuf_manage_read_only_new_length (const unsigned char *str, size_t length) EINA_DEPRECATED
| Creates a new string buffer using the passed string. More...
EINA_API void | eina_binbuf_free (Eina_Binbuf *buf)
| Frees a string buffer. More...
EINA_API void | eina_binbuf_reset (Eina_Binbuf *buf)
| Resets a string buffer. More...
EINA_API 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`. More...
EINA_API Eina_Bool | eina_binbuf_use (Eina_Binbuf *buf, size_t extra_bytes)
| Marks more bytes as used. More...
EINA_API 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. More...
EINA_API Eina_Bool | eina_binbuf_append_slice (Eina_Binbuf *buf, const Eina_Slice slice)
| Appends a slice to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_binbuf_append_buffer (Eina_Binbuf *buf, const Eina_Binbuf *data)
| Appends an Eina_Binbuf to a buffer, reallocating as necessary. More...
EINA_API Eina_Bool | eina_binbuf_append_char (Eina_Binbuf *buf, unsigned char c)
| Appends a character to a string buffer, reallocating as necessary. More...
EINA_API 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. More...
EINA_API 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. More...
EINA_API 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. More...
EINA_API Eina_Bool | eina_binbuf_remove (Eina_Binbuf *buf, size_t start, size_t end)
| Removes a slice of the given string buffer. More...
EINA_API const unsigned char * | eina_binbuf_string_get (const Eina_Binbuf *buf)
| Retrieves a pointer to the contents of a string buffer. More...
EINA_API unsigned char * | eina_binbuf_string_steal (Eina_Binbuf *buf)
| Steals the contents of a string buffer. More...
EINA_API void | eina_binbuf_string_free (Eina_Binbuf *buf)
| Frees the contents of a string buffer but not the buffer. More...
EINA_API size_t | eina_binbuf_length_get (const Eina_Binbuf *buf)
| Retrieves the length of the string buffer's content. More...
EINA_API Eina_Slice | eina_binbuf_slice_get (const Eina_Binbuf *buf)
| Gets a read-only slice of the buffer contents. More...
EINA_API Eina_Rw_Slice | eina_binbuf_rw_slice_get (const Eina_Binbuf *buf)
| Gets a read-write slice of the buffer contents. More...
EINA_API unsigned char * | eina_binbuf_release (Eina_Binbuf *buf)
| 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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()

EINA_API 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