Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Related Pages

str: Dynamically allocated string library.


Data Structures

struct  str
 The basic string structure. More...

struct  str_sortentry
 This struct is used to serve in lists of pointers into a string for sorting. More...


Overhead Functions

#define str_ready(S, SZ)   str_alloc(S,SZ,0)
 Make sure string S has at least SZ bytes ready (no copy).

#define str_realloc(S, SZ)   str_alloc(S,SZ,1)
 Reallocate string S to size SZ bytes, copying the existing string.

int str_truncate (str *s, unsigned len)
 Truncate a string.


In-place Modification Functions

#define str_strip(S)   (str_rstrip(S), str_lstrip(S))
void str_upper (str *s)
 Translate all lower-case characters to upper-case.

void str_subst (str *s, char from, char to)
 Substitute one character for another throughout the string.


Searching Functions

#define str_findfirst(S, C)   str_findnext(S,C,0)
#define str_findfirstof(S, L)   str_findnextof(S,L,0)
#define str_findfirstnot(S, L)   str_findnextnot(S,L,0)
#define str_findlast(S, C)   str_findprev(S,C,-1)
#define str_findlastof(S, L)   str_findprevof(S,L,-1)
#define str_findlastnot(S, L)   str_findprevof(S,L,-1)

Globals

const char str_lcase_digits [36]
 Lower-case digits, also used for decimal numbers.

const char str_ucase_digits [36]
 Upper-case digits.


Defines

#define STR_BLOCKSIZE   16
 The block size in which string memory is allocated.


Typedefs

typedef str str
typedef str_sortentry str_sortentry

Functions

int str_init (str *s)
 Initialize a string, giving it a small empty allocation.

int str_alloc (str *s, unsigned size, int copy)
 Allocate storage for a string.

void str_free (str *s)
 Free a string's storage.

int str_copy (str *s, const str *in)
 Copy in a string.

int str_copys (str *s, const char *in)
 Copy in a C string.

int str_copyb (str *s, const char *in, unsigned len)
 Copy in a binary block.

int str_copy2s (str *s, const char *a, const char *b)
 Copy in the concatenation of 2 C strings.

int str_copy3s (str *s, const char *a, const char *b, const char *c)
 Copy in the concatenation of 3 C strings.

int str_copy4s (str *s, const char *a, const char *b, const char *c, const char *d)
 Copy in the concatenation of 4 C strings.

int str_copy5s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e)
 Copy in the concatenation of 5 C strings.

int str_copy6s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e, const char *f)
 Copy in the concatenation of 6 C strings.

int str_cat (str *s, const str *in)
 Append another string.

int str_cats (str *s, const char *in)
 Append a C string.

int str_catc (str *s, char in)
 Append a single character.

int str_catb (str *s, const char *in, unsigned len)
 Append a binary block.

int str_cati (str *s, long in)
 Append a signed integer in decimal.

int str_catiw (str *s, long in, unsigned width, char pad)
 Append a signed integer in decimal, padded to a minimum width.

int str_catu (str *s, unsigned long in)
 Append an unsigned integer in decimal, padded to a minimum width.

int str_catuw (str *s, unsigned long in, unsigned width, char pad)
 Append an unsigned integer in decimal.

int str_catx (str *s, unsigned long in)
 Append an unsigned integer in hexadecimal, padded to a minimum width.

int str_catxw (str *s, unsigned long in, unsigned width, char pad)
 Append an unsigned integer in hexadecimal.

int str_catill (str *s, long long in)
 Append a signed long long integer in decimal.

int str_catiwll (str *s, long long in, unsigned width, char pad)
 Append a signed long long integer in decimal, padded to a minimum width.

int str_catull (str *s, unsigned long long in)
 Append an unsigned long long integer in decimal.

int str_catuwll (str *s, unsigned long long in, unsigned width, char pad)
 Append an unsigned long long integer in decimal, padded to a minimum width.

