bstrlib.c File Reference

#include <stdio.h>
#include <stddef.h>
#include <stdarg.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <limits.h>
#include "bstrlib.h"

Data Structures
struct	charField
struct	bStream
struct	genBstrList

Macros
#define	bBlockCopy(D, S, L)
#define	upcase(c)
#define	downcase(c)
#define	wspace(c)
#define	LONG_LOG_BITS_QTY   (3)
#define	LONG_BITS_QTY   (1 << LONG_LOG_BITS_QTY)
#define	LONG_TYPE   unsigned char
#define	CFCLEN   ((1 << CHAR_BIT) / LONG_BITS_QTY)
#define	testInCharField(cf, c)
#define	setInCharField(cf, idx)
#define	INITIAL_STATIC_FIND_INDEX_COUNT   32
#define	BS_BUFF_SZ   (1024)
#define	BSSSC_BUFF_LEN   (256)
#define	exvsnprintf(r, b, n, f, a)
#define	START_VSNBUFF   (16)

Typedefs
typedef int(*	instr_fnptr) (const bstring s1, int pos, const bstring s2)

Functions
static int	snapUpSize (int i)
int	balloc (bstring b, int olen)
int	ballocmin (bstring b, int len)
bstring	bfromcstr (const char *str)
bstring	bfromcstralloc (int mlen, const char *str)
bstring	blk2bstr (const void *blk, int len)
char *	bstr2cstr (const bstring b, char z)
int	bcstrfree (char *s)
int	bconcat (bstring b0, const bstring b1)
int	bconchar (bstring b, char c)
int	bcatcstr (bstring b, const char *s)
int	bcatblk (bstring b, const void *s, int len)
bstring	bstrcpy (const bstring b)
int	bassign (bstring a, const bstring b)
int	bassignmidstr (bstring a, const bstring b, int left, int len)
int	bassigncstr (bstring a, const char *str)
int	bassignblk (bstring a, const void *s, int len)
int	btrunc (bstring b, int n)
int	btoupper (bstring b)
int	btolower (bstring b)
int	bstricmp (const bstring b0, const bstring b1)
int	bstrnicmp (const bstring b0, const bstring b1, int n)
int	biseqcaseless (const bstring b0, const bstring b1)
int	bisstemeqcaselessblk (const bstring b0, const void *blk, int len)
int	bltrimws (bstring b)
int	brtrimws (bstring b)
int	btrimws (bstring b)
int	biseq (const bstring b0, const bstring b1)
int	bisstemeqblk (const bstring b0, const void *blk, int len)
int	biseqcstr (const bstring b, const char *s)
int	biseqcstrcaseless (const bstring b, const char *s)
int	bstrcmp (const bstring b0, const bstring b1)
int	bstrncmp (const bstring b0, const bstring b1, int n)
bstring	bmidstr (const bstring b, int left, int len)
int	bdelete (bstring b, int pos, int len)
int	bdestroy (bstring b)
int	binstr (const bstring b1, int pos, const bstring b2)
int	binstrr (const bstring b1, int pos, const bstring b2)
int	binstrcaseless (const bstring b1, int pos, const bstring b2)
int	binstrrcaseless (const bstring b1, int pos, const bstring b2)
int	bstrchrp (const bstring b, int c, int pos)
int	bstrrchrp (const bstring b, int c, int pos)
static int	buildCharField (struct charField *cf, const bstring b)
static void	invertCharField (struct charField *cf)
static int	binchrCF (const unsigned char *data, int len, int pos, const struct charField *cf)
int	binchr (const bstring b0, int pos, const bstring b1)
static int	binchrrCF (const unsigned char *data, int pos, const struct charField *cf)
int	binchrr (const bstring b0, int pos, const bstring b1)
int	bninchr (const bstring b0, int pos, const bstring b1)
int	bninchrr (const bstring b0, int pos, const bstring b1)
int	bsetstr (bstring b0, int pos, const bstring b1, unsigned char fill)
int	binsert (bstring b1, int pos, const bstring b2, unsigned char fill)
int	breplace (bstring b1, int pos, int len, const bstring b2, unsigned char fill)
static int	findreplaceengine (bstring b, const bstring find, const bstring repl, int pos, instr_fnptr instr)
int	bfindreplace (bstring b, const bstring find, const bstring repl, int pos)
int	bfindreplacecaseless (bstring b, const bstring find, const bstring repl, int pos)
int	binsertch (bstring b, int pos, int len, unsigned char fill)
int	bpattern (bstring b, int len)
int	breada (bstring b, bNread readPtr, void *parm)
bstring	bread (bNread readPtr, void *parm)
int	bassigngets (bstring b, bNgetc getcPtr, void *parm, char terminator)
int	bgetsa (bstring b, bNgetc getcPtr, void *parm, char terminator)
bstring	bgets (bNgetc getcPtr, void *parm, char terminator)
struct bStream *	bsopen (bNread readPtr, void *parm)
int	bsbufflength (struct bStream *s, int sz)
int	bseof (const struct bStream *s)
void *	bsclose (struct bStream *s)
int	bsreadlna (bstring r, struct bStream *s, char terminator)
int	bsreadlnsa (bstring r, struct bStream *s, const bstring term)
int	bsreada (bstring r, struct bStream *s, int n)
int	bsreadln (bstring r, struct bStream *s, char terminator)
int	bsreadlns (bstring r, struct bStream *s, const bstring term)
int	bsread (bstring r, struct bStream *s, int n)
int	bsunread (struct bStream *s, const bstring b)
int	bspeek (bstring r, const struct bStream *s)
bstring	bjoin (const struct bstrList *bl, const bstring sep)
int	bssplitscb (struct bStream *s, const bstring splitStr, int(*cb)(void *parm, int ofs, const bstring entry), void *parm)
int	bssplitstrcb (struct bStream *s, const bstring splitStr, int(*cb)(void *parm, int ofs, const bstring entry), void *parm)
struct bstrList *	bstrListCreate (void)
int	bstrListDestroy (struct bstrList *sl)
int	bstrListAlloc (struct bstrList *sl, int msz)
int	bstrListAllocMin (struct bstrList *sl, int msz)
int	bsplitcb (const bstring str, unsigned char splitChar, int pos, int(*cb)(void *parm, int ofs, int len), void *parm)
int	bsplitscb (const bstring str, const bstring splitStr, int pos, int(*cb)(void *parm, int ofs, int len), void *parm)
int	bsplitstrcb (const bstring str, const bstring splitStr, int pos, int(*cb)(void *parm, int ofs, int len), void *parm)
static int	bscb (void *parm, int ofs, int len)
struct bstrList *	bsplit (const bstring str, unsigned char splitChar)
struct bstrList *	bsplitstr (const bstring str, const bstring splitStr)
struct bstrList *	bsplits (const bstring str, const bstring splitStr)
int	bformata (bstring b, const char *fmt,...)
int	bassignformat (bstring b, const char *fmt,...)
bstring	bformat (const char *fmt,...)
int	bvcformata (bstring b, int count, const char *fmt, va_list arg)

