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)
#define str_realloc(S, SZ)   str_alloc(S,SZ,1)
int str_init (str *s)
int str_alloc (str *s, unsigned size, int copy)
void str_free (str *s)
int str_truncate (str *s, unsigned len)

In-place Modification Functions

#define str_strip(S)   (str_rstrip(S), str_lstrip(S))
void str_lower (str *s)
void str_upper (str *s)
long str_subst (str *s, char from, char to)
void str_lstrip (str *s)
void str_rstrip (str *s)
void str_lcut (str *s, unsigned count)
void str_rcut (str *s, unsigned count)
int str_sort (str *s, char sep, long count, int(*fn)(const str_sortentry *a, const str_sortentry *b))
int str_splice (str *s, unsigned start, unsigned len, const str *r)
int str_splices (str *s, unsigned start, unsigned len, const char *r)
int str_spliceb (str *s, unsigned start, unsigned len, const char *r, unsigned rlen)
long str_xlate (str *s, const char *from, const char *to, unsigned nchars)

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)
void str_buildmap (int map[256], const char *list)
unsigned str_count (const str *s, char ch)
unsigned str_countof (const str *s, const char *list)
int str_findnext (const str *s, char ch, unsigned pos)
int str_findnextof (const str *s, const char *list, unsigned pos)
int str_findnextnot (const str *s, const char *list, unsigned pos)
int str_findprev (const str *s, char ch, unsigned pos)
int str_findprevof (const str *s, const char *list, unsigned pos)
int str_findprevnot (const str *s, const char *list, unsigned pos)

Assignment Functions

int str_copy (str *s, const str *in)
int str_copys (str *s, const char *in)
int str_copyb (str *s, const char *in, unsigned len)
int str_copyns (str *s, unsigned int count,...)
int str_copy2s (str *s, const char *a, const char *b)
int str_copy3s (str *s, const char *a, const char *b, const char *c)
int str_copy4s (str *s, const char *a, const char *b, const char *c, const char *d)
int str_copy5s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e)
int str_copy6s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e, const char *f)

Appending Functions

int str_cat (str *s, const str *in)
int str_cats (str *s, const char *in)
int str_catc (str *s, char in)
int str_catb (str *s, const char *in, unsigned len)
int str_cati (str *s, long in)
int str_catiw (str *s, long in, unsigned width, char pad)
int str_catu (str *s, unsigned long in)
int str_catuw (str *s, unsigned long in, unsigned width, char pad)
int str_catx (str *s, unsigned long in)
int str_catxw (str *s, unsigned long in, unsigned width, char pad)
int str_catill (str *s, long long in)
int str_catiwll (str *s, long long in, unsigned width, char pad)
int str_catull (str *s, unsigned long long in)
int str_catuwll (str *s, unsigned long long in, unsigned width, char pad)
int str_catxll (str *s, unsigned long long in)
int str_catxwll (str *s, unsigned long long in, unsigned width, char pad)
int str_catsnumw (str *s, long in, unsigned width, char pad, unsigned base, const char *digits)
int str_catunumw (str *s, unsigned long in, unsigned width, char pad, unsigned base, const char *digits)
int str_catsllnumw (str *s, long long in, unsigned width, char pad, unsigned base, const char *digits)
int str_catullnumw (str *s, unsigned long long in, unsigned width, char pad, unsigned base, const char *digits)
int str_catns (str *s, unsigned int count,...)
int str_cat2s (str *s, const char *a, const char *b)
int str_cat3s (str *s, const char *a, const char *b, const char *c)
int str_cat4s (str *s, const char *a, const char *b, const char *c, const char *d)
int str_cat5s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e)
int str_cat6s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e, const char *f)
int str_join (str *s, char sep, const str *t)
int str_joins (str *s, char sep, const char *in)
int str_joinb (str *s, char sep, const char *in, unsigned len)

Comparison Functions

int str_cmp (const str *a, unsigned aoffset, const str *b, unsigned boffset)
int str_cmps (const str *a, unsigned offset, const char *b)
int str_cmpb (const str *a, unsigned offset, const char *b, unsigned len)
int str_diff (const str *a, const str *b)
int str_diffs (const str *a, const char *b)
int str_diffb (const str *a, const char *b, unsigned len)
int str_start (const str *a, const str *b)
int str_starts (const str *a, const char *b)
int str_startb (const str *a, const char *b, unsigned len)
int str_case_start (const str *a, const str *b)
int str_case_starts (const str *a, const char *b)
int str_case_startb (const str *a, const char *b, unsigned len)

Pattern Matching Functions