int str_catxll (str *s, unsigned long long in)
 Append an unsigned long long integer in hexadecimal.

int str_catxwll (str *s, unsigned long long in, unsigned width, char pad)
 Append an unsigned long long integer in hexadecimal, padded to a minimum width.

int str_catsnumw (str *s, long in, unsigned width, char pad, unsigned base, const char *digits)
 Append a signed integer, optionally padded to a minimum width.

int str_catunumw (str *s, unsigned long in, unsigned width, char pad, unsigned base, const char *digits)
 Append an unsigned integer, optionally padded to a minimum width.

int str_catsllnumw (str *s, long long in, unsigned width, char pad, unsigned base, const char *digits)
 Append a signed long long integer, optionally padded to a minimum width.

int str_catullnumw (str *s, unsigned long long in, unsigned width, char pad, unsigned base, const char *digits)
 Append an unsigned long long integer, optionally padded to a minimum width.

int str_cat2s (str *s, const char *a, const char *b)
 Append 2 C strings.

int str_cat3s (str *s, const char *a, const char *b, const char *c)
 Append 3 C strings.

int str_cat4s (str *s, const char *a, const char *b, const char *c, const char *d)
 Append 4 C strings.

int str_cat5s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e)
 Append 5 C strings.

int str_cat6s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e, const char *f)
 Append 6 C strings.

int str_join (str *s, char sep, const str *in)
 Join two strings together with exactly one instance of the seperator.

int str_joins (str *s, char sep, const char *in)
 Join a C string to this string.

int str_joinb (str *s, char sep, const char *in, unsigned len)
 Join a binary block to this string.

void str_lower (str *s)
 Translate all upper-case characters to lower-case.

void str_lstrip (str *s)
 Strip all white space from the left (front) of the string.

void str_rstrip (str *s)
 Strip all white space from the right (end) of the string.

void str_lcut (str *s, unsigned count)
 Cut count bytes from the left (front) of the string.

void str_rcut (str *s, unsigned count)
 Cut count bytes from the right (end) of the string.

int str_sort (str *s, char sep, long count, int(*fn)(const str_sortentry *a, const str_sortentry *b))
 Sort a string.

int str_cmp (const str *a, unsigned aoffset, const str *b, unsigned boffset)
 Compare part of two strings.

int str_cmps (const str *a, unsigned offset, const char *b)
 Compare a string against a C string.

int str_cmpb (const str *a, unsigned offset, const char *b, unsigned len)
 Compare a string against a binary block.

int str_diff (const str *a, const str *b)
 Differentiate two strings.

int str_diffs (const str *a, const char *b)
 Differentiate a string and a C string.

int str_diffb (const str *a, const char *b, unsigned len)
 Differentiate a string and a binary block.

int str_start (const str *a, const str *b)
 Match the prefix of the string to another string.

int str_starts (const str *a, const char *b)
 Match the prefix of the string to a C string.

int str_startb (const str *a, const char *b, unsigned len)
 Match the prefix of the string to a binary chunk.

int str_case_start (const str *a, const str *b)
 Match the prefix of the string to another string.

int str_case_starts (const str *a, const char *b)
 Match the prefix of the string to a C string.

int str_case_startb (const str *a, const char *b, unsigned len)
 Match the prefix of the string to a binary chunk.

void str_buildmap (int map[256], const char *list)
 Build a map from the list of characters.

unsigned str_count (const str *s, char ch)
 Count the number of instances of a character.

unsigned str_countof (const str *s, const char *list)
 Count the number of instances of a list of characters.

int str_findnext (const str *s, char ch, unsigned pos)
 Find the next instance of the given character, on or after pos.

int str_findnextof (const str *s, const char *list, unsigned pos)
 Find the next instance of the given list of characters, on or after pos.

int str_findnextnot (const str *s, const char *list, unsigned pos)
 Find the next instance of a character not in the given list of characters, on or after pos.

