diff options
Diffstat (limited to 'src/lib/eina/eina_ustrbuf.h')
-rw-r--r-- | src/lib/eina/eina_ustrbuf.h | 504 |
1 files changed, 281 insertions, 223 deletions
diff --git a/src/lib/eina/eina_ustrbuf.h b/src/lib/eina/eina_ustrbuf.h index 888d8a2989..48fd62a234 100644 --- a/src/lib/eina/eina_ustrbuf.h +++ b/src/lib/eina/eina_ustrbuf.h @@ -7,39 +7,33 @@ #include "eina_unicode.h" /** - * @addtogroup Eina_Unicode_String_Buffer_Group Unicode String Buffer + * @defgroup Eina_Unicode_String_Buffer_Group Unicode String Buffer + * @ingroup Eina_Data_Types_Group * - * @brief These functions provide unicode string buffers management. + * @brief This group discusses the functions that provide unicode string buffers management. * - * The Unicode String Buffer data type is designed to be a mutable string, - * allowing to append, prepend or insert a string to a buffer. - */ - -/** - * @addtogroup Eina_Data_Types_Group Data Types - * - * @{ - */ - -/** - * @defgroup Eina_Unicode_String_Buffer_Group Unicode String Buffer + * @remarks The Unicode String Buffer data type is designed to be a mutable string, + * allowing to append, prepend, or insert a string into a buffer. * * @{ */ /** * @typedef Eina_UStrbuf - * Type for a string buffer. + * @brief The structure type for a string buffer. */ typedef struct _Eina_Strbuf Eina_UStrbuf; /** - * @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_ustrbuf_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_ustrbuf_free(). + * @return A newly allocated string buffer instance * * @see eina_ustrbuf_free() * @see eina_ustrbuf_append() @@ -48,72 +42,88 @@ typedef struct _Eina_Strbuf Eina_UStrbuf; EAPI Eina_UStrbuf *eina_ustrbuf_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_ustrbuf_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_ustrbuf_string_steal . The passed string must be malloced. + * + * @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(). + * + * @since 1.1.0 * - * @param str the string to manage - * @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 + * @return A newly allocated string buffer instance * * @see eina_ustrbuf_free() * @see eina_ustrbuf_append() * @see eina_ustrbuf_string_get() - * @since 1.1.0 */ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *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_ustrbuf_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_ustrbuf_string_steal . The passed string must be malloced. + * + * @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_ustrbuf_free(). + * + * @since 1.2.0 * - * @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_ustrbuf_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_ustrbuf_manage_new() - * @since 1.2.0 */ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; /** - * @brief Free a string buffer. + * @brief Frees a string buffer. + * + * @details This function frees the memory of @a buf. @a buf must have been + * created by eina_ustrbuf_new(). * - * @param buf The string buffer to free. + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to free * - * This function frees the memory of @p buf. @p buf must have been - * created by eina_ustrbuf_new(). */ EAPI void eina_ustrbuf_free(Eina_UStrbuf *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 + * + * @param[in] buf The string buffer to reset * - * This function reset @p buf: the buffer len is set to 0, and the - * string is set to '\\0'. No memory is free'd. */ EAPI void eina_ustrbuf_reset(Eina_UStrbuf *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_ustrbuf_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_ustrbuf_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_ustrbuf_append() * @see eina_ustrbuf_append_length() @@ -121,35 +131,40 @@ EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *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. + * + * @details This function appends the escaped 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 buf The string buffer to append to. - * @param str The string to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @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 appends the escaped 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_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2); /** - * @brief Append 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. - * - * This function appends at most @p maxlen characters of @p str to - * @p buf. It can't appends more than the length of @p str. It - * computes the length of @p str, so is slightly slower than - * eina_ustrbuf_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. + * @brief Appends a string to a buffer, reallocating as necessary, + * limited by the given length. + * + * @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 is slightly slower than + * eina_ustrbuf_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. + * + * @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_ustrbuf_append() * @see eina_ustrbuf_append_length() @@ -157,19 +172,21 @@ EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *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_ustrbuf_append() 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 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 * - * This function appends @p str to @p buf. @p str must be of size at - * most @p length. It is slightly faster than eina_ustrbuf_append() 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 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 + * @param[in] length The exact length to use + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * * @see eina_stringshare_length() * @see eina_ustrbuf_append() @@ -178,84 +195,98 @@ EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) EINA_ARG_NONNULL(1, 2); /** - * @brief Append a character to a string buffer, reallocating as - * necessary. + * @brief Appends a character to a string buffer, reallocating as + * necessary. * - * @param buf The string buffer to append to. - * @param c The char to append. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @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. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to append to + * @param[in] c The char 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_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1); /** - * @brief Insert a string to 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. - * - * 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_ustrbuf_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. + * @brief Inserts a string into a buffer, reallocating as necessary. + * + * @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_ustrbuf_insert_length(). If the length is known beforehand, + * consider using that variant. If @a buf can't insert 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] 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 + * */ EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *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 inserts the escaped 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. * - * @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. + * @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 the escaped 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_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2); /** - * @brief Insert a string to 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. - * - * This function inserts @p str ot @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_ustrbuf_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. + * @brief Inserts a string into a buffer, reallocating as necessary. Limited by maxlen. + * + * @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_ustrbuf_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 characters 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 + * */ EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *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_ustrbuf_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_ustrbuf_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_ustrbuf_insert() @@ -264,119 +295,142 @@ EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode *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_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_t pos) EINA_ARG_NONNULL(1); /** * @def eina_ustrbuf_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_ustrbuf_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_ustrbuf_insert() at position 0.If @p buf - * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend(buf, str) eina_ustrbuf_insert(buf, str, 0) /** * @def eina_ustrbuf_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_ustrbuf_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_ustrbuf_insert_escaped() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_escaped(buf, str) eina_ustrbuf_insert_escaped(buf, str, 0) /** * @def eina_ustrbuf_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_ustrbuf_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 Eina_Unicode *s 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 Eina_Unicode characters to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_ustrbuf_insert_n() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_n(buf, str, maxlen) eina_ustrbuf_insert_n(buf, str, maxlen, 0) /** * @def eina_ustrbuf_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_ustrbuf_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_ustrbuf_insert_length() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_length(buf, str, length) eina_ustrbuf_insert_length(buf, str, length, 0) /** * @def eina_ustrbuf_prepend_char(buf, c) - * @brief Prepend the given unicode character to the given buffer + * @brief Prepends the given unicode character to the given buffer. + * + * @details This macro calls eina_ustrbuf_insert_Eina_Unicode *() 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 c The Eina_Unicode character to prepend. - * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * @param buf The string buffer to prepend to + * @param c The Eina_Unicode character to prepend + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure * - * This macro is calling eina_ustrbuf_insert_Eina_Unicode *() at position 0. If - * @p buf can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. */ #define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0) /** - * @brief Remove a slice of the given string buffer. + * @brief Removes a slice of the given string buffer. * - * @param buf The string buffer to remove a slice. + * @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 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_ustrbuf_remove(Eina_UStrbuf *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 and is longer be valid if @a buf is + * modified. In other words, any eina_ustrbuf_append() or similar + * makes that pointer invalid. * - * 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_ustrbuf_append() or similar will - * make that pointer invalid. + * @since_tizen 2.3 + * + * @param buf The string buffer + * @return The current string in the string buffer * * @see eina_ustrbuf_string_steal() */ @@ -384,15 +438,17 @@ EAPI const Eina_Unicode * eina_ustrbuf_string_get(const Eina_UStrbuf *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_ustrbuf_string_get() */ @@ -400,23 +456,29 @@ EAPI Eina_Unicode * eina_ustrbuf_string_steal(Eina_UStrbuf *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. * - * @param buf The string buffer to free the string of. + * @details This function frees the string contained in @a buf without freeing + * @a buf. + * + * @since_tizen 2.3 + * + * @param[in] buf The string buffer to free the string of * - * This function frees the string contained in @p buf without freeing - * @p buf. */ EAPI void eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); /** - * @brief Retrieve the length of the string buffer content. + * @brief Gets the length of the string buffer's content. + * + * @details This function returns the length of @a buf. + * + * @since_tizen 2.3 * - * @param buf The string buffer. - * @return The current length of the string, in bytes. + * @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_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -425,8 +487,4 @@ eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_U * @} */ -/** - * @} - */ - #endif /* EINA_STRBUF_H */ |