Macro Definition Documentation

bBlockCopy

#define bBlockCopy	(		D,
			S,
			L )

Value:

do { \
    if ((L) > 0) { \
        memmove((D), (S), (L)); \
    } \
} while (0);

BS_BUFF_SZ

#define BS_BUFF_SZ   (1024)

BSSSC_BUFF_LEN

#define BSSSC_BUFF_LEN   (256)

CFCLEN

#define CFCLEN   ((1 << CHAR_BIT) / LONG_BITS_QTY)

downcase

#define downcase

(

c

)

Value:

(tolower((unsigned char)c))

exvsnprintf

#define exvsnprintf	(		r,
			b,
			n,
			f,
			a )

Value:

{ \
    r = vsnprintf(b, n, f, a); \
}

INITIAL_STATIC_FIND_INDEX_COUNT

#define INITIAL_STATIC_FIND_INDEX_COUNT   32

LONG_BITS_QTY

#define LONG_BITS_QTY   (1 << LONG_LOG_BITS_QTY)

LONG_LOG_BITS_QTY

#define LONG_LOG_BITS_QTY   (3)

LONG_TYPE

#define LONG_TYPE   unsigned char

setInCharField

#define setInCharField	(		cf,
			idx )

Value:

do { \
    unsigned int c = (unsigned int)(idx); \
    (cf)->content[c >> LONG_LOG_BITS_QTY] |= (LONG_TYPE)(1ul << (c & (LONG_BITS_QTY-1))); \
} while (0)

START_VSNBUFF

#define START_VSNBUFF   (16)

testInCharField

#define testInCharField	(		cf,
			c )

Value:

((cf)->content[(c) >> LONG_LOG_BITS_QTY] & (((long)1) << ((c) & (LONG_BITS_QTY-1))))

upcase

#define upcase

(

c

)

Value:

(toupper((unsigned char)c))

wspace

#define wspace

(

c

)

Value:

(isspace((unsigned char)c))

Typedef Documentation

instr_fnptr

typedef int(* instr_fnptr) (const bstring s1, int pos, const bstring s2)

Function Documentation

balloc()

int balloc	(	bstring	s,
		int	len )

Increase the allocated memory backing the data buffer for the bstring b to a length of at least length.

If the memory backing the bstring b is already large enough, not action is performed. This has no effect on the bstring b that is visible to the bstring API. Usually this function will only be used when a minimum buffer size is required coupled with a direct access to the ->data member of the bstring structure.

Be warned that like any other bstring function, the bstring must be well defined upon entry to this function, i.e., doing something like:

b->slen *= 2;
balloc(b, b->slen);

is invalid, and should be implemented as:

int t;
if (BSTR_OK == balloc (b, t = (b->slen * 2))) {
    b->slen = t;
}

This function will return with BSTR_ERR if b is not detected as a valid bstring or length is not greater than 0, otherwise BSTR_OK is returned.

ballocmin()

int ballocmin	(	bstring	b,
		int	len )

Change the amount of memory backing the bstring b to at least length.

This operation will never truncate the bstring data including the extra terminating '\0' and thus will not decrease the length to less than b->slen + 1. Note that repeated use of this function may cause performance problems (realloc may be called on the bstring more than the O(log(INT_MAX)) times). This function will return with BSTR_ERR if b is not detected as a valid bstring or length is not greater than 0, otherwise BSTR_OK is returned.

So for example:

if (BSTR_OK == ballocmin (b, 64)) {
    b->data[63] = 'x';
}

The idea is that this will set the 64th character of b to 'x' if it is at least 64 characters long otherwise do nothing. And we know this is well defined so long as the ballocmin call was successfully, since it will ensure that b has been allocated with at least 64 characters.

bassign()

int bassign	(	bstring	a,
		const bstring	b )

Overwrite the bstring a with the contents of bstring b.

Note that the bstring a must be a well defined and writable bstring. If an error occurs BSTR_ERR is returned and a is not overwritten.

bassignblk()

int bassignblk	(	bstring	a,
		const void *	s,
		int	len )

Overwrite the bstring a with the middle of contents of bstring b starting from position left and running for a length len.

left and len are clamped to the ends of b as with the function bmidstr. Note that the bstring a must be a well defined and writable bstring. If an error occurs BSTR_ERR is returned and a is not overwritten.

bassigncstr()

int bassigncstr	(	bstring	a,
		const char *	str )

Overwrite the string a with the contents of char * string str.

Note that the bstring a must be a well defined and writable bstring. If an error occurs BSTR_ERR is returned and a may be partially overwritten.

bassignformat()