int str_findprev (const str *s, char ch, unsigned pos)
 Find the previous instance of the given character on or before pos.

int str_findprevof (const str *s, const char *list, unsigned pos)
 Find the previous instance of the given list of characters, on or before pos.

int str_findprevnot (const str *s, const char *list, unsigned pos)
 Find the previous instance of a character not in the given list of characters, on or before pos.

int str_match (const str *s, const str *pattern)
 Simple pattern match on dynamic string pattern.

int str_matchb (const str *s, const char *pptr, unsigned plen)
 Simple but fast (linear time) pattern matching on binary pattern.

int str_matchs (const str *s, const char *pattern)
 Simple pattern match on C string pattern.

int str_case_match (const str *s, const str *pattern)
 Simple pattern match on dynamic string pattern.

int str_case_matchb (const str *s, const char *pptr, unsigned plen)
 Simple but fast (linear time) pattern matching on binary pattern.

int str_case_matchs (const str *s, const char *pattern)
 Simple pattern match on C string pattern.

int str_glob (const str *s, const str *pattern)
int str_globb (const str *s, const char *pptr, unsigned plen)
int str_globs (const str *s, const char *pattern)
int str_case_glob (const str *s, const str *pattern)
int str_case_globb (const str *s, const char *pptr, unsigned plen)
int str_case_globs (const str *s, const char *pattern)

Detailed Description

Calling Convention
The standard calling convention to str functions is to pass the string being examined or modified as the first argument. For most functions, the return value will be 0 (false) if an error occurred (ie memory allocation failed) and non-zero (true) otherwise.

Define Documentation

#define STR_BLOCKSIZE   16
 

The block size in which string memory is allocated.

STR_BLOCKSIZE should be set to at least the size at which the allocator (ie malloc) will align the data it returns. String data will be allocated in steps of this number. Values smaller than the alignment will only cause a small amount of space to be wasted, and will not trigger bugs.


Function Documentation

int str_alloc str s,
unsigned  size,
int  copy
 

Allocate storage for a string.

Parameters:
s String to modify.
size Minimum number of bytes for which to allocate.
copy If set, the existing string will be copied into the new string.
The size given is incremented to account for adding a trailing NUL byte (to ensure compatibility with C string functions) and is then rounded up to the nearest STR_BLOCKSIZE interval.

void str_buildmap int  map[256],
const char *  list
 

Build a map from the list of characters.

Each byte in the output map contains either -1 if the corresponding character was not present in the input string, or the offset of the last instance of the character in the list.

int str_cmp const str a,
unsigned  aoffset,
const str b,
unsigned  boffset
 

Compare part of two strings.

This function compares two strings, starting at aoffset bytes into a and boffset bytes into b. The first non-zero difference is returned. If the portion of b is longer than the portion of a, the result is positive.

int str_diff const str a,
const str b
 

Differentiate two strings.

The first non-zero difference between a and b is returned. If a is longer than b and no differences are found up to the length of b, then the return value is positive. If b is longer than a and no differences are found up to the length of a, then the return value is negative.

void str_free str s  ) 
 

Free a string's storage.

This function also sets all the members of the structure to zero.

int str_sort str s,
char  sep,
long  count,
int(*  fn)(const str_sortentry *a, const str_sortentry *b)
 

Sort a string.

Parameters:
s The string to sort.
sep The character which delimits the substrings.
count The number of substrings within s (set to -1 if not known).
fn The comparison function. Defaults to a function that works like memcmp.
Note:
This function allocates a temporary array of substring pointers, and so may return 0 if memory allocation fails. The string itself is not reallocated.

int str_truncate str s,
unsigned  len
 

Truncate a string.

If len is larger than the current size, the string is reallocated. If len is less than the existing length (not size), the length of the string is reduced to len. A NUL marker is placed at len.


Generated on Mon Dec 1 13:28:06 2003 for bglibs by doxygen 1.3.3