netatalk 4.5.0
Free and Open Source Apple Filing Protocol (AFP) Server
Loading...
Searching...
No Matches
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 | bfromcstrrangealloc (int minl, int maxl, 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 | biseqcaselessblk (const bstring b, const void *blk, int len)
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 | biseqblk (const bstring b, const void *blk, int len)
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 | binsertblk (bstring b, int pos, const void *blk, int len, 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 | bjoinblk (const struct bstrList *bl, const void *blk, int len)
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))
c
size_t c
Definition dircache.c:257

## ◆ 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)
LONG_BITS_QTY
#define LONG_BITS_QTY
Definition bstrlib.c:1319
LONG_LOG_BITS_QTY
#define LONG_LOG_BITS_QTY
Definition bstrlib.c:1318
LONG_TYPE
#define LONG_TYPE
Definition bstrlib.c:1321

## ◆ 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);
balloc
int balloc(bstring b, int olen)
Definition bstrlib.c:97

is invalid, and should be implemented as:

int t;
if (BSTR_OK == balloc (b, t = (b->slen * 2))) {
b->slen = t;
}
BSTR_OK
#define BSTR_OK
Definition bstrlib.h:83

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';
}
ballocmin
int ballocmin(bstring b, int len)
Definition bstrlib.c:159

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);
bassignformat
int bassignformat(bstring b, const char *fmt,...)
Definition bstrlib.c:2952
bfromcstr
bstring bfromcstr(const char *str)
Definition bstrlib.c:188
b1
q_t * b1
Definition dircache.c:246

## ◆ 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);
bfindreplace
int bfindreplace(bstring b, const bstring find, const bstring repl, int pos)
Definition bstrlib.c:1830

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);
bfindreplacecaseless
int bfindreplacecaseless(bstring b, const bstring find, const bstring repl, int pos)
Definition bstrlib.c:1836

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);
bformat
bstring bformat(const char *fmt,...)
Definition bstrlib.c:3007

## ◆ 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);
bformata
int bformata(bstring b, const char *fmt,...)
Definition bstrlib.c:2897

## ◆ 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);
}
bstring
struct tagbstring * bstring
Definition bstrlib.h:86
tagbstring::data
unsigned char * data
Definition bstrlib.h:91

## ◆ 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';
}
bfromcstralloc
bstring bfromcstralloc(int mlen, const char *str)
Definition bstrlib.c:266

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.

## ◆ bfromcstrrangealloc()

bstring bfromcstrrangealloc | ( | int | minl,
|  | int | maxl,
|  | const char * | str )

Create a bstring which contains the contents of the '\0' terminated char* buffer str. The memory buffer backing the string is at least minl characters in length, but an attempt is made to allocate up to maxl 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');
bgets
bstring bgets(bNgetc getcPtr, void *parm, char terminator)
Definition bstrlib.c:2006
bNgetc
int(* bNgetc)(void *parm)
Definition bstrlib.h:1174

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

## ◆ binsertblk()

int binsertblk | ( | bstring | b,
|  | int | pos,
|  | const void * | blk,
|  | int | len,
|  | unsigned char | fill )

Inserts the block of characters at blk with length len into b at position pos.

If the position pos is past the end of b, then the character "fill" is appended as necessary to make up the gap between the end of b and pos. Unlike bsetstr, binsertblk does not allow blk to be NULL.

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

## ◆ biseqblk()

int biseqblk | ( | const bstring | b,
|  | const void * | blk,
|  | int | len )

Compare the bstring b with the character block blk of length len.

If the content differs, 0 is returned, if the content is the same, 1 is returned, if there is an error, -1 is returned. If the length of the strings are different, this function is O(1). '\0' characters are not treated in any special way.

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

## ◆ biseqcaselessblk()

int biseqcaselessblk | ( | const bstring | b,
|  | const void * | blk,
|  | int | len )

Compare content of b and the array of bytes in blk for length len for equality without differentiating between character case.

If the content differs other than in case, 0 is returned, if, ignoring case, the content is the same, 1 is returned, if there is an error, -1 is returned. If the length of the strings are different, this function is O(1). '\0' 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);
bsplit
struct bstrList * bsplit(const bstring str, unsigned char splitChar)
Definition bstrlib.c:2802
bjoin
bstring bjoin(const struct bstrList *bl, const bstring sep)
Definition bstrlib.c:2436

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.

## ◆ bjoinblk()

bstring bjoinblk | ( | const struct bstrList * | bl,
|  | const void * | blk,
|  | int | len )

Join the entries of a bstrList into one bstring by sequentially concatenating them with the content from blk for length len in between.

If there is an error NULL is returned, otherwise a bstring with the correct result is returned.

## ◆ 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;
};
bstrList
Definition bstrlib.h:778
bstrList::qty
int qty
Definition bstrlib.h:779
bstrList::mlen
int mlen
Definition bstrlib.h:779
entry
Definition ad_open.c:95

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.