Loading...
Searching...
No Matches
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.
typedef struct svn_stringbuf_t | svn_stringbuf_t
| A buffered string, capable of appending without an allocation and copy for each append.

## 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.
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.
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.
svn_boolean_t | svn_string_isempty (const svn_string_t *str)
| Return TRUE if str is empty (has length zero).
svn_string_t * | svn_string_dup (const svn_string_t *original_string, apr_pool_t *pool)
| Return a duplicate of original_string.
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.
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.
svn_stringbuf_t * | svn_stringbuf_create_empty (apr_pool_t *pool)
| Create a new, empty stringbuf.
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.
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.
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.
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.
void | svn_stringbuf_set (svn_stringbuf_t *str, const char *value)
| Set str to a copy of the null-terminated C string value.
void | svn_stringbuf_setempty (svn_stringbuf_t *str)
| Set str to empty (zero length).
svn_boolean_t | svn_stringbuf_isempty (const svn_stringbuf_t *str)
| Return `TRUE` if str is empty (has length zero).
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.
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.
void | svn_stringbuf_fillchar (svn_stringbuf_t *str, unsigned char c)
| Fill str with character c.
void | svn_stringbuf_appendbyte (svn_stringbuf_t *targetstr, char byte)
| Append the single character byte onto targetstr.
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.
void | svn_stringbuf_appendfill (svn_stringbuf_t *targetstr, char byte, apr_size_t count)
| Append byte count times onto targetstr.
void | svn_stringbuf_appendstr (svn_stringbuf_t *targetstr, const svn_stringbuf_t *appendstr)
| Append the stringbuf `appendstr` onto targetstr.
void | svn_stringbuf_appendcstr (svn_stringbuf_t *targetstr, const char *cstr)
| Append the C string cstr onto targetstr.
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.
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.
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.
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.
svn_stringbuf_t * | svn_stringbuf_dup (const svn_stringbuf_t *original_string, apr_pool_t *pool)
| Return a duplicate of original_string.
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.
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).
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.
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.
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.
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.
char * | svn_cstring_tokenize (const char *sep, char **str)
| Get the next token from *str interpreting any char from sep as a token separator.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.

## Detailed Description

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

# autotoc_md119

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.