Binary Buffer

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files
- Examples

Typedefs | Functions
Binary Buffer
Eina » Data Types

These functions provide string buffers management. More...

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

## Functions
EAPI Eina_Binbuf * | eina_binbuf_new (void) EINA_MALLOC EINA_WARN_UNUSED_RESULT
| Create a new string buffer. More...
EAPI Eina_Binbuf * | eina_binbuf_manage_new_length (unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED
| Create a new string buffer using the passed string. More...
EAPI Eina_Binbuf * | eina_binbuf_manage_new (const unsigned char *str, size_t length, Eina_Bool ro) EINA_MALLOC EINA_WARN_UNUSED_RESULT
| Create 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
| Create a new string buffer using the passed string. More...
EAPI void | eina_binbuf_free (Eina_Binbuf *buf) EINA_ARG_NONNULL(1)
| Free a string buffer. More...
EAPI void | eina_binbuf_reset (Eina_Binbuf *buf) EINA_ARG_NONNULL(1)
| Reset a string buffer. More...
EAPI Eina_Bool | eina_binbuf_append_length (Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1
| Append a string of exact length to a buffer, reallocating as necessary. More...
EAPI Eina_Bool EAPI Eina_Bool | eina_binbuf_append_buffer (Eina_Binbuf *buf, const Eina_Binbuf *data) EINA_ARG_NONNULL(1
| Append an Eina_Binbuf to a buffer, reallocating as necessary. More...
EAPI Eina_Bool EAPI Eina_Bool EAPI Eina_Bool | eina_binbuf_append_char (Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1)
| Append 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
| Insert a string of exact length to a buffer, reallocating as necessary. More...
EAPI Eina_Bool EAPI Eina_Bool | eina_binbuf_insert_char (Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1)
| Insert a character to 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)
| Remove 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
| Retrieve 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)
| Steal the contents of a string buffer. More...
EAPI void | eina_binbuf_string_free (Eina_Binbuf *buf) EINA_ARG_NONNULL(1)
| Free 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
| Retrieve the length of the string buffer content. More...

## Detailed Description

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.

## Function Documentation

EAPI Eina_Binbuf* eina_binbuf_new | ( | void |  | ) |

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

Referenced by emile_binbuf_cipher(), and emile_binbuf_decipher().

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

Create 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
  1.2.0

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

Create 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
  1.14.0

Referenced by edje_edit_sound_samplebuffer_get(), eet_alias(), eet_write_cipher(), emile_compress(), and emile_decompress().

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

Create 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 will not be touched.

Parameters

  str | the string to start from
  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(). It will not touch the internal buffer. Any changing operation will create a fresh new memory, copy old data there and starting modifying that one.

See also
  eina_binbuf_manage_new()

Since
  1.9.0

EAPI void eina_binbuf_free | ( | Eina_Binbuf * | buf | ) |

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

Referenced by eet_alias(), eet_alias_get(), eet_read_cipher(), eet_read_direct(), eet_write_cipher(), emile_binbuf_cipher(), emile_binbuf_decipher(), and emile_decompress().

EAPI void eina_binbuf_reset | ( | Eina_Binbuf * | buf | ) |

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

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

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

Referenced by emile_binbuf_cipher(), and emile_binbuf_decipher().

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

Append 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
  1.9.0

Referenced by emile_binbuf_cipher().

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

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

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

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

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

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

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

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

Referenced by emile_binbuf_cipher(), and emile_binbuf_decipher().

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

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

Referenced by eet_alias_get(), eet_read_direct(), emile_binbuf_cipher(), emile_binbuf_decipher(), emile_compress(), and emile_expand().

EAPI unsigned char* eina_binbuf_string_steal | ( | Eina_Binbuf * | buf | ) |

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

Referenced by eet_read_cipher().

EAPI void eina_binbuf_string_free | ( | Eina_Binbuf * | buf | ) |

Free 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`.

EAPI size_t eina_binbuf_length_get | ( | const Eina_Binbuf * | buf | ) |

Retrieve 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`.

Referenced by eet_alias_get(), eet_read_cipher(), eet_read_direct(), eet_write_cipher(), emile_binbuf_cipher(), emile_binbuf_decipher(), emile_compress(), and emile_expand().