svn_stringbuf_t *
svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...)
  __attribute__((format(printf, 2, 3)));

/** Create a new stringbuf by printf-style formatting using @c fmt and @a ap.
 * This is the same as svn_stringbuf_createf() except for the different
 * way of passing the variable arguments.
 */
svn_stringbuf_t *
svn_stringbuf_createv(apr_pool_t *pool, const char *fmt, va_list ap)
  __attribute__((format(printf, 2, 0)));

/** Make sure that @a str has at least @a minimum_size
 * bytes of space available in the memory block.
 *
 * The allocated string buffer will be at least one byte larger than
 * @a minimum_size to account for a final '\\0'.
 *
 * @note: Before Subversion 1.8 this function did not ensure space for
 * one byte more than @a minimum_size.  If compatibility with pre-1.8
 * behaviour is required callers must assume space for only
 * @a minimum_size-1 data bytes plus a final '\\0'.
 */
void
svn_stringbuf_ensure(svn_stringbuf_t *str, apr_size_t minimum_size);

/** Set @a str to a copy of the null-terminated C string @a value. */
void
svn_stringbuf_set(svn_stringbuf_t *str, const char *value);

/** Set @a str to empty (zero length). */
void
svn_stringbuf_setempty(svn_stringbuf_t *str);

/** Return @c TRUE if @a str is empty (has length zero). */
svn_boolean_t
svn_stringbuf_isempty(const svn_stringbuf_t *str);

/** Chop @a nbytes bytes off end of @a str, but not more than @a str->len. */
void
svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes);

/**
 * Chop @a nbytes bytes off the start of @a str, but not more than @a str->len.
 *
 * @since New in 1.10.
 */
void
svn_stringbuf_leftchop(svn_stringbuf_t *str, apr_size_t nbytes);

/** Fill @a str with character @a c. */
void
svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c);

/** Append the single character @a byte onto @a targetstr.
 *
 * This is an optimized version of svn_stringbuf_appendbytes()
 * that is much faster to call and execute. Gains vary with the ABI.
 * The advantages extend beyond the actual call because the reduced
 * register pressure allows for more optimization within the caller.
 *
 * Reallocs if necessary. @a targetstr is affected, nothing else is.
 * @since New in 1.7.
 */
void
svn_stringbuf_appendbyte(svn_stringbuf_t *targetstr,
                         char byte);

/** Append the array of bytes @a bytes of length @a count onto @a targetstr.
 *
 * Reallocs if necessary. @a targetstr is affected, nothing else is.
 *
 * @since 1.9 @a bytes can be NULL if @a count is zero.
 */
void
svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr,
                          const char *bytes,
                          apr_size_t count);

/** Append @a byte @a count times onto @a targetstr.
 *
 * Reallocs if necessary. @a targetstr is affected, nothing else is.
 * @since New in 1.9.
 */
void
svn_stringbuf_appendfill(svn_stringbuf_t *targetstr,
                         char byte,
                         apr_size_t count);

/** Append the stringbuf @c appendstr onto @a targetstr.
 *
 * Reallocs if necessary. @a targetstr is affected, nothing else is.
 */
void
svn_stringbuf_appendstr(svn_stringbuf_t *targetstr,
                        const svn_stringbuf_t *appendstr);

/** Append the C string @a cstr onto @a targetstr.
 *
 * Reallocs if necessary. @a targetstr is affected, nothing else is.
 */
void
svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr,
                         const char *cstr);

/** Insert into @a str at position @a pos an array of bytes @a bytes
 * which is @a count bytes long.
 *
 * The resulting string will be @c count+str->len bytes long.  If
 * @a pos is larger than or equal to @c str->len, simply append @a bytes.
 *
 * Reallocs if necessary. @a str is affected, nothing else is.
 *
 * @note The inserted string may be a sub-range of @a str.
 *
 * @since New in 1.8.
 *
 * @since Since 1.9, @a bytes can be NULL if @a count is zero.
 */
void
svn_stringbuf_insert(svn_stringbuf_t *str,
                     apr_size_t pos,
                     const char *bytes,
                     apr_size_t count);

/** Remove @a count bytes from @a str, starting at position @a pos.
 *
 * If that range exceeds the current string data, truncate @a str at
 * @a pos.  If @a pos is larger than or equal to @c str->len, this will
 * be a no-op.  Otherwise, the resulting string will be @c str->len-count
 * bytes long.
 *
 * @since New in 1.8.
 */
void
svn_stringbuf_remove(svn_stringbuf_t *str,
                     apr_size_t pos,
                     apr_size_t count);

/** Replace in @a str the substring which starts at @a pos and is @a
 * old_count bytes long with a new substring @a bytes which is @a
 * new_count bytes long.
 *
 * This is faster but functionally equivalent to the following sequence:
 * @code
     svn_stringbuf_remove(str, pos, old_count);
     svn_stringbuf_insert(str, pos, bytes, new_count);
 * @endcode
 *
 * @since New in 1.8.
 *
 * @since Since 1.9, @a bytes can be NULL if @a new_count is zero.
 */
void
svn_stringbuf_replace(svn_stringbuf_t *str,
                      apr_size_t pos,
                      apr_size_t old_count,
                      const char *bytes,
                      apr_size_t new_count);

/** Replace all occurrences of @a to_find in @a str with @a replacement.
 * Return the number of replacements made.
 *
 * @since New in 1.10.
 */
apr_size_t
svn_stringbuf_replace_all(svn_stringbuf_t *str,
                          const char *to_find,
                          const char *replacement);

/** Return a duplicate of @a original_string. */
svn_stringbuf_t *
svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool);

/** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
svn_boolean_t
svn_stringbuf_compare(const svn_stringbuf_t *str1,
                      const svn_stringbuf_t *str2);

/** Return offset of first non-whitespace character in @a str, or return
 * @a str->len if none.
 */
apr_size_t
svn_stringbuf_first_non_whitespace(const svn_stringbuf_t *str);

/** Strip whitespace from both sides of @a str (modified in place). */
void
svn_stringbuf_strip_whitespace(svn_stringbuf_t *str);

/** Return position of last occurrence of @a ch in @a str, or return
 * @a str->len if no occurrence.
 */
apr_size_t
svn_stringbuf_find_char_backward(const svn_stringbuf_t *str, char ch);

/** Return @c TRUE iff @a str1 and @a str2 have identical length and data. */
svn_boolean_t
svn_string_compare_stringbuf(const svn_string_t *str1,
                             const svn_stringbuf_t *str2);

/** @} */

