svn_string.h File Reference

Counted-length strings for Subversion, plus some C string goodies. More...

#include <apr.h>
#include <apr_pools.h>
#include <apr_tables.h>
#include "svn_types.h"

Go to the source code of this file.

Data Structures
struct	svn_string_t
	A simple counted string. More...
struct	svn_stringbuf_t
	A buffered string, capable of appending without an allocation and copy for each append. More...

Typedefs
typedef struct svn_string_t	svn_string_t
	A simple counted string. More...
typedef struct svn_stringbuf_t	svn_stringbuf_t
	A buffered string, capable of appending without an allocation and copy for each append. More...

Functions
svn_string_t *	svn_string_create (const char *cstring, apr_pool_t *pool)
	Create a new string copied from the null-terminated C string cstring.
svn_string_t *	svn_string_create_empty (apr_pool_t *pool)
	Create a new, empty string. More...
svn_string_t *	svn_string_ncreate (const char *bytes, apr_size_t size, apr_pool_t *pool)
	Create a new string copied from a generic string of bytes, bytes, of length size bytes. More...
svn_string_t *	svn_string_create_from_buf (const svn_stringbuf_t *strbuf, apr_pool_t *pool)
	Create a new string copied from the stringbuf strbuf.
svn_string_t *	svn_string_createf (apr_pool_t *pool, const char *fmt,...)
	Create a new string by printf-style formatting using fmt and the variable arguments, which are as appropriate for apr_psprintf().
svn_string_t *	svn_string_createv (apr_pool_t *pool, const char *fmt, va_list ap)
	Create a new string by printf-style formatting using fmt and ap. More...
svn_boolean_t	svn_string_isempty (const svn_string_t *str)
	Return TRUE if str is empty (has length zero). More...
svn_string_t *	svn_string_dup (const svn_string_t *original_string, apr_pool_t *pool)
	Return a duplicate of original_string. More...
svn_boolean_t	svn_string_compare (const svn_string_t *str1, const svn_string_t *str2)
	Return TRUE iff str1 and str2 have identical length and data. More...
apr_size_t	svn_string_first_non_whitespace (const svn_string_t *str)
	Return offset of first non-whitespace character in str, or return str->len if none.
apr_size_t	svn_string_find_char_backward (const svn_string_t *str, char ch)
	Return position of last occurrence of ch in str, or return str->len if no occurrence.
svn_stringbuf_t *	svn_stringbuf_create (const char *cstring, apr_pool_t *pool)
	Create a new stringbuf copied from the null-terminated C string cstring.
svn_stringbuf_t *	svn_stringbuf_ncreate (const char *bytes, apr_size_t size, apr_pool_t *pool)
	Create a new stringbuf copied from the generic string of bytes, bytes, of length size bytes. More...
svn_stringbuf_t *	svn_stringbuf_create_empty (apr_pool_t *pool)
	Create a new, empty stringbuf. More...
svn_stringbuf_t *	svn_stringbuf_create_ensure (apr_size_t minimum_size, apr_pool_t *pool)
	Create a new, empty stringbuf with at least minimum_size bytes of space available in the memory block. More...
svn_stringbuf_t *	svn_stringbuf_create_from_string (const svn_string_t *str, apr_pool_t *pool)
	Create a new stringbuf copied from the string str.
svn_stringbuf_t *	svn_stringbuf_create_wrap (char *str, apr_pool_t *pool)
	Create a new stringbuf using the given str as initial buffer. More...
svn_stringbuf_t *	svn_stringbuf_createf (apr_pool_t *pool, const char *fmt,...)
	Create a new stringbuf by printf-style formatting using fmt and the variable arguments, which are as appropriate for apr_psprintf().
svn_stringbuf_t *	svn_stringbuf_createv (apr_pool_t *pool, const char *fmt, va_list ap)
	Create a new stringbuf by printf-style formatting using fmt and ap. More...