int bassignformat	(	bstring	b,
		const char *	fmt,
			... )

After the first parameter, it takes the same parameters as printf(), but rather than outputting results to stdio, it outputs the results to the bstring parameter b.

Note that if there is an early generation of a '\0' character, the bstring will be truncated to this end point.

Note that s format tokens correspond to '\0' terminated char * buffers, not bstrings. To print a bstring, first dereference data element of the the bstring:

b1->data needs to be '\0' terminated, so tagbstrings generated by blk2tbstr() might not be suitable.

bassignformat (b0 = bfromcstr ("Hello"), ", %s", b1->data);

bassigngets()

int bassigngets	(	bstring	b,
		bNgetc	getcPtr,
		void *	parm,
		char	terminator )

Read from a stream and concatenate to a bstring.

Behaves like bgets, except that it assigns the results to the bstring b. The value 1 is returned if no characters are read before a negative result is returned from getcPtr. Otherwise BSTR_ERR is returned on error, and 0 is returned in other normal cases.

bassignmidstr()

int bassignmidstr	(	bstring	a,
		const bstring	b,
		int	left,
		int	len )

Overwrite the bstring a with the middle of contents of bstring b starting from position left and running for a length len.

left and len are clamped to the ends of b as with the function bmidstr. Note that the bstring a must be a well defined and writable bstring. If an error occurs BSTR_ERR is returned and a is not overwritten.

bcatblk()

int bcatblk	(	bstring	b,
		const void *	s,
		int	len )

Concatenate a fixed length buffer (s, len) to the end of bstring b.

The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

bcatcstr()

int bcatcstr	(	bstring	b,
		const char *	s )

Concatenate the char * string s to the end of bstring b.

The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

bconcat()

int bconcat	(	bstring	b0,
		const bstring	b1 )

Concatenate the bstring b1 to the end of bstring b0.

The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

bconchar()

int bconchar	(	bstring	b0,
		char	c )

Concatenate the character c to the end of bstring b.

The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

bcstrfree()

int bcstrfree

(

char *

s

)

Frees a C-string generated by bstr2cstr().

This is normally unnecessary since it just wraps a call to free(), however, if malloc() and free() have been redefined as a macros within the bstrlib module (via macros in the memdbg.h backdoor) with some difference in behaviour from the std library functions, then this allows a correct way of freeing the memory that allows higher level code to be independent from these macro redefinitions.

bdelete()

int bdelete	(	bstring	s1,
		int	pos,
		int	len )

Removes characters from pos to pos+len-1 and shifts the tail of the bstring starting from pos+len to pos.

len must be positive for this call to have any effect. The section of the bstring described by (pos, len) is clamped to boundaries of the bstring b. The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

bdestroy()

int bdestroy

(

bstring

b

)

Deallocate the bstring passed.

Passing NULL in as a parameter will have no effect. Note that both the header and the data portion of the bstring will be freed. No other bstring function which modifies one of its parameters will free or reallocate the header. Because of this, in general, bdestroy cannot be called on any declared struct tagbstring even if it is not write protected. A bstring which is write protected cannot be destroyed via the bdestroy call. Any attempt to do so will result in no action taken, and BSTR_ERR will be returned.

bfindreplace()

int bfindreplace	(	bstring	b,
		const bstring	find,
		const bstring	repl,
		int	pos )

Replace all occurrences of the find substring with a replace bstring after a given position in the bstring b.

The find bstring must have a length > 0 otherwise BSTR_ERR is returned. This function does not perform recursive per character replacement; that is to say successive searches resume at the position after the last replace.

So for example:

bfindreplace(a0 = bfromcstr("aabaAb"), a1 = bfromcstr("a"),
             a2 = bfromcstr("aa"), 0);

Should result in changing a0 to "aaaabaaAb".

This function performs exactly (b->slen - position) bstring comparisons, and data movement is bounded above by character volume equivalent to size of the output bstring.

bfindreplacecaseless()

int bfindreplacecaseless	(	bstring	b,
		const bstring	find,
		const bstring	repl,
		int	pos )

Replace all occurrences of the find substring, ignoring case, with a replace bstring after a given position in the bstring b.

The find bstring must have a length > 0 otherwise BSTR_ERR is returned. This function does not perform recursive per character replacement; that is to say successive searches resume at the position after the last replace.

So for example:

bfindreplacecaseless(a0 = bfromcstr("AAbaAb"), a1 = bfromcstr("a"),
a2 = bfromcstr("aa"), 0);

Should result in changing a0 to "aaaabaaaab".

This function performs exactly (b->slen - position) bstring comparisons, and data movement is bounded above by character volume equivalent to size of the output bstring.

bformat()

bstring bformat	(	const char *	fmt,
			... )

Takes the same parameters as printf(), but rather than outputting results to stdio, it forms a bstring which contains what would have been output.

Note that if there is an early generation of a '\0' character, the bstring will be truncated to this end point.

Note that s format tokens correspond to '\0' terminated char * buffers, not bstrings. To print a bstring, first dereference data element of the the bstring:

b1->data needs to be '\0' terminated, so tagbstrings generated by blk2tbstr() might not be suitable.

b0 = bformat ("Hello, %s", b1->data);

bformata()

int bformata	(	bstring	b,
		const char *	fmt,
			... )

In addition to the initial output buffer b, bformata takes the same parameters as printf (), but rather than outputting results to stdio, it appends the results to the initial bstring parameter.

Note that if there is an early generation of a '\0' character, the bstring will be truncated to this end point.

Note that s format tokens correspond to '\0' terminated char * buffers, not bstrings. To print a bstring, first dereference data element of the the bstring:

b1->data needs to be '\0' terminated, so tagbstrings generated by blk2tbstr() might not be suitable.

bformata (b0 = bfromcstr ("Hello"), ", %s", b1->data);

bfromcstr()

bstring bfromcstr

(

const char *

str

)

