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. 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).
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.
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.
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. More...
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. 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.
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. 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.

# @if copyrights

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations

# under the License.

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.