diff options
Diffstat (limited to 'src/lib/eina/eina_strbuf.h')
| -rw-r--r-- | src/lib/eina/eina_strbuf.h | 746 |
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 */ |