Take a standard C library style '\0' terminated char buffer and generate a bstring with the same contents as the char buffer.

If an error occurs NULL is returned.

bstring b = bfromcstr("Hello");
if(!b) {
    fprintf(stderr, "Out of memory");
} else {
    puts((char *)b->data);
}

bfromcstralloc()

bstring bfromcstralloc	(	int	mlen,
		const char *	str )

Create a bstring which contains the contents of the '\0' terminated char *buffer str.

The memory buffer backing the bstring is at least mlen characters in length. If an error occurs NULL is returned.

bstring b = bfromcstralloc(64, someCstr);
if(b) {
    b->data[63] = 'x';
}

The idea is that this will set the 64th character of b to 'x' if it is at least 64 characters long otherwise do nothing. And we know this is well defined so long as b was successfully created, since it will have been allocated with at least 64 characters.

bgets()

bstring bgets	(	bNgetc	getcPtr,
		void *	parm,
		char	terminator )

Read a bstring from a stream.

As many bytes as is necessary are read until the terminator is consumed or no more characters are available from the stream. If read from the stream, the terminator character will be appended to the end of the returned bstring. The getcPtr function must have the same semantics as the fgetc C library function (i.e., returning an integer whose value is negative when there are no more characters available, otherwise the value of the next available unsigned character from the stream.) The intention is that parm would contain the stream data context/state required (similar to the role of the FILE* I/O stream parameter of fgets.) If no characters are read, or there is some other detectable error, NULL is returned.

bgets will never call the getcPtr function more often than necessary to construct its output (including a single call, if required, to determine that the stream contains no more characters.)

Abstracting the character stream function and terminator character allows for different stream devices and string formats other than '
' terminated lines in a file if desired (consider \032 terminated email messages, in a UNIX mailbox for example.)

For files, this function can be used analogously as fgets as follows:

fp = fopen( ... );
if (fp) b = bgets((bNgetc) fgetc, fp, '\n');

(Note that only one terminator character can be used, and that '\0' is not assumed to terminate the stream in addition to the terminator character. This is consistent with the semantics of fgets.)

bgetsa()

int bgetsa	(	bstring	b,
		bNgetc	getcPtr,
		void *	parm,
		char	terminator )

Read from a stream and concatenate to a bstring.

Behaves like bgets, except that it appends it results to the bstring b. The value 1 is returned if no characters are read before a negative result is returned from getcPtr. Otherwise BSTR_ERR is returned on error, and 0 is returned in other normal cases.

binchr()

int binchr	(	const bstring	b0,
		int	pos,
		const bstring	b1 )

Search for the first position in b0 starting from pos or after, in which one of the characters in b1 is found.

This function has an execution time of O(b0->slen + b1->slen). If such a position does not exist in b0, then BSTR_ERR is returned.

binchrCF()

int binchrCF ( const unsigned char * data, int len, int pos, const struct charField * cf )

static

binchrr()

int binchrr	(	const bstring	b0,
		int	pos,
		const bstring	b1 )

Search for the last position in b0 no greater than pos, in which one of the characters in b1 is found.

This function has an execution time of O(b0->slen + b1->slen). If such a position does not exist in b0, then BSTR_ERR is returned.

binchrrCF()

int binchrrCF ( const unsigned char * data, int pos, const struct charField * cf )

static

binsert()

int binsert	(	bstring	s1,
		int	pos,
		const bstring	s2,
		unsigned char	fill )

Inserts the bstring s2 into s1 at position pos.

If the position pos is past the end of s1, then the character "fill" is appended as necessary to make up the gap between the end of s1 and pos. The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

binsertch()

int binsertch	(	bstring	s1,
		int	pos,
		int	len,
		unsigned char	fill )

Inserts the character fill repeatedly into s1 at position pos for a length len.

If the position pos is past the end of s1, then the character "fill" is appended as necessary to make up the gap between the end of s1 and the position pos + len (exclusive). The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

binstr()

int binstr	(	const bstring	s1,
		int	pos,
		const bstring	s2 )

Search for the bstring s2 in s1 starting at position pos and looking in a forward (increasing) direction.

If it is found then it returns with the first position after pos where it is found, otherwise it returns BSTR_ERR. The algorithm used is brute force; O(m*n).

binstrcaseless()

int binstrcaseless	(	const bstring	s1,
		int	pos,
		const bstring	s2 )

Search for the bstring s2 in s1 starting at position pos and looking in a forward (increasing) direction but without regard to case.

If it is found then it returns with the first position after pos where it is found, otherwise it returns BSTR_ERR. The algorithm used is brute force; O(m*n).

binstrr()

int binstrr	(	const bstring	s1,
		int	pos,
		const bstring	s2 )

Search for the bstring s2 in s1 starting at position pos and looking in a backward (decreasing) direction.

If it is found then it returns with the first position after pos where it is found, otherwise return BSTR_ERR. Note that the current position at pos is tested as well – so to be disjoint from a previous forward search it is recommended that the position be backed up (decremented) by one position. The algorithm used is brute force; O(m*n).

binstrrcaseless()

int binstrrcaseless	(	const bstring	s1,
		int	pos,
		const bstring	s2 )

Search for the bstring s2 in s1 starting at position pos and looking in a backward (decreasing) direction but without regard to case.

If it is found then it returns with the first position after pos where it is found, otherwise return BSTR_ERR. Note that the current position at pos is tested as well – so to be disjoint from a previous forward search it is recommended that the position be backed up (decremented) by one position. The algorithm used is brute force; O(m*n).

biseq()

int biseq	(	const bstring	b0,
		const bstring	b1 )

Compare the bstring b0 and b1 for equality.

If the bstrings differ, 0 is returned, if the bstrings are the same, 1 is returned, if there is an error, -1 is returned. If the length of the bstrings are different, this function has O(1) complexity. Contained '\0' characters are not treated as a termination character.