void	svn_stringbuf_ensure (svn_stringbuf_t *str, apr_size_t minimum_size)
	Make sure that str has at least minimum_size bytes of space available in the memory block. More...
void	svn_stringbuf_set (svn_stringbuf_t *str, const char *value)
	Set str to a copy of the null-terminated C string value. More...
void	svn_stringbuf_setempty (svn_stringbuf_t *str)
	Set str to empty (zero length). More...
svn_boolean_t	svn_stringbuf_isempty (const svn_stringbuf_t *str)
	Return TRUE if str is empty (has length zero). More...
void	svn_stringbuf_chop (svn_stringbuf_t *str, apr_size_t nbytes)
	Chop nbytes bytes off end of str, but not more than str->len. More...
void	svn_stringbuf_leftchop (svn_stringbuf_t *str, apr_size_t nbytes)
	Chop nbytes bytes off the start of str, but not more than str->len. More...
void	svn_stringbuf_fillchar (svn_stringbuf_t *str, unsigned char c)
	Fill str with character c. More...
void	svn_stringbuf_appendbyte (svn_stringbuf_t *targetstr, char byte)
	Append the single character byte onto targetstr. More...
void	svn_stringbuf_appendbytes (svn_stringbuf_t *targetstr, const char *bytes, apr_size_t count)
	Append the array of bytes bytes of length count onto targetstr. More...
void	svn_stringbuf_appendfill (svn_stringbuf_t *targetstr, char byte, apr_size_t count)
	Append byte count times onto targetstr. More...
void	svn_stringbuf_appendstr (svn_stringbuf_t *targetstr, const svn_stringbuf_t *appendstr)
	Append the stringbuf appendstr onto targetstr. More...
void	svn_stringbuf_appendcstr (svn_stringbuf_t *targetstr, const char *cstr)
	Append the C string cstr onto targetstr. More...
void	svn_stringbuf_insert (svn_stringbuf_t *str, apr_size_t pos, const char *bytes, apr_size_t count)
	Insert into str at position pos an array of bytes bytes which is count bytes long. More...
void	svn_stringbuf_remove (svn_stringbuf_t *str, apr_size_t pos, apr_size_t count)
	Remove count bytes from str, starting at position pos. More...
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 in str the substring which starts at pos and is old_count bytes long with a new substring bytes which is new_count bytes long. More...
apr_size_t	svn_stringbuf_replace_all (svn_stringbuf_t *str, const char *to_find, const char *replacement)
	Replace all occurrences of to_find in str with replacement. More...
svn_stringbuf_t *	svn_stringbuf_dup (const svn_stringbuf_t *original_string, apr_pool_t *pool)
	Return a duplicate of original_string. More...
svn_boolean_t	svn_stringbuf_compare (const svn_stringbuf_t *str1, const svn_stringbuf_t *str2)
	Return TRUE iff str1 and str2 have identical length and data. More...
apr_size_t	svn_stringbuf_first_non_whitespace (const svn_stringbuf_t *str)
	Return offset of first non-whitespace character in str, or return str->len if none.
void	svn_stringbuf_strip_whitespace (svn_stringbuf_t *str)
	Strip whitespace from both sides of str (modified in place). More...
apr_size_t	svn_stringbuf_find_char_backward (const svn_stringbuf_t *str, char ch)
	Return position of last occurrence of ch in str, or return str->len if no occurrence.
svn_boolean_t	svn_string_compare_stringbuf (const svn_string_t *str1, const svn_stringbuf_t *str2)
	Return TRUE iff str1 and str2 have identical length and data. More...
apr_array_header_t *	svn_cstring_split (const char *input, const char *sep_chars, svn_boolean_t chop_whitespace, apr_pool_t *pool)
	Divide input into substrings, interpreting any char from sep as a token separator. More...
void	svn_cstring_split_append (apr_array_header_t *array, const char *input, const char *sep_chars, svn_boolean_t chop_whitespace, apr_pool_t *pool)
	Like svn_cstring_split(), but append to existing array instead of creating a new one. More...
