diff options
Diffstat (limited to 'subversion/include/svn_string.h')
| -rw-r--r-- | subversion/include/svn_string.h | 158 |
1 files changed, 126 insertions, 32 deletions
diff --git a/subversion/include/svn_string.h b/subversion/include/svn_string.h index 3df4ae0..d8ce02b 100644 --- a/subversion/include/svn_string.h +++ b/subversion/include/svn_string.h @@ -54,13 +54,13 @@ * * Note that an @c svn_string(buf)_t may contain binary data, * which means that strlen(s->data) does not have to equal @c - * s->len. The NULL terminator is provided to make it easier to + * s->len. The null terminator is provided to make it easier to * pass @c s->data to C string interfaces. * * * 2. Non-NULL input: * - * All the functions assume their input data is non-NULL, + * All the functions assume their input data pointer is non-NULL, * unless otherwise documented, and may seg fault if passed * NULL. The input data may *contain* null bytes, of course, just * the data pointer itself must not be NULL. @@ -125,34 +125,46 @@ typedef struct svn_stringbuf_t * @{ */ -/** Create a new bytestring containing a C string (NULL-terminated). */ +/** Create a new string copied from the null-terminated C string @a cstring. + */ svn_string_t * svn_string_create(const char *cstring, apr_pool_t *pool); -/** Create a new bytestring containing a generic string of bytes - * (NOT NULL-terminated) */ +/** Create a new, empty string. + * + * @since New in 1.8. + */ +svn_string_t * +svn_string_create_empty(apr_pool_t *pool); + +/** Create a new string copied from a generic string of bytes, @a bytes, of + * length @a size bytes. @a bytes is NOT assumed to be null-terminated, but + * the new string will be. + */ svn_string_t * svn_string_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool); -/** Create a new string with the contents of the given stringbuf */ +/** Create a new string copied from the stringbuf @a strbuf. + */ svn_string_t * svn_string_create_from_buf(const svn_stringbuf_t *strbuf, apr_pool_t *pool); -/** Create a new bytestring by formatting @a cstring (NULL-terminated) - * from varargs, which are as appropriate for apr_psprintf(). +/** Create a new string by printf-style formatting using @a fmt and the + * variable arguments, which are as appropriate for apr_psprintf(). */ svn_string_t * svn_string_createf(apr_pool_t *pool, const char *fmt, ...) __attribute__((format(printf, 2, 3))); -/** Create a new bytestring by formatting @a cstring (NULL-terminated) - * from a @c va_list (see svn_stringbuf_createf()). +/** Create a new string by printf-style formatting using @c fmt and @a ap. + * This is the same as svn_string_createf() except for the different + * way of passing the variable arguments. */ svn_string_t * svn_string_createv(apr_pool_t *pool, const char *fmt, va_list ap) __attribute__((format(printf, 2, 0))); -/** Return TRUE if a bytestring is empty (has length zero). */ +/** Return TRUE if @a str is empty (has length zero). */ svn_boolean_t svn_string_isempty(const svn_string_t *str); @@ -184,62 +196,80 @@ svn_string_find_char_backward(const svn_string_t *str, char ch); * @{ */ -/** Create a new bytestring containing a C string (NULL-terminated). */ +/** Create a new stringbuf copied from the null-terminated C string + * @a cstring. + */ svn_stringbuf_t * svn_stringbuf_create(const char *cstring, apr_pool_t *pool); -/** Create a new bytestring containing a generic string of bytes - * (NON-NULL-terminated) +/** Create a new stringbuf copied from the generic string of bytes, @a bytes, + * of length @a size bytes. @a bytes is NOT assumed to be null-terminated, + * but the new stringbuf will be. */ svn_stringbuf_t * svn_stringbuf_ncreate(const char *bytes, apr_size_t size, apr_pool_t *pool); -/** Create a new empty bytestring with at least @a minimum_size bytes of +/** Create a new, empty stringbuf. + * + * @since New in 1.8. + */ +svn_stringbuf_t * +svn_stringbuf_create_empty(apr_pool_t *pool); + +/** Create a new, empty stringbuf with at least @a minimum_size bytes of * space available in the memory block. * - * The allocated string buffer will be one byte larger than @a minimum_size - * to account for a final '\\0'. + * The allocated string buffer will be at least one byte larger than + * @a minimum_size to account for a final '\\0'. * * @since New in 1.6. */ svn_stringbuf_t * svn_stringbuf_create_ensure(apr_size_t minimum_size, apr_pool_t *pool); -/** Create a new stringbuf with the contents of the given string */ +/** Create a new stringbuf copied from the string @a str. + */ svn_stringbuf_t * svn_stringbuf_create_from_string(const svn_string_t *str, apr_pool_t *pool); -/** Create a new bytestring by formatting @a cstring (NULL-terminated) - * from varargs, which are as appropriate for apr_psprintf(). +/** Create a new stringbuf by printf-style formatting using @a fmt and the + * variable arguments, which are as appropriate for apr_psprintf(). */ svn_stringbuf_t * svn_stringbuf_createf(apr_pool_t *pool, const char *fmt, ...) __attribute__((format(printf, 2, 3))); -/** Create a new bytestring by formatting @a cstring (NULL-terminated) - * from a @c va_list (see svn_stringbuf_createf()). +/** 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 the string @a str has at least @a minimum_size bytes of - * space available in the memory block. +/** 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'. * - * (@a minimum_size should include space for the terminating NULL character.) + * @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 bytestring @a str to @a value */ +/** 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 bytestring @a str to empty (0 length). */ +/** Set @a str to empty (zero length). */ void svn_stringbuf_setempty(svn_stringbuf_t *str); -/** Return @c TRUE if a bytestring is empty (has length zero). */ +/** Return @c TRUE if @a str is empty (has length zero). */ svn_boolean_t svn_stringbuf_isempty(const svn_stringbuf_t *str); @@ -247,11 +277,12 @@ svn_stringbuf_isempty(const svn_stringbuf_t *str); void svn_stringbuf_chop(svn_stringbuf_t *str, apr_size_t nbytes); -/** Fill bytestring @a str with character @a c. */ +/** Fill @a str with character @a c. */ void svn_stringbuf_fillchar(svn_stringbuf_t *str, unsigned char c); -/** Append a single character @a byte onto @a targetstr. +/** 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 @@ -273,7 +304,7 @@ svn_stringbuf_appendbytes(svn_stringbuf_t *targetstr, const char *bytes, apr_size_t count); -/** Append an @c svn_stringbuf_t onto @a targetstr. +/** Append the stringbuf @c appendstr onto @a targetstr. * * reallocs if necessary. @a targetstr is affected, nothing else is. */ @@ -281,7 +312,7 @@ void svn_stringbuf_appendstr(svn_stringbuf_t *targetstr, const svn_stringbuf_t *appendstr); -/** Append a C string onto @a targetstr. +/** Append the C string @a cstr onto @a targetstr. * * reallocs if necessary. @a targetstr is affected, nothing else is. */ @@ -289,6 +320,55 @@ void svn_stringbuf_appendcstr(svn_stringbuf_t *targetstr, const char *cstr); +/** Read @a count bytes from @a bytes and insert them into @a str at + * position @a pos and following. The resulting string will be + * @c count+str->len bytes long. If @c pos is larger or equal to the + * number of bytes currently used in @a str, simply append @a bytes. + * + * Reallocs if necessary. @a str is affected, nothing else is. + * + * @note The inserted string may be a sub-range if @a str. + * + * @since New in 1.8. + */ +void +svn_stringbuf_insert(svn_stringbuf_t *str, + apr_size_t pos, + const char *bytes, + apr_size_t count); + +/** Removes @a count bytes from @a str, starting at position @a pos. + * If that range exceeds the current string data, @a str gets truncated + * at @a pos. If the latter is larger or equal to @c str->pos, 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. + */ +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); + /** Return a duplicate of @a original_string. */ svn_stringbuf_t * svn_stringbuf_dup(const svn_stringbuf_t *original_string, apr_pool_t *pool); @@ -371,6 +451,20 @@ svn_boolean_t svn_cstring_match_list(const char *str, const apr_array_header_t *list); /** + * Get the next token from @a *str interpreting any char from @a sep as a + * token separator. Separators at the beginning of @a str will be skipped. + * Returns a pointer to the beginning of the first token in @a *str or NULL + * if no token is left. Modifies @a str such that the next call will return + * the next token. + * + * @note The content of @a *str may be modified by this function. + * + * @since New in 1.8. + */ +char * +svn_cstring_tokenize(const char *sep, char **str); + +/** * Return the number of line breaks in @a msg, allowing any kind of newline * termination (CR, LF, CRLF, or LFCR), even inconsistent. * |