Note that the semantics of biseq are not completely compatible with bstrcmp because of its different treatment of the '\0' character.

biseqcaseless()

int biseqcaseless	(	const bstring	b0,
		const bstring	b1 )

Compare two bstrings for equality without differentiating between case.

If the bstrings differ other than in case, 0 is returned, if the bstrings are the same, 1 is returned, if there is an error, -1 is returned. If the length of the bstrings are different, this function is O(1). '\0' termination characters are not treated in any special way.

biseqcstr()

int biseqcstr	(	const bstring	b,
		const char *	s )

Compare the bstring b and char * string s.

The C string s must be '\0' terminated at exactly the length of the bstring b, and the contents between the two must be identical with the bstring b with no '\0' characters for the two contents to be considered equal. This is equivalent to the condition that their current contents will be always be equal when comparing them in the same format after converting one or the other. If they are equal 1 is returned, if they are unequal 0 is returned and if there is a detectable error BSTR_ERR is returned.

biseqcstrcaseless()

int biseqcstrcaseless	(	const bstring	b,
		const char *	s )

Compare the bstring b and char * string s.

The C string s must be '\0' terminated at exactly the length of the bstring b, and the contents between the two must be identical except for case with the bstring b with no '\0' characters for the two contents to be considered equal. This is equivalent to the condition that their current contents will be always be equal ignoring case when comparing them in the same format after converting one or the other. If they are equal, except for case, 1 is returned, if they are unequal regardless of case 0 is returned and if there is a detectable error BSTR_ERR is returned.

bisstemeqblk()

int bisstemeqblk	(	const bstring	b0,
		const void *	blk,
		int	len )

Compare beginning of bstring b0 with a block of memory of length len for equality.

If the beginning of b0 differs from the memory block (or if b0 is too short), 0 is returned, if the bstrings are the same, 1 is returned, if there is an error, -1 is returned.

bisstemeqcaselessblk()

int bisstemeqcaselessblk	(	const bstring	b0,
		const void *	blk,
		int	len )

Compare beginning of bstring b0 with a block of memory of length len without differentiating between case for equality.

If the beginning of b0 differs from the memory block other than in case (or if b0 is too short), 0 is returned, if the bstrings are the same, 1 is returned, if there is an error, -1 is returned.

bjoin()

bstring bjoin	(	const struct bstrList *	bl,
		const bstring	sep )

Join the entries of a bstrList into one bstring by sequentially concatenating them with the sep bstring in between.

If sep is NULL, it is treated as if it were the empty bstring. Note that:

bjoin (l = bsplit (b, s->data[0]), s);

should result in a copy of b, if s->slen is 1. If there is an error NULL is returned, otherwise a bstring with the correct result is returned. See bstrListCreate() above for structure of struct bstrList.

blk2bstr()

bstring blk2bstr	(	const void *	blk,
		int	len )

Create a bstring whose contents are described by the contiguous buffer pointing to by blk with a length of len bytes.

Note that this function creates a copy of the data in blk, rather than simply referencing it. Compare with the blk2tbstr macro. If an error occurs NULL is returned.

bltrimws()

int bltrimws

(

bstring

b

)

Delete whitespace contiguous from the left end of the bstring.

This function will return with BSTR_ERR if b is NULL or of length 0, otherwise BSTR_OK is returned.

bmidstr()

bstring bmidstr	(	const bstring	b,
		int	left,
		int	len )

Create a bstring which is the substring of b starting from position left and running for a length len (clamped by the end of the bstring b).

If there was no error, the value of this constructed bstring is returned otherwise NULL is returned.

bninchr()

int bninchr	(	const bstring	b0,
		int	pos,
		const bstring	b1 )

Search for the first position in b0 starting from pos or after, in which none of the characters in b1 is found and return it.

This function has an execution time of O(b0->slen + b1->slen). If such a position does not exist in b0, then BSTR_ERR is returned.

bninchrr()

int bninchrr	(	const bstring	b0,
		int	pos,
		const bstring	b1 )

Search for the last position in b0 no greater than pos, in which none of the characters in b1 is found and return it.

This function has an execution time of O(b0->slen + b1->slen). If such a position does not exist in b0, then BSTR_ERR is returned.

bpattern()

int bpattern	(	bstring	b,
		int	len )

Replicate the starting bstring, b, end to end repeatedly until it surpasses len characters, then chop the result to exactly len characters.

This function operates in-place. This function will return with BSTR_ERR if b is NULL or of length 0, otherwise BSTR_OK is returned.

bread()

bstring bread	(	bNread	readPtr,
		void *	parm )

Read an entire stream into a bstring, verbatum.

The readPtr function pointer is compatible with fread sematics, except that it need not obtain the stream data from a file. The intention is that parm would contain the stream data context/state required (similar to the role of the FILE* I/O stream parameter of fread.)

Abstracting the block read function allows for block devices other than file streams to be read if desired. Note that there is an ANSI compatibility issue if "fread" is used directly; see the ANSI issues section below.

breada()

int breada	(	bstring	b,
		bNread	readPtr,
		void *	parm )

Read an entire stream and append it to a bstring, verbatim.

Behaves like bread, except that it appends it results to the bstring b. BSTR_ERR is returned on error, otherwise 0 is returned.

breplace()

int breplace	(	bstring	b1,
		int	pos,
		int	len,
		const bstring	b2,
		unsigned char	fill )

Replace a section of a bstring from pos for a length len with the bstring b2.

If the position pos is past the end of b1 then the character "fill" is appended as necessary to make up the gap between the end of b1 and pos.

brtrimws()

int brtrimws

(

bstring

b

)

Delete whitespace contiguous from the right end of the bstring.

This function will return with BSTR_ERR if b is NULL or of length 0, otherwise BSTR_OK is returned.

bsbufflength()