svn_boolean_t	svn_cstring_match_glob_list (const char *str, const apr_array_header_t *list)
	Return TRUE iff str matches any of the elements of list, a list of zero or more glob patterns.
svn_boolean_t	svn_cstring_match_list (const char *str, const apr_array_header_t *list)
	Return TRUE iff str exactly matches any of the elements of list. More...
char *	svn_cstring_tokenize (const char *sep, char **str)
	Get the next token from *str interpreting any char from sep as a token separator. More...
int	svn_cstring_count_newlines (const char *msg)
	Return the number of line breaks in msg, allowing any kind of newline termination (CR, LF, CRLF, or LFCR), even inconsistent. More...
char *	svn_cstring_join2 (const apr_array_header_t *strings, const char *separator, svn_boolean_t trailing_separator, apr_pool_t *pool)
	Return a cstring which is the concatenation of strings (an array of char *) joined by separator. More...
char *	svn_cstring_join (const apr_array_header_t *strings, const char *separator, apr_pool_t *pool)
	Similar to svn_cstring_join2(), but always includes the trailing separator. More...
int	svn_cstring_casecmp (const char *str1, const char *str2)
	Compare two strings atr1 and atr2, treating case-equivalent unaccented Latin (ASCII subset) letters as equal. More...
svn_error_t *	svn_cstring_strtoi64 (apr_int64_t *n, const char *str, apr_int64_t minval, apr_int64_t maxval, int base)
	Parse the C string str into a 64 bit number, and return it in *n. More...
svn_error_t *	svn_cstring_atoi64 (apr_int64_t *n, const char *str)
	Parse the C string str into a 64 bit number, and return it in *n. More...
svn_error_t *	svn_cstring_atoi (int *n, const char *str)
	Parse the C string str into a 32 bit number, and return it in *n. More...
svn_error_t *	svn_cstring_strtoui64 (apr_uint64_t *n, const char *str, apr_uint64_t minval, apr_uint64_t maxval, int base)
	Parse the C string str into an unsigned 64 bit number, and return it in *n. More...
svn_error_t *	svn_cstring_atoui64 (apr_uint64_t *n, const char *str)
	Parse the C string str into an unsigned 64 bit number, and return it in *n. More...
svn_error_t *	svn_cstring_atoui (unsigned int *n, const char *str)
	Parse the C string str into an unsigned 32 bit number, and return it in *n. More...
const char *	svn_cstring_skip_prefix (const char *str, const char *prefix)
	Skip the common prefix prefix from the C string str, and return a pointer to the next character after the prefix. More...

Detailed Description

Counted-length strings for Subversion, plus some C string goodies.

There are two string datatypes: svn_string_t and svn_stringbuf_t. The former is a simple pointer/length pair useful for passing around strings (or arbitrary bytes) with a counted length. svn_stringbuf_t is buffered to enable efficient appending of strings without an allocation and copy for each append operation.

svn_string_t contains a const char * for its data, so it is most appropriate for constant data and for functions which expect constant, counted data. Functions should generally use const svn_string_t * as their parameter to indicate they are expecting a constant, counted string.

svn_stringbuf_t uses a plain char * for its data, so it is most appropriate for modifiable data.

Invariants

1. Null termination:

   Both structures maintain a significant invariant:

   s->data[s->len] == '\0'

   The functions defined within this header file will maintain the invariant (which does imply that memory is allocated/defined as len+1 bytes). If code outside of the svn_string.h functions manually builds these structures, then they must enforce this invariant.

   Note that an svn_string(buf)_t may contain binary data, which means that strlen(s->data) does not have to equal s->len. The null terminator is provided to make it easier to pass s->data to C string interfaces.

2. Non-NULL input:

   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.

Memory allocation

All the functions make a deep copy of all input data, and never store a pointer to the original input data.

Definition in file svn_string.h.