int str_match (const str *s, const str *pattern)
int str_matchb (const str *s, const char *pptr, unsigned plen)
int str_matchs (const str *s, const char *pattern)
int str_case_match (const str *s, const str *pattern)
int str_case_matchb (const str *s, const char *pptr, unsigned plen)
int str_case_matchs (const str *s, const char *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)

Globals

const char str_lcase_digits [36]
const char str_ucase_digits [36]

Defines

#define STR_BLOCKSIZE   16

Typedefs

typedef str str
typedef str_sortentry str_sortentry

Variables

const char str_lcase_digits [36] = "0123456789abcdefghijklmnopqrstuvwxyz"
const char str_ucase_digits [36] = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"

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.

#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.


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_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_case_start const str a,
const str b
 

Match the prefix of the string to another string.

int str_case_startb const str a,
const char *  b,
unsigned  len
 

Match the prefix of the string to a binary chunk.

int str_case_starts const str a,
const char *  b
 

Match the prefix of the string to a C string.

int str_cat str s,
const str in
 

Append another string.

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_catb str s,
const char *  in,
unsigned  len
 

Append a binary block.

int str_catc str s,
char  in
 

Append a single character.

int str_cati str s,
long  in
 

Append a signed integer in decimal.

int str_catill str s,
long long  in
 

Append a signed long long 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_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_catns str s,
unsigned int  count,
... 
 

Append N C strings.

int str_cats str s,
const char *  in
 

Append a C string.

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_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_catu str s,
unsigned long  in
 

Append an unsigned 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_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_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_catuw str s,
unsigned long  in,
unsigned  width,
char  pad
 

Append an unsigned 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_catx str s,
unsigned long  in
 

Append an unsigned integer in hexadecimal, padded to a minimum width.

int str_catxll str s,
unsigned long long  in
 

Append an unsigned long long integer in hexadecimal.

int str_catxw str s,
unsigned long  in,
unsigned  width,
char  pad
 

Append an unsigned 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_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_cmpb const str a,
unsigned  offset,
const char *  b,
unsigned  len
 

Compare a string against a binary block.

int str_cmps const str a,
unsigned  offset,
const char *  b
 

Compare a string against a C string.

int str_copy str s,
const str in
 

Copy in a string.

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_copyb str s,
const char *  in,
unsigned  len
 

Copy in a binary block.

int str_copyns str s,
unsigned int  count,
... 
 

Copy in the concatenation of N C strings.

int str_copys str s,
const char *  in
 

Copy in a C string.

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_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.

int str_diffb const str a,
const char *  b,
unsigned  len
 

Differentiate a string and a binary block.

int str_diffs const str a,
const char *  b
 

Differentiate a string and a C string.

int str_findnext const str s,
char  ch,
unsigned  pos
 

Find the next instance of the given character, 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_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_findprev const str s,
char  ch,
unsigned  pos
 

Find the previous instance of the given character 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_findprevof const str s,
const char *  list,
unsigned  pos
 

Find the previous instance of the given list of characters, on or before pos.

void str_free str s  ) 
 

Free a string's storage.

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

int str_init str s  ) 
 

Initialize a string, giving it a small empty allocation.

int str_join str s,
char  sep,
const str t
 

Join two strings together with exactly one instance of the seperator.

int str_joinb str s,
char  sep,
const char *  in,
unsigned  len
 

Join a binary block to this string.

int str_joins str s,
char  sep,
const char *  in
 

Join a C string to this string.

void str_lcut str s,
unsigned  count
 

Cut count bytes from the left (front) of the 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.

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.

void str_rcut str s,
unsigned  count
 

Cut count bytes from the right (end) of the string.

void str_rstrip str s  ) 
 

Strip all white space 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.

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_start const str a,
const str b
 

Match the prefix of the string to another string.

int str_startb const str a,
const char *  b,
unsigned  len
 

Match the prefix of the string to a binary chunk.

int str_starts const str a,
const char *  b
 

Match the prefix of the string to a C string.

long str_subst str s,
char  from,
char  to
 

Substitute one character for another throughout the string.

Returns:
the number of substitutions made.

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.

void str_upper str s  ) 
 

Translate all lower-case characters to upper-case.

long str_xlate str s,
const char *  from,
const char *  to,
unsigned  nchars
 

Substitute one character for another throughout the string.

Returns:
the number of substitutions made.


Variable Documentation

const char str_lcase_digits[36]
 

Lower-case digits, also used for decimal numbers.

const char str_lcase_digits[36] = "0123456789abcdefghijklmnopqrstuvwxyz"
 

Lower-case digits, also used for decimal numbers.

const char str_ucase_digits[36]
 

Upper-case digits.

const char str_ucase_digits[36] = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
 

Upper-case digits.


Generated on Tue Mar 23 21:58:09 2004 for bglibs by doxygen 1.3.5