aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eina/eina_strbuf.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/eina/eina_strbuf.h')
-rw-r--r--src/lib/eina/eina_strbuf.h746
1 files changed, 382 insertions, 364 deletions
diff --git a/src/lib/eina/eina_strbuf.h b/src/lib/eina/eina_strbuf.h
index 1a628b9fef..7ce38705b4 100644
--- a/src/lib/eina/eina_strbuf.h
+++ b/src/lib/eina/eina_strbuf.h
@@ -6,71 +6,34 @@
#include "eina_types.h"
-
-/**
- * @page tutorial_strbuf Eina_Strbuf example
- * @dontinclude eina_strbuf_01.c
- *
- * First thing always is including Eina:
- * @skipline #include
- * @until #include
- *
- * Next we initialize eina and create a string buffer to play with:
- * @until strbuf_new
- *
- * Here you can see two different ways of creating a buffer with the same
- * contents. We could create them in simpler ways, but this gives us an
- * opportunity to demonstrate several functions in action:
- * @until strbuf_reset
- * @until strbuf_reset
- *
- * Next we use the printf family of functions to create a formated string,
- * add, remove and replace some content:
- * @until strbuf_string_get
- * @until strbuf_string_get
- * @until strbuf_string_get
- *
- * Once done we free our string buffer, shut down Eina and end the application:
- * @until }
- *
- * @example eina_strbuf_01.c
- */
/**
- * @addtogroup Eina_String_Buffer_Group String Buffer
- *
- * @brief These functions provide string buffers management.
- *
- * The String Buffer data type is designed to be a mutable string,
- * allowing to append, prepend or insert a string to a buffer.
+ * @defgroup Eina_String_Buffer_Group String Buffer
+ * @ingroup Eina_Data_Types_Group
*
- * For more information see @ref tutorial_strbuf "this example".
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
+ * @brief This group discusses the functions that provide string buffers management.
*
- * @{
- */
-
-/**
- * @defgroup Eina_String_Buffer_Group String Buffer
+ * @remarks The String Buffer data type is designed to be a mutable string,
+ * allowing to append, prepend, or insert a string into a buffer.
*
* @{
*/
/**
* @typedef Eina_Strbuf
- * Type for a string buffer.
+ * @brief The structure type for a string buffer.
*/
typedef struct _Eina_Strbuf Eina_Strbuf;
/**
- * @brief Create a new string buffer.
+ * @brief Creates a new string buffer.
+ *
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_strbuf_free().
*
- * @return Newly allocated string buffer instance.
+ * @since_tizen 2.3
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
+ * @return A newly allocated string buffer instance
*
* @see eina_strbuf_free()
* @see eina_strbuf_append()
@@ -79,89 +42,86 @@ typedef struct _Eina_Strbuf Eina_Strbuf;
EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief 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
- * @ref eina_strbuf_string_steal . The passed string must be malloced.
+ * @brief 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
+ * @ref eina_strbuf_string_steal. The passed string must be malloced.
*
- * @param str the string to manage
- * @return Newly allocated string buffer instance.
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_strbuf_free().
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
+ * @since 1.1.0
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] str The string to manage
+ * @return A newly allocated string buffer instance
*
* @see eina_strbuf_free()
* @see eina_strbuf_append()
* @see eina_strbuf_string_get()
- * @since 1.1.0
*/
EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief 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
- * @ref eina_strbuf_string_steal . The passed string must be malloced.
+ * @brief 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
+ * @ref eina_strbuf_string_steal. The passed string must be malloced.
*
- * @param str the string to manage
- * @param length the length of the string.
- * @return Newly allocated string buffer instance.
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_strbuf_free().
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
- *
- * @see eina_strbuf_manage_new()
* @since 1.2.0
- */
-EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief 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
- * @ref eina_strbuf_string_steal . The passed string must be malloced.
*
- * @param str the string to manage
- * @param length the length of the string.
- * @return Newly allocated string buffer instance.
+ * @since_tizen 2.3
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
+ * @param[in] str The string to manage
+ * @param[in] length The length of the string
+ * @return A newly allocated string buffer instance
*
* @see eina_strbuf_manage_new()
- * @since 1.9.0
*/
-EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free a string buffer.
+ * @brief Frees a string buffer.
*
- * @param buf The string buffer to free.
+ * @details This function frees the memory of @a buf. @a buf must have been
+ * created by eina_strbuf_new().
*
- * This function frees the memory of @p buf. @p buf must have been
- * created by eina_strbuf_new().
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to free
*/
EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Reset a string buffer.
+ * @brief Resets a string buffer.
+ *
+ * @details This function resets @a buf: the buffer length is set to 0, and the
+ * string is set to '\\0'. No memory is freed.
*
- * @param buf The string buffer to reset.
+ * @since_tizen 2.3
*
- * This function reset @p buf: the buffer len is set to 0, and the
- * string is set to '\\0'. No memory is free'd.
+ * @param[in] buf The string buffer to reset
*/
EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Append a string to a buffer, reallocating as necessary.
+ * @brief Appends a string to a buffer, reallocating as necessary.
+ *
+ * @details This function appends @a str to @a buf. It computes the length of
+ * @a str, so is slightly slower than eina_strbuf_append_length(). If
+ * the length is known beforehand, consider using that variant. If
+ * @a buf can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
*
- * This function appends @p str to @p buf. It computes the length of
- * @p str, so is slightly slower than eina_strbuf_append_length(). If
- * the length is known beforehand, consider using that variant. If
- * @p buf can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append()
* @see eina_strbuf_append_length()
@@ -169,35 +129,40 @@ EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append an escaped string to a buffer, reallocating as necessary.
+ * @brief Appends an escaped string to a buffer, reallocating as necessary.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function escapes and then appends the string @a str to @a buf. If @a str
+ * cannot be appended, @c EINA_FALSE is returned, otherwise, @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function escapes and then appends the string @p str to @p buf. If @p str
- * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
- * returned.
*/
EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append a string to a buffer, reallocating as necessary,
- * limited by the given length.
+ * @brief Appends a string to a buffer, reallocating as necessary,
+ * limited by the given length.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @param maxlen The maximum number of characters to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function appends at most @a maxlen characters of @a str to
+ * @a buf. It can't append more than the length of @a str. It
+ * computes the length of @a str, so it is slightly slower than
+ * eina_strbuf_append_length(). If the length is known beforehand,
+ * consider using that variant (@a maxlen should then be checked so
+ * that it is greater than the size of @a str). If @a str cannot be
+ * appended, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * This function appends at most @p maxlen characters of @p str to
- * @p buf. It can't append more than the length of @p str. It
- * computes the length of @p str, so it is slightly slower than
- * eina_strbuf_append_length(). If the length is known beforehand,
- * consider using that variant (@p maxlen should then be checked so
- * that it is greater than the size of @p str). If @p str can not be
- * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
- * returned.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @param[in] maxlen The maximum number of characters to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append()
* @see eina_strbuf_append_length()
@@ -205,19 +170,22 @@ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EIN
EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append a string of exact length to a buffer, reallocating as necessary.
+ * @brief Appends a string of exact length to a buffer, reallocating as necessary.
+ *
+ * @details This function appends @a str to @a buf. @a str must be at most of size
+ * @a length. It is slightly faster than eina_strbuf_append() as
+ * it does not compute the size of @a str. It is useful when dealing
+ * with strings of known size, such as eina_stringshare. If @a buf
+ * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @param length The exact length to use.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @param[in] length The exact length to use
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function appends @p str to @p buf. @p str must be of size at
- * most @p length. It is slightly faster than eina_strbuf_append() as
- * it does not compute the size of @p str. It is useful when dealing
- * with strings of known size, such as eina_stringshare. If @p buf
- * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*
* @see eina_stringshare_length()
* @see eina_strbuf_append()
@@ -226,130 +194,128 @@ EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t ma
EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size_t length) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append an Eina_Strbuf to a buffer, reallocating as necessary.
- *
- * @param buf The string buffer to append to.
- * @param data The string buffer to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Appends a character to a string buffer, reallocating as
+ * necessary.
*
- * This function appends @p data to @p buf. @p data must be allocated and
- * different from @NULL. It is slightly faster than eina_strbuf_append() as
- * it does not compute the size of @p str. If @p buf can't append it,
- * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
+ * @details This function inserts @a c to @a buf. If it cannot insert it, @c EINA_FALSE
+ * is returned, otherwise @c EINA_TRUE is returned.
*
- * @see eina_strbuf_append()
- * @see eina_strbuf_append_n()
- * @see eina_strbuf_append_length()
- * @since 1.9.0
- */
-EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *data) EINA_ARG_NONNULL(1, 2);
-
-/**
- * @brief Append a character to a string buffer, reallocating as
- * necessary.
+ * @since_tizen 2.3
*
- * @param buf The string buffer to append to.
- * @param c The char to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param[in] buf The string buffer to append to
+ * @param[in] c The character to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE
- * is returned, otherwise #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1);
/**
- * @brief Append a string to a buffer, reallocating as necessary.
+ * @brief Appends a string to a buffer, reallocating as necessary.
+ *
+ * @details This function appends the string defined by the format @a fmt to @a buf. @a
+ * fmt must be of a valid format from the printf family of functions. If it can't
+ * insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is returned.
*
- * @param buf The string buffer to append to.
- * @param fmt The string to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
*
- * This function appends the string defined by the format @p fmt to @p buf. @p
- * fmt must be of a valid format for printf family of functions. If it can't
- * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
+ * @param[in] buf The string buffer to append to
+ * @param[in] fmt The string to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append()
*/
EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3);
/**
- * @brief Append a string to a buffer, reallocating as necessary.
+ * @brief Appends a string to a buffer, reallocating as necessary.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to append to.
- * @param fmt The string to append.
- * @param args The variable arguments.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param[in] buf The string buffer to append to
+ * @param[in] fmt The string to append
+ * @param[in] args The variable arguments
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append_printf()
*/
EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Insert a string to a buffer, reallocating as necessary.
+ * @brief Inserts a string into a buffer, reallocating as necessary.
*
- * @param buf The string buffer to insert.
- * @param str The string to insert.
- * @param pos The position to insert the string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function inserts @a str into @a buf at position @a pos. It
+ * computes the length of @a str, so is slightly slower than
+ * eina_strbuf_insert_length(). If the length is known beforehand,
+ * consider using that variant. If @a buf can't insert it, @c EINA_FALSE
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to insert into
+ * @param[in] str The string to insert
+ * @param[in] pos The position at which to insert the string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p str to @p buf at position @p pos. It
- * computes the length of @p str, so is slightly slower than
- * eina_strbuf_insert_length(). If the length is known beforehand,
- * consider using that variant. If @p buf can't insert it, #EINA_FALSE
- * is returned, otherwise #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Insert an escaped string to a buffer, reallocating as
- * necessary.
+ * @brief Inserts an escaped string into a buffer, reallocating as
+ * necessary.
+ *
+ * @details This function escapes and inserts the string @a str into @a buf at
+ * position @a pos. If @a buf can't insert @a str, @c EINA_FALSE is
+ * returned, otherwise @c EINA_TRUE is returned.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to insert to.
- * @param str The string to insert.
- * @param pos The position to insert the string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param[in] buf The string buffer to insert into
+ * @param[in] str The string to insert
+ * @param[in] pos The position at which to insert the string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function escapes and inserts the string @p str to @p buf at
- * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is
- * returned, otherwise #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen.
+ * @brief Inserts a string into a buffer, reallocating as necessary. Limited by maxlen.
*
- * @param buf The string buffer to insert to.
- * @param str The string to insert.
- * @param maxlen The maximum number of chars to insert.
- * @param pos The position to insert the string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function inserts @a str into @a buf at position @a pos, with at
+ * most @a maxlen bytes. The number of inserted characters cannot be
+ * greater than the length of @a str. It computes the length of
+ * @a str, so is slightly slower than eina_strbuf_insert_length(). If the
+ * length is known beforehand, consider using that variant (@a maxlen
+ * should then be checked so that it is greater than the size of
+ * @a str). If @a str cannot be inserted, @c EINA_FALSE is returned,
+ * otherwise @c EINA_TRUE is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to insert into
+ * @param[in] str The string to insert
+ * @param[in] maxlen The maximum number of chars to insert
+ * @param[in] pos The position at which to insert the string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p str to @p buf at position @p pos, with at
- * most @p maxlen bytes. The number of inserted characters can not be
- * greater than the length of @p str. It computes the length of
- * @p str, so is slightly slower than eina_strbuf_insert_length(). If the
- * length is known beforehand, consider using that variant (@p maxlen
- * should then be checked so that it is greater than the size of
- * @p str). If @p str can not be inserted, #EINA_FALSE is returned,
- * otherwise, #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Insert a string of exact length to a buffer, reallocating as necessary.
+ * @brief Inserts a string of exact length into a buffer, reallocating as necessary.
+ *
+ * @details This function inserts @a str into @a buf. @a str must be at most of size
+ * @a length. It is slightly faster than eina_strbuf_insert() as
+ * it does not compute the size of @a str. It is useful when dealing
+ * with strings of known size, such as eina_strngshare. If @a buf
+ * can't insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to insert to.
- * @param str The string to insert.
- * @param length The exact length to use.
- * @param pos The position to insert the string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
*
- * This function inserts @p str to @p buf. @p str must be of size at
- * most @p length. It is slightly faster than eina_strbuf_insert() as
- * it does not compute the size of @p str. It is useful when dealing
- * with strings of known size, such as eina_strngshare. If @p buf
- * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
+ * @param[in] buf The string buffer to insert into
+ * @param[in] str The string to insert
+ * @param[in] length The exact length to use
+ * @param[in] pos The position at which to insert the string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_stringshare_length()
* @see eina_strbuf_insert()
@@ -358,43 +324,51 @@ EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t ma
EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Insert a character to a string buffer, reallocating as
- * necessary.
+ * @brief Inserts a character into a string buffer, reallocating as
+ * necessary.
*
- * @param buf The string buffer to insert to.
- * @param c The char to insert.
- * @param pos The position to insert the char.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function inserts @a c into @a buf at position @a pos. If @a buf
+ * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to insert into
+ * @param[in] c The character to insert
+ * @param[in] pos The position at which to insert the char
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p c to @p buf at position @p pos. If @p buf
- * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1);
/**
- * @brief Insert a string to a buffer, reallocating as necessary.
+ * @brief Inserts a string into a buffer, reallocating as necessary.
+ *
+ * @details This function inserts a string as described by the format @a fmt into @a buf at
+ * the position @a pos. @a fmt must be of a valid format from the printf family of
+ * functions. If it can't insert it, @c EINA_FALSE is returned,
+ * otherwise @c EINA_TRUE is returned.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to insert.
- * @param fmt The string to insert.
- * @param pos The position to insert the string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param[in] buf The string buffer to insert into
+ * @param[in] fmt The string to insert
+ * @param[in] pos The position at which to insert the string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function insert a string as described by the format @p fmt to @p buf at
- * the position @p pos. @p fmt must be of a valid format for printf family of
- * functions. If it can't insert it, #EINA_FALSE is returned,
- * otherwise #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4);
/**
- * @brief Insert a string to a buffer, reallocating as necessary.
+ * @brief Inserts a string into a buffer, reallocating as necessary.
*
- * @param buf The string buffer to insert.
- * @param fmt The string to insert.
- * @param pos The position to insert the string.
- * @param args The variable arguments.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to insert into
+ * @param[in] fmt The string to insert
+ * @param[in] pos The position at which to insert the string
+ * @param[in] args The variable arguments
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_insert_printf
*/
@@ -402,242 +376,294 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend(buf, str)
- * @brief Prepend the given string to the given buffer
+ * @brief Prepends the given string to the given buffer.
+ *
+ * @details This macro calls eina_strbuf_insert() at position 0. If @a buf
+ * can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to prepend to.
- * @param str The string to prepend.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param buf The string buffer to prepend to
+ * @param str The string to prepend
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This macro is calling eina_strbuf_insert() at position 0. If @p buf
- * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
#define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf, str, 0)
/**
* @def eina_strbuf_prepend_escaped(buf, str)
- * @brief Prepend the given escaped string to the given buffer
+ * @brief Prepends the given escaped string to the given buffer.
*
- * @param buf The string buffer to prepend to.
- * @param str The string to prepend.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This macro calls eina_strbuf_insert_escaped() at position 0. If
+ * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param buf The string buffer to prepend to
+ * @param str The string to prepend
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This macro is calling eina_strbuf_insert_escaped() at position 0. If
- * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
#define eina_strbuf_prepend_escaped(buf, str) eina_strbuf_insert_escaped(buf, str, 0)
/**
* @def eina_strbuf_prepend_n(buf, str)
- * @brief Prepend the given escaped string to the given buffer
+ * @brief Prepends the given escaped string to the given buffer.
+ *
+ * @details This macro calls eina_strbuf_insert_n() at position 0. If
+ * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to prepend to.
- * @param str The string to prepend.
- * @param maxlen The maximum number of chars to prepend.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param buf The string buffer to prepend to
+ * @param str The string to prepend
+ * @param maxlen The maximum number of chars to prepend
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This macro is calling eina_strbuf_insert_n() at position 0. If
- * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
#define eina_strbuf_prepend_n(buf, str, maxlen) eina_strbuf_insert_n(buf, str, maxlen, 0)
/**
* @def eina_strbuf_prepend_length(buf, str)
- * @brief Prepend the given escaped string to the given buffer
+ * @brief Prepends the given escaped string to the given buffer.
*
- * @param buf The string buffer to prepend to.
- * @param str The string to prepend.
- * @param length The exact length to use.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This macro calls eina_strbuf_insert_length() at position 0. If
+ * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param buf The string buffer to prepend to
+ * @param str The string to prepend
+ * @param length The exact length to use
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This macro is calling eina_strbuf_insert_length() at position 0. If
- * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
#define eina_strbuf_prepend_length(buf, str, length) eina_strbuf_insert_length(buf, str, length, 0)
/**
* @def eina_strbuf_prepend_char(buf, str)
- * @brief Prepend the given character to the given buffer
+ * @brief Prepends the given character to the given buffer.
+ *
+ * @details This macro calls eina_strbuf_insert_char() at position 0. If
+ * @a buf can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE
+ * is returned.
*
- * @param buf The string buffer to prepend to.
- * @param c The character to prepend.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param buf The string buffer to prepend to
+ * @param c The character to prepend
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure.
*
- * This macro is calling eina_strbuf_insert_char() at position 0. If
- * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE
- * is returned.
*/
#define eina_strbuf_prepend_char(buf, c) eina_strbuf_insert_char(buf, c, 0)
/**
* @def eina_strbuf_prepend_printf(buf, fmt, ...)
- * @brief Prepend the given string to the given buffer
+ * @brief Prepends the given string to the given buffer.
+ *
+ * @details This macro calls eina_strbuf_insert_printf() at position 0. If @a buf
+ * can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to prepend to.
- * @param fmt The string to prepend.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param buf The string buffer to prepend to
+ * @param fmt The string to prepend
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This macro is calling eina_strbuf_insert_printf() at position 0. If @p buf
- * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
#define eina_strbuf_prepend_printf(buf, fmt, ...) eina_strbuf_insert_printf(buf, fmt, 0, ## __VA_ARGS__)
/**
* @def eina_strbuf_prepend_vprintf(buf, fmt, args)
- * @brief Prepend the given string to the given buffer
+ * @brief Prepends the given string to the given buffer.
+ *
+ * @details This macro calls eina_strbuf_insert_vprintf() at position 0. If @a buf
+ * can't prepend it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to prepend to.
- * @param fmt The string to prepend.
- * @param args The variable arguments.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param buf The string buffer to prepend to
+ * @param fmt The string to prepend
+ * @param args The variable arguments
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This macro is calling eina_strbuf_insert_vprintf() at position 0.If @p buf
- * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
#define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args)
/**
- * @brief Remove a slice of the given string buffer.
+ * @brief Removes a slice of the given string buffer.
+ *
+ * @details This function removes a slice of @a buf, starting from @a start
+ * (inclusive) and ending at @a end (non-inclusive). Both the values are
+ * in bytes. It returns @c EINA_FALSE on failure, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to remove a slice.
+ * @param buf The string buffer to remove a slice of
* @param start The initial (inclusive) slice position to start
- * removing, in bytes.
+ * removing from, in bytes
* @param end The final (non-inclusive) slice position to finish
- * removing, in bytes.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * removing at, in bytes
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function removes a slice of @p buf, starting at @p start
- * (inclusive) and ending at @p end (non-inclusive). Both values are
- * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise.
*/
EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve a pointer to the contents of a string buffer
+ * @brief Gets a pointer to the contents of a string buffer.
*
- * @param buf The string buffer.
- * @return The current string in the string buffer.
+ * @details This function returns the string contained in @a buf. The returned
+ * value must not be modified as it is longer valid if @a buf is
+ * modified. In other words, any eina_strbuf_append() or similar
+ * makes that pointer invalid. The pointer returned by this function <b>must
+ * not</b> be freed.
*
- * This function returns the string contained in @p buf. The returned
- * value must not be modified and will no longer be valid if @p buf is
- * modified. In other words, any eina_strbuf_append() or similar will
- * make that pointer invalid. The pointer returned by this function <b>must
- * not</b> be freed.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer
+ * @return The current string in the string buffer
*
* @see eina_strbuf_string_steal()
*/
EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Steal the contents of a string buffer.
+ * @brief Steals the contents of a string buffer.
+ *
+ * @details This function returns the string contained in @a buf. @a 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().
*
- * @param buf The string buffer to steal.
- * @return The current string in the string buffer.
+ * @since_tizen 2.3
*
- * This function returns the string contained in @p buf. @p 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().
+ * @param[in] buf The string buffer to steal from
+ * @return The current string in the string buffer
*
* @see eina_strbuf_string_get()
*/
EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * @brief Free the contents of a string buffer but not the buffer.
+ * @brief Frees the contents of a string buffer but not the buffer.
+ *
+ * @details This function frees the string contained in @a buf without freeing
+ * @a buf.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to free the string of.
+ * @param[in] buf The string buffer to free the string from
*
- * This function frees the string contained in @p buf without freeing
- * @p buf.
*/
EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve the length of the string buffer content.
+ * @brief Gets the length of the string buffer's content.
*
- * @param buf The string buffer.
- * @return The current length of the string, in bytes.
+ * @details This function returns the length of @a buf.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer
+ * @return The current length of the string, in bytes
*
- * This function returns the length of @p buf.
*/
EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Replace the n-th string with an other string.
+ * @brief Replaces the nth string with another string.
+ *
+ * @details This function replaces the nth occurrence of @a str in @a buf with
+ * @a with. It returns @c EINA_FALSE on failure, otherwise @c EINA_TRUE.
*
- * @param buf The string buffer to work with.
- * @param str The string to replace.
- * @param with The replaceing string.
- * @param n The number of the fitting string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to work with
+ * @param[in] str The string to replace
+ * @param[in] with The string to replace with
+ * @param[in] n The number of the fitting string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function replaces the n-th occurrence of @p str in @p buf with
- * @p with. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise.
*/
EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3);
/**
* @def eina_strbuf_replace_first(buf, str, with)
- * @brief Prepend the given character to the given buffer
+ * @brief Prepends the given character to the given buffer.
+ *
+ * @details This macro calls eina_strbuf_replace() with the nth occurrence
+ * equal to @c 1. If @a buf can't replace it, @c EINA_FALSE is returned,
+ * otherwise @c EINA_TRUE is returned.
*
- * @param buf The string buffer to work with.
- * @param str The string to replace.
- * @param with The replaceing string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param buf The string buffer to work with
+ * @param str The string to replace
+ * @param with The string to replace with
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This macro is calling eina_strbuf_replace() with the n-th occurrence
- * equal to @c 1. If @p buf can't replace it, #EINA_FALSE is returned,
- * otherwise #EINA_TRUE is returned.
*/
#define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf, str, with, 1)
/**
- * @brief Replace all strings with an other string.
-
- * @param buf the string buffer to work with.
- * @param str The string to replace.
- * @param with The replaceing string.
- * @return How often the string was replaced.
+ * @brief Replaces all strings with another string.
+ *
+ * @details This function replaces all the occurrences of @a str in @a buf with
+ * the string @a with. This function returns the number of times @a str
+ * has been replaced. On failure, it returns @c 0.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to work with
+ * @param[in] str The string to replace
+ * @param[in] with The string to replace with
+ * @return The frequency with which the string is replaced
*
- * This function replaces all the occurrences of @p str in @p buf with
- * the string @p with. This function returns the number of times @p str
- * has been replaced. On failure, it returns @c 0.
*/
EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Trim the string buffer
-
- * @param buf the string buffer to work with.
+ * @brief Trims the string buffer.
+ *
+ * @details This function skips whitespaces at the beginning and the end of the buffer.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to work with
*
- * This function skips whitespaces in the beginning and the end of the buffer.
*/
EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Left trim the string buffer
-
- * @param buf the string buffer to work with.
+ * @brief Left trims the string buffer.
+ *
+ * @details This function skips whitespaces at the beginning of the buffer.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to work with
*
- * This function skips whitespaces in the beginning of the buffer.
*/
EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Right trim the string buffer
-
- * @param buf the string buffer to work with.
+ * @brief Right trims the string buffer.
+ *
+ * @details This function skips whitespaces at the end of the buffer.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to work with
*
- * This function skips whitespaces in the end of the buffer.
*/
EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
@@ -645,12 +671,4 @@ EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif /* EINA_STRBUF_H */