Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Typedefs | Functions
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_tsvn_string_create (const char *cstring, apr_pool_t *pool)
 Create a new bytestring containing a C string (NULL-terminated).
 
svn_string_tsvn_string_ncreate (const char *bytes, apr_size_t size, apr_pool_t *pool)
 Create a new bytestring containing a generic string of bytes (NOT NULL-terminated)
 
svn_string_tsvn_string_create_from_buf (const svn_stringbuf_t *strbuf, apr_pool_t *pool)
 Create a new string with the contents of the given stringbuf.
 
svn_string_tsvn_string_createf (apr_pool_t *pool, const char *fmt,...)
 Create a new bytestring by formatting cstring (NULL-terminated) from varargs, which are as appropriate for apr_psprintf().
 
svn_string_tsvn_string_createv (apr_pool_t *pool, const char *fmt, va_list ap)
 Create a new bytestring by formatting cstring (NULL-terminated) from a va_list (see svn_stringbuf_createf()).
 
svn_boolean_t svn_string_isempty (const svn_string_t *str)
 Return TRUE if a bytestring is empty (has length zero).
 
svn_string_tsvn_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_tsvn_stringbuf_create (const char *cstring, apr_pool_t *pool)
 Create a new bytestring containing a C string (NULL-terminated).
 
svn_stringbuf_tsvn_stringbuf_ncreate (const char *bytes, apr_size_t size, apr_pool_t *pool)
 Create a new bytestring containing a generic string of bytes (NON-NULL-terminated)
 
svn_stringbuf_tsvn_stringbuf_create_ensure (apr_size_t minimum_size, apr_pool_t *pool)
 Create a new empty bytestring with at least minimum_size bytes of space available in the memory block.
 
svn_stringbuf_tsvn_stringbuf_create_from_string (const svn_string_t *str, apr_pool_t *pool)
 Create a new stringbuf with the contents of the given string.
 
svn_stringbuf_tsvn_stringbuf_createf (apr_pool_t *pool, const char *fmt,...)
 Create a new bytestring by formatting cstring (NULL-terminated) from varargs, which are as appropriate for apr_psprintf().
 
svn_stringbuf_tsvn_stringbuf_createv (apr_pool_t *pool, const char *fmt, va_list ap)
 Create a new bytestring by formatting cstring (NULL-terminated) from a va_list (see svn_stringbuf_createf()).
 
void svn_stringbuf_ensure (svn_stringbuf_t *str, apr_size_t minimum_size)
 Make sure that the string 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 a bytestring str to value.
 
void svn_stringbuf_setempty (svn_stringbuf_t *str)
 Set a bytestring str to empty (0 length).
 
svn_boolean_t svn_stringbuf_isempty (const svn_stringbuf_t *str)
 Return TRUE if a bytestring 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_fillchar (svn_stringbuf_t *str, unsigned char c)
 Fill bytestring str with character c.
 
void svn_stringbuf_appendbyte (svn_stringbuf_t *targetstr, char byte)
 Append a single character byte onto targetstr.
 
void svn_stringbuf_appendbytes (svn_stringbuf_t *targetstr, const char *bytes, apr_size_t count)
 Append an array of bytes onto targetstr.
 
void svn_stringbuf_appendstr (svn_stringbuf_t *targetstr, const svn_stringbuf_t *appendstr)
 Append an svn_stringbuf_t onto targetstr.
 
void svn_stringbuf_appendcstr (svn_stringbuf_t *targetstr, const char *cstr)
 Append a C string onto targetstr.
 
svn_stringbuf_tsvn_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 along sep_chars boundaries, return an array of copies of those substrings (plain const char*), allocating both the array and the copies in pool.
 
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.
 
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_join (const apr_array_header_t *strings, const char *separator, apr_pool_t *pool)
 Return a cstring which is the concatenation of strings (an array of char *) each followed by separator (that is, separator will also end the resulting string).
 
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_tsvn_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_tsvn_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_tsvn_cstring_atoi (int *n, const char *str)
 Parse the C string str into a 32 bit number, and return it in *n.
 
svn_error_tsvn_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_tsvn_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_tsvn_cstring_atoui (unsigned int *n, const char *str)
 Parse the C string str into an unsigned 32 bit number, and return it in *n.
 

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.

  1. Non-NULL input:

    All the functions assume their input data 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.