str: Dynamically allocated string library.

Data Structures
struct	str
struct	str_sortentry
Globals
const char	str_lcase_digits [36]
const char	str_ucase_digits [36]
Overhead Functions
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)
#define	str_ready(S, SZ)   str_alloc(S,SZ,0)
#define	str_realloc(S, SZ)   str_alloc(S,SZ,1)
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_copyf (str *s, const char *format,...)
int	str_copyfv (str *s, const char *format, va_list ap)
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_catf (str *s, const char *format,...)
int	str_catfv (str *s, const char *format, va_list ap)
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)
In-place Modification Functions
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)
#define	str_strip(S)   (str_rstrip(S), str_lstrip(S))
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)
Searching Functions
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)
#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)
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)
Defines
#define	STR_BLOCKSIZE   16
Typedefs
typedef struct str	str
typedef struct str_sortentry	str_sortentry

---

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

---

Typedef Documentation

typedef struct str str

String structure typedef.

typedef struct str_sortentry str_sortentry

String sort entry typedef.

---

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_catf	(	str *	s,
		const char *	format,
			...
	)

Append formatted data using fmt_multi from variable arguments

int str_catfv	(	str *	s,
		const char *	format,
		va_list	ap
	)

Append formatted data using fmt_multi from a va_list

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_copyf	(	str *	s,
		const char *	format,
			...
	)

Copy formatted data using fmt_multi from variable arguments

int str_copyfv	(	str *	s,
		const char *	format,
		va_list	ap
	)

Copy formatted data using fmt_multi from a va_list

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 *	in
	)

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(*)(const str_sortentry *a, const str_sortentry *b)	fn
	)

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_ucase_digits[36]

Upper-case digits.

---