int bsbufflength	(	struct bStream *	s,
		int	sz )

Set the length of the buffer used by the bStream.

If sz is the macro BSTR_BS_BUFF_LENGTH_GET (which is 0), the length is not set. If s is NULL or sz is negative, the function will return with BSTR_ERR, otherwise this function returns with the previous length.

bscb()

int bscb ( void * parm, int ofs, int len )

static

bsclose()

void * bsclose

(

struct bStream *

s

)

Close the bStream, and return the handle to the stream that was originally used to open the given stream.

If s is NULL or detectably invalid, NULL will be returned.

bseof()

int bseof

(

const struct bStream *

s

)

Return the defacto "EOF" (end of file) state of a stream (1 if the bStream is in an EOF state, 0 if not, and BSTR_ERR if stream is closed or detectably erroneous).

When the readPtr callback returns a value <= 0 the stream reaches its "EOF" state. Note that bunread with non-empty content will essentially turn off this state, and the stream will not be in its "EOF" state so long as its possible to read more data out of it.

Also note that the semantics of bseof() are slightly different from something like feof(), i.e., reaching the end of the stream does not necessarily guarantee that bseof() will return with a value indicating that this has happened. bseof() will only return indicating that it has reached the "EOF" and an attempt has been made to read past the end of the bStream.

bsetstr()

int bsetstr	(	bstring	b0,
		int	pos,
		const bstring	b1,
		unsigned char	fill )

Overwrite the bstring b0 starting at position pos with the bstring b1.

If the position pos is past the end of b0, then the character "fill" is appended as necessary to make up the gap between the end of b0 and pos. If b1 is NULL, it behaves as if it were a 0-length bstring. The value BSTR_OK is returned if the operation is successful, otherwise BSTR_ERR is returned.

bsopen()

struct bStream * bsopen	(	bNread	readPtr,
		void *	parm )

Wrap a given open stream (described by a fread compatible function pointer and stream handle) into an open bStream suitable for the bstring library streaming functions.

bspeek()

int bspeek	(	bstring	r,
		const struct bStream *	s )

Return the number of currently buffered characters from the bStream that will be read prior to reads from the core stream, and append it to the the parameter r.

bsplit()

struct bstrList * bsplit	(	const bstring	str,
		unsigned char	splitChar )

Create an array of sequential substrings from str divided by the character splitChar.

Successive occurrences of the splitChar will be divided by empty bstring entries, following the semantics from the Python programming language. To reclaim the memory from this output structure, bstrListDestroy() should be called. See bstrListCreate() above for structure of struct bstrList.

bsplitcb()

int bsplitcb	(	const bstring	str,
		unsigned char	splitChar,
		int	pos,
		int(*	cb )(void *parm, int ofs, int len),
		void *	parm )

Iterate the set of disjoint sequential substrings over str starting at position pos divided by the character splitChar.

The parm passed to bsplitcb is passed on to cb. If the function cb returns a value < 0, then further iterating is halted and this value is returned by bsplitcb.

Note: Non-destructive modification of str from within the cb function while performing this split is not undefined. bsplitcb behaves in sequential lock step with calls to cb. I.e., after returning from a cb that return a non-negative integer, bsplitcb continues from the position 1 character after the last detected split character and it will halt immediately if the length of str falls below this point. However, if the cb function destroys str, then it must return with a negative value, otherwise bsplitcb will continue in an undefined manner.

This function is provided as an incremental alternative to bsplit that is abortable and which does not impose additional memory allocation.

bsplits()

struct bstrList * bsplits	(	const bstring	str,
		const bstring	splitStr )

Create an array of sequential substrings from str divided by any character contained in splitStr.

An empty splitStr causes a single entry bstrList containing a copy of str to be returned. See bstrListCreate() above for structure of struct bstrList.

bsplitscb()

int bsplitscb	(	const bstring	str,
		const bstring	splitStr,
		int	pos,
		int(*	cb )(void *parm, int ofs, int len),
		void *	parm )

Iterate the set of disjoint sequential substrings over str starting at position pos divided by any of the characters in splitStr.

An empty splitStr causes the whole str to be iterated once. The parm passed to bsplitcb is passed on to cb. If the function cb returns a value < 0, then further iterating is halted and this value is returned by bsplitcb.

Note: Non-destructive modification of str from within the cb function while performing this split is not undefined. bsplitscb behaves in sequential lock step with calls to cb. I.e., after returning from a cb that return a non-negative integer, bsplitscb continues from the position 1 character after the last detected split character and it will halt immediately if the length of str falls below this point. However, if the cb function destroys str, then it must return with a negative value, otherwise bsplitscb will continue in an undefined manner.

This function is provided as an incremental alternative to bsplits that is abortable and which does not impose additional memory allocation.

bsplitstr()

struct bstrList * bsplitstr	(	const bstring	str,
		const bstring	splitStr )

Create an array of sequential substrings from str divided by the entire substring splitStr.

An empty splitStr causes a single entry bstrList containing a copy of str to be returned. See bstrListCreate() above for structure of struct bstrList.

bsplitstrcb()

int bsplitstrcb	(	const bstring	str,
		const bstring	splitStr,
		int	pos,
		int(*	cb )(void *parm, int ofs, int len),
		void *	parm )

Iterate the set of disjoint sequential substrings over str starting at position pos divided by the entire substring splitStr.

An empty splitStr causes each character of str to be iterated. The parm passed to bsplitcb is passed on to cb. If the function cb returns a value < 0, then further iterating is halted and this value is returned by bsplitcb.

Note: Non-destructive modification of str from within the cb function while performing this split is not undefined. bsplitstrcb behaves in sequential lock step with calls to cb. I.e., after returning from a cb that return a non-negative integer, bsplitstrcb continues from the position 1 character after the last detected split character and it will halt immediately if the length of str falls below this point. However, if the cb function destroys str, then it must return with a negative value, otherwise bsplitscb will continue in an undefined manner.

This function is provided as an incremental alternative to bsplitstr that is abortable and which does not impose additional memory allocation.

bsread()

int bsread	(	bstring	b,
		struct bStream *	s,
		int	n )

Read a bstring of length n (or, if it is fewer, as many bytes as is remaining) from the bStream.

This function will read the minimum required number of additional characters from the core stream. When the stream is at the end of the file BSTR_ERR is returned, otherwise BSTR_OK is returned.

bsreada()

int bsreada	(	bstring	b,
		struct bStream *	s,
		int	n )

Read a bstring of length n (or, if it is fewer, as many bytes as is remaining) from the bStream and concatenate it to the parameter r.

This function will read the minimum required number of additional characters from the core stream. When the stream is at the end of the file BSTR_ERR is returned, otherwise BSTR_OK is returned.

bsreadln()

int bsreadln	(	bstring	b,
		struct bStream *	s,
		char	terminator )

Read a bstring terminated by the terminator character or the end of the stream from the bStream (s) and return it into the parameter r.

The matched terminator, if found, appears at the end of the line read. If the stream has been exhausted of all available data, before any can be read, BSTR_ERR is returned. This function may read additional characters into the stream buffer from the core stream that are not returned, but will be retained for subsequent read operations. When reading from high speed streams, this function can perform significantly faster than bgets.

bsreadlna()

int bsreadlna	(	bstring	b,
		struct bStream *	s,
		char	terminator )

Read a bstring terminated by the terminator character or the end of the stream from the bStream (s) and concatenate it to the parameter r.

The matched terminator, if found, appears at the end of the line read. If the stream has been exhausted of all available data, before any can be read, BSTR_ERR is returned. This function may read additional characters into the stream buffer from the core stream that are not returned, but will be retained for subsequent read operations. When reading from high speed streams, this function can perform significantly faster than bgets.

bsreadlns()

int bsreadlns	(	bstring	r,
		struct bStream *	s,
		const bstring	term )

Read a bstring terminated by any character in the terminators bstring or the end of the stream from the bStream (s) and return it into the parameter r.

This function may read additional characters from the core stream that are not returned, but will be retained for subsequent read operations.

bsreadlnsa()

int bsreadlnsa	(	bstring	r,
		struct bStream *	s,
		const bstring	term )

Read a bstring terminated by any character in the terminators bstring or the end of the stream from the bStream (s) and concatenate it to the parameter r.

If the stream has been exhausted of all available data, before any can be read, BSTR_ERR is returned. This function may read additional characters from the core stream that are not returned, but will be retained for subsequent read operations.

bssplitscb()

int bssplitscb	(	struct bStream *	s,
		const bstring	splitStr,
		int(*	cb )(void *parm, int ofs, const bstring entry),
		void *	parm )

Iterate the set of disjoint sequential substrings over the stream s divided by any character from the bstring splitStr.

The parm passed to bssplitscb is passed on to cb. If the function cb returns a value < 0, then further iterating is halted and this return value is returned by bssplitscb.

Note: At the point of calling the cb function, the bStream pointer is pointed exactly at the position right after having read the split character. The cb function can act on the stream by causing the bStream pointer to move, and bssplitscb will continue by starting the next split at the position of the pointer after the return from cb.

However, if the cb causes the bStream s to be destroyed then the cb must return with a negative value, otherwise bssplitscb will continue in an undefined manner.

This function is provided as way to incrementally parse through a file or other generic stream that in total size may otherwise exceed the practical or desired memory available. As with the other split callback based functions this is abortable and does not impose additional memory allocation.

bssplitstrcb()

int bssplitstrcb	(	struct bStream *	s,
		const bstring	splitStr,
		int(*	cb )(void *parm, int ofs, const bstring entry),
		void *	parm )

Iterate the set of disjoint sequential substrings over the stream s divided by the entire substring splitStr.

The parm passed to bssplitstrcb is passed on to cb. If the function cb returns a value < 0, then further iterating is halted and this return value is returned by bssplitstrcb.

Note: At the point of calling the cb function, the bStream pointer is pointed exactly at the position right after having read the split character. The cb function can act on the stream by causing the bStream pointer to move, and bssplitstrcb will continue by starting the next split at the position of the pointer after the return from cb.

However, if the cb causes the bStream s to be destroyed then the cb must return with a negative value, otherwise bssplitscb will continue in an undefined manner.

This function is provided as way to incrementally parse through a file or other generic stream that in total size may otherwise exceed the practical or desired memory available. As with the other split callback based functions this is abortable and does not impose additional memory allocation.

bstr2cstr()

char * bstr2cstr	(	const bstring	s,
		char	z )

Create a '\0' terminated char buffer which contains the contents of the bstring s, except that any contained '\0' characters are converted to the character in z.

This returned value should be freed with bcstrfree(), by the caller. If an error occurs NULL is returned.

bstrchrp()

int bstrchrp	(	const bstring	b,
		int	c,
		int	pos )

Search for the character c in b forwards from the position pos (inclusive).

Returns the position of the found character or BSTR_ERR if it is not found.

bstrcmp()

int bstrcmp	(	const bstring	b0,
		const bstring	b1 )

Compare the bstrings b0 and b1 for ordering.

If there is an error, SHRT_MIN is returned, otherwise a value less than or greater than zero, indicating that the bstring pointed to by b0 is lexicographically less than or greater than the bstring pointed to by b1 is returned. If the bstring lengths are unequal but the characters up until the length of the shorter are equal then a value less than, or greater than zero, indicating that the bstring pointed to by b0 is shorter or longer than the bstring pointed to by b1 is returned. 0 is returned if and only if the two bstrings are the same. If the length of the bstrings are different, this function is O(n). Like its standard C library counter part, the comparison does not proceed past any '\0' termination characters encountered.

The seemingly odd error return value, merely provides slightly more granularity than the undefined situation given in the C library function strcmp. The function otherwise behaves very much like strcmp().

Note that the semantics of bstrcmp are not completely compatible with biseq because of its different treatment of the '\0' termination character.

bstrcpy()

bstring bstrcpy

(

const bstring

b1

)

Make a copy of the passed in bstring.

The copied bstring is returned if there is no error, otherwise NULL is returned.

bstricmp()

int bstricmp	(	const bstring	b0,
		const bstring	b1 )

Compare two bstrings without differentiating between case.

The return value is the difference of the values of the characters where the two bstrings first differ, otherwise 0 is returned indicating that the bstrings are equal. If the lengths are different, then a difference from 0 is given, but if the first extra character is '\0', then it is taken to be the value UCHAR_MAX + 1.

bstrListAlloc()

int bstrListAlloc	(	struct bstrList *	sl,
		int	msz )

Ensure that there is memory for at least msz number of entries for the list.

bstrListAllocMin()

int bstrListAllocMin	(	struct bstrList *	sl,
		int	msz )

Try to allocate the minimum amount of memory for the list to include at least msz entries or sl->qty whichever is greater.

bstrListCreate()

struct bstrList * bstrListCreate

(

void

)

Create an empty struct bstrList.

The struct bstrList output structure is declared as follows:

struct bstrList {
    int qty, mlen;
    bstring *entry;
};

The entry field actually is an array with qty number entries. The mlen record counts the maximum number of bstring's for which there is memory in the entry record.

The Bstrlib API does NOT include a comprehensive set of functions for full management of struct bstrList in an abstracted way. The reason for this is because aliasing semantics of the list are best left to the user of this function, and performance varies wildly depending on the assumptions made.

bstrListDestroy()

int bstrListDestroy

(

struct bstrList *

sl

)

Destroy a struct bstrList structure that was returned by the bsplit function. Note that this will destroy each bstring in the ->entry array as well. See bstrListCreate() above for structure of struct bstrList.

bstrncmp()

int bstrncmp	(	const bstring	b0,
		const bstring	b1,
		int	n )

Compare the bstrings b0 and b1 for ordering for at most n characters.

If there is an error, SHRT_MIN is returned, otherwise a value is returned as if b0 and b1 were first truncated to at most n characters then bstrcmp was called with these new bstrings are paremeters. If the length of the bstrings are different, this function is O(n). Like its standard C library counter part, the comparison does not proceed past any '\0' termination characters encountered.

The seemingly odd error return value, merely provides slightly more granularity than the undefined situation given in the C library function strncmp. The function otherwise behaves very much like strncmp().

bstrnicmp()

int bstrnicmp	(	const bstring	b0,
		const bstring	b1,
		int	n )

Compare two bstrings without differentiating between case for at most n characters.

If the position where the two bstrings first differ is before the nth position, the return value is the difference of the values of the characters, otherwise 0 is returned. If the lengths are different and less than n characters, then a difference from 0 is given, but if the first extra character is '\0', then it is taken to be the value UCHAR_MAX + 1.

bstrrchrp()

int bstrrchrp	(	const bstring	b,
		int	c,
		int	pos )

Search for the character c in b backwards from the position pos in bstring (inclusive).

Returns the position of the found character or BSTR_ERR if it is not found.

bsunread()

int bsunread	(	struct bStream *	s,
		const bstring	b )

Insert a bstring into the bStream at the current position.

These characters will be read prior to those that actually come from the core stream.

btolower()

int btolower

(

bstring

b

)

Convert contents of bstring to lower case.

This function will return with BSTR_ERR if b is NULL or of length 0, otherwise BSTR_OK is returned.

btoupper()

int btoupper

(

bstring

b

)

Convert contents of bstring to upper case.

This function will return with BSTR_ERR if b is NULL or of length 0, otherwise BSTR_OK is returned.

btrimws()

int btrimws

(

bstring

b

)

Delete whitespace contiguous from both ends of the bstring.

This function will return with BSTR_ERR if b is NULL or of length 0, otherwise BSTR_OK is returned.

btrunc()

int btrunc	(	bstring	b,
		int	n )

Truncate the bstring to at most n characters.

This function will return with BSTR_ERR if b is not detected as a valid bstring or n is less than 0, otherwise BSTR_OK is returned.

buildCharField()

int buildCharField ( struct charField * cf, const bstring b )

static

bvcformata()

int bvcformata	(	bstring	b,
		int	count,
		const char *	fmt,
		va_list	arglist )

The bvcformata function formats data under control of the format control string fmt and attempts to append the result to b.

The fmt parameter is the same as that of the printf function. The variable argument list is replaced with arglist, which has been initialized by the va_start macro. The size of the output is upper bounded by count. If the required output exceeds count, the string b is not augmented with any contents and a value below BSTR_ERR is returned. If a value below -count is returned then it is recommended that the negative of this value be used as an update to the count in a subsequent pass. On other errors, such as running out of memory, parameter errors or numeric wrap around BSTR_ERR is returned. BSTR_OK is returned when the output is successfully generated and appended to b.

Note: There is no sanity checking of arglist, and this function is destructive of the contents of b from the b->slen point onward. If there is an early generation of a '\0' character, the bstring will be truncated to this end point.

Although this function is part of the external API for Bstrlib, the interface and semantics (length limitations, and unusual return codes) are fairly atypical. The real purpose for this function is to provide an engine for the bvformata macro.

findreplaceengine()

int findreplaceengine ( bstring b, const bstring find, const bstring repl, int pos, instr_fnptr instr )

static

invertCharField()

void invertCharField ( struct charField * cf )

static

snapUpSize()

int snapUpSize ( int i )

static

Compute the snapped size for a given requested size.

By snapping to powers of 2 like this, repeated reallocations are avoided.