Skip to content

Better String Library API Reference

Jump to bottom Edit New page
websnarf edited this page Mar 16, 2016 · 7 revisions

The core functions

The functions from '''bstrlib.c''' are the core functions and should be considered to be available by default in all uses of Bstrlib:

extern bstring bfromcstr (const char * str);
Take a standard C library style ''''\0'''' terminated '''char''' buffer and generate a '''bstring''' with the same contents. If an error occurs '''NULL''' is returned. For example: 
 bstring b = bfromcstr ("Hello");
 if (!b) {
     fprintf (stderr, "Out of memory");
 } else {
     puts ((char *) b->data);
 }
extern 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 and is at least large enough to hold the string with the ''''\0'''' terminator. If an error occurs '''NULL''' is returned. For example: 
 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. This is well defined so long as b was successfully created since it will have been allocated with at least 64 characters.
extern 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. The buffer is also at least large enough to hold the string with the ''''\0'''' terminator. If an error occurs '''NULL''' is returned. For example: 
 bstring b = bfromcstrrangealloc (0, 128, "Hello.");
 if (b) b->data[5] = '!';
The idea is that this will set the 6th character of b to ''''!'''' if it was allocated 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 7 ('''strlen("Hello.")''') characters.
extern 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. For example: 
 bstring b = blk2bstr (bsStaticBlkParms("Hello."));
The string '''"Hello."''' is turned into a blk, len parameter pair which is then turned into an allocated '''bstring'''.
extern 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.
extern 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 behavior from the standard library functions, then this allows a correct way of freeing the memory that allows higher level code to be independent from these macro redefinitions.
extern bstring bstrcpy (const_bstring b);
Make a copy of the passed in '''bstring''' b. The copied '''bstring''' is returned if there is no error, otherwise, '''NULL''' is returned.
extern 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.
extern int bassigncstr (bstring a, const char * str);
Overwrite the '''bstring''' 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.
extern int bassignblk (bstring a, const void * blk, int len);
Overwrite the '''bstring''' a with the contents of the block (blk, len). 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.
extern 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.
extern bstring bmidstr (const_bstring b, int left, int len);
Create a '''bstring''' which is the sub-string 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.
extern int bdelete (bstring b, int pos, int len);
Removes characters from pos to pos'''+'''len'''-1''' and shifts the tail of the '''bstring''' b 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.
extern int bconcat (bstring b1, const_bstring b2);
Concatenate the '''bstring''' b2 to the end of '''bstring''' b1. The value '''BSTR_OK''' is returned if the operation is successful, otherwise '''BSTR_ERR''' is returned and b2 is unchanged.
extern int bconchar (bstring b, 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.
extern 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.
extern int bcatblk (bstring b, const void * blk, int len);
Concatenate a fixed length buffer (blk, len) to the end of '''bstring''' b. The value '''BSTR_OK''' is returned if the operation is successful, otherwise '''BSTR_ERR''' is returned.
extern int biseq (const_bstring b1, const_bstring b2);
Compare the '''bstring''' b1 and b2 for equality. If the '''bstring''' differ, '''0''' is returned, if the '''bstring''' are the same, '''1''' is returned, if there is an error, '''-1''' is returned. If the length of the '''bstring'''s 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.
extern int bisstemeqblk (const_bstring b, const void * blk, int len);
Compare beginning of '''bstring''' b with a block of memory at blk of length len for equality. If the beginning of b differs from the memory block (or if b is too short), '''0''' is returned, if the '''bstring'''s are the same, '''1''' is returned, if there is an error, '''-1''' is returned.
extern int biseqcaseless (const_bstring b1, const_bstring b2);
Compare two '''bstring'''s for equality without differentiating between case. If the '''bstring'''s differ other than in case, '''0''' is returned, if the '''bstring'''s are the same, '''1''' is returned, if there is an error, '''-1''' is returned. If the length of the '''bstring'''s are different, this function is O(1). ''''\0'''' termination characters are not treated in any special way.
extern 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'''' termination characters are not treated in any special way.
extern int bisstemeqcaselessblk (const_bstring b, const void * blk, int len);
Compare beginning of '''bstring''' b with a block of memory, blk, of length len without differentiating between case for equality. If the beginning of b differs from the memory block other than in case (or if b is too short), '''0''' is returned, if the '''bstring'''s are the same, '''1''' is returned, if there is an error, '''-1''' is returned.
extern int biseqblk (const_bstring b, const void * blk, int len);
Compare the string 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.
extern 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.
extern 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.
extern int bstrcmp (const_bstring b1, const_bstring b2);
Compare the '''bstring'''s b1 and b2 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 b1 is lexicographically less than or greater than the '''bstring''' pointed to by b2 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 b1 is shorter or longer than the '''bstring''' pointed to by b2 is returned. '''0''' is returned if and only if the two '''bstring'''s are the same. If the length of the '''bstring'''s 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.
extern int bstrncmp (const_bstring b1, const_bstring b2, int n);
Compare the '''bstring'''s b1 and b2 for ordering for at most n characters. If there is an error, '''SHRT_MIN''' is returned, otherwise a value is returned as if b1 and b2 were first truncated to at most n characters then '''bstrcmp''' was called with these new '''bstring'''s are parameters. If the length of the '''bstring'''s 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()'''.
extern int bstricmp (const_bstring b1, const_bstring b2);
Compare two '''bstring'''s without differentiating between case. The return value is the difference of the values of the characters where the two '''bstring'''s first differ, otherwise '''0''' is returned indicating that the '''bstring'''s 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'''.
extern int bstrnicmp (const_bstring b1, const_bstring b2, int n);
Compare two '''bstring'''s without differentiating between case for at most n characters. If the position where the two '''bstring'''s 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'''.
extern 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. Note to C++ users: Passing in a '''CBString''' cast to a '''bstring''' will lead to undefined behavior ('''free''' will be called on the header, rather than the '''CBString''' destructor.) Instead just use the ordinary C++ language facilities to dealloc a '''CBString'''.
extern int binstr (const_bstring b1, int pos, const_bstring b2);
Search for the '''bstring''' b2 in b1 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 O(m*n) but there is an attempt to improve upon this in easy cases.
extern int binstrr (const_bstring b1, int pos, const_bstring b2);
Search for the '''bstring''' b2 in b1 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 O(m*n).
extern int binstrcaseless (const_bstring b1, int pos, const_bstring b2);
Search for the '''bstring''' b2 in b1 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 O(m*n).
extern int binstrrcaseless (const_bstring b1, int pos, const_bstring b2);
Search for the '''bstring''' b2 in b1 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 O(m*n).
extern int binchr (const_bstring b1, int pos, const_bstring b2);
Search for the first position in b1 starting from pos or after, in which one of the characters in b2 is found. This function has an execution time of O(b1->slen + b2->slen). If such a position does not exist in b1, then '''BSTR_ERR''' is returned.
extern int binchrr (const_bstring b1, int pos, const_bstring b2);
Search for the last position in b1 no greater than pos, in which one of the characters in b2 is found. This function has an execution time of O(b1->slen + b2->slen). If such a position does not exist in b1, then '''BSTR_ERR''' is returned.
extern int bninchr (const_bstring b1, int pos, const_bstring b2);
Search for the first position in b1 starting from pos or after, in which none of the characters in b2 is found and return it. This function has an execution time of O(b1->slen + b2->slen). If such a position does not exist in b1, then '''BSTR_ERR''' is returned.
extern int bninchrr (const_bstring b1, int pos, const_bstring b2);
Search for the last position in b1 no greater than pos, in which none of the characters in b2 is found and return it. This function has an execution time of O(b1->slen + b2->slen). If such a position does not exist in b1, then '''BSTR_ERR''' is returned.
extern 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.
extern 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.
extern int bsetstr (bstring b1, int pos, const_bstring b2, unsigned char fill);
Overwrite the '''bstring''' b1 starting at position pos 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. If b2 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.
extern int binsert (bstring b1, int pos, const_bstring b2, unsigned char fill);
Inserts the '''bstring''' b2 into b1 at position pos. 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. The value '''BSTR_OK''' is returned if the operation is successful, otherwise '''BSTR_ERR''' is returned.
extern 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''', '''binsert''' does not allow blk to be '''NULL'''.
extern int binsertch (bstring b, int pos, int len, unsigned char fill);
Inserts the character fill repeatedly into b at position pos for a length len. 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 the position pos + len (exclusive). The value '''BSTR_OK''' is returned if the operation is successful, otherwise '''BSTR_ERR''' is returned.
extern 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.
extern int bfindreplace (bstring b, const_bstring find, const_bstring replace, int pos);
Replace all occurrences of the find substring in b with replace after the position pos. 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 - pos) '''bstring''' comparisons, and data movement is bounded above by character volume equivalent to size of the output '''bstring'''.
extern int bfindreplacecaseless (bstring b, const_bstring find, const_bstring replace, int pos);
Replace all occurrences of the find substring in b, ignoring case, with replace after a given position pos. 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 - pos) '''bstring''' comparisons, and data movement is bounded above by character volume equivalent to size of the output '''bstring'''.
extern int balloc (bstring b, int length);
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 Bstrlib 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; /* ?? Most likely incorrect */
 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;
'''balloc''' will return with '''BSTR_ERR''' if b is not detected as a valid '''bstring''' or if its length is not greater than 0, otherwise '''BSTR_OK''' is returned.
extern int ballocmin (bstring b, int len);
Change the amount of memory backing the '''bstring''' b to at least len. 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. 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 successful since it will ensure that b has been allocated with at least 64 characters.
extern 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.
extern 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.
extern 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.
extern 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.
extern int bltrimws (bstring b);
Delete contiguous white space from the left end of b. This function will return with '''BSTR_ERR''' if b is '''NULL''' or of length 0, otherwise '''BSTR_OK''' is returned.
extern int brtrimws (bstring b);
Delete contiguous white space from the right end of b. This function will return with '''BSTR_ERR''' if b is '''NULL''' or of length 0, otherwise '''BSTR_OK''' is returned.
extern int btrimws (bstring b);
Delete contiguous white space from both ends of b. This function will return with '''BSTR_ERR''' if b is '''NULL''' or of length 0, otherwise '''BSTR_OK''' is returned.
extern 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. For a complete list of '''bstring''' data type it is recommended that the C++ public '''std::vector<CBString>''' be used, since its semantics are usage are more standard.
extern 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'''.
extern int bstrListAlloc (struct bstrList * sl, int msz);
Ensure that there is memory for at least msz number of entries for the list sl.
extern 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.
extern struct bstrList * bsplit (bstring str, unsigned char splitChar);
Create an array of sequential sub-strings from str divided by the character splitChar. Successive occurrences of the splitChar will be divided by empty '''bstring''' entries, following the semantics of the Python programming language. To reclaim the memory from this output structure, '''bstrListDestroy()''' should be called. See '''bstrListCreate()''' above for structure of '''struct bstrList'''.
extern struct bstrList * bsplits (bstring str, const_bstring splitStr);
Create an array of sequential sub-strings 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 the structure of '''struct bstrList'''.
extern struct bstrList * bsplitstr (bstring str, const_bstring splitStr);
Create an array of sequential sub-strings from str divided by the entire sub-string splitStr. An empty splitStr causes a single entry '''bstrList''' containing a copy of str to be returned. See '''bstrListCreate()''' above for the structure of '''struct bstrList'''.
extern bstring bjoin (const struct bstrList * bl, const_bstring sep);
Join the entries of bl into one '''bstring''' by sequentially concatenating them with sep 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 return 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'''.
extern bstring bjoinblk (const struct bstrList * bl, 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.
extern 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 sub-strings 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 returns 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 allocations.
extern 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 sub-strings 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 '''bsplitscb''' is passed on to cb. If the function cb returns a value < 0, then further iterating is halted and this value is returned by '''bsplitscb'''. 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 allocations.
extern 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 sub-strings of str starting at position pos divided by the entire sub-string splitStr. An empty splitStr causes each character of str to be iterated. The parm passed to '''bsplitstrcb''' is passed on to cb. If the function cb returns a value < 0, then further iterating is halted and this value is returned by '''bsplitstrcb'''. 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 '''bsplitstrcb''' 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.
extern 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 '''bstring'''s. To print a '''bstring''', first dereference data element of the '''bstring''': 
 /* b1->data needs to be '\0' terminated, so tagbstrings
    generated by blk2tbstr () might not be suitable. */
 b0 = bformat ("Hello, %s", b1->data);
Note that if the '''BSTRLIB_NOVSNP''' macro has been set when Bstrlib has been compiled the '''bformat''' function is not present.
extern 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 '''bstring'''s. To print a '''bstring''', first dereference data element of 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);
Note that if the '''BSTRLIB_NOVSNP''' macro has been set when Bstrlib has been compiled the '''bformata''' function is not present.
extern 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 '''bstring'''s. To print a '''bstring''', first dereference data element of 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);
Note that if the '''BSTRLIB_NOVSNP''' macro has been set when Bstrlib has been compiled the '''bassignformat''' function is not present.
extern 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. Note that if the '''BSTRLIB_NOVSNP''' macro has been set when Bstrlib has been compiled the '''bvcformata''' function is not present.
extern bstring bread (bNread readPtr, void * parm);
Read an entire stream into a '''bstring''', verbatim. The readPtr function pointer is compatible with '''fread()''' semantics, 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.) '''bNread '''is defined as follows: 
     typedef size_t (* bNread) (void *buff, size_t elsize, 
                                size_t nelem, void *parm);
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.
extern 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 b. '''BSTR_ERR''' is returned on error, otherwise '''0''' is returned.
extern 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()''' standard 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. '''bNgetc''' is defined as: 
     typedef int (* bNgetc) (void * parm);
'''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 ''''\n'''' 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 is 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'''.
extern 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 its result 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.
extern int bassigngets (bstring b, bNgetc getcPtr, void * parm, char terminator);
Read from a stream and overwrite a '''bstring'''. Behaves like '''bgets()''', except that it overwrites the contents of b with the results. 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.
extern struct bStream * bsopen (bNread readPtr, void * parm);
Creates a '''bStream''' which wraps a given open stream (described by a '''fread''' compatible function pointer and stream handle). This makes a stream usable by various Bstrlib streaming functions.
extern 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.
extern 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.
extern int bsreadln (bstring r, struct bStream * s, char terminator);
Read a block of data terminated by the terminator character or the end of the stream from the '''bStream''' s and return the data into the '''bstring''' r. The matched terminator, if found, appears at the end of 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 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()'''.
extern int bsreadlna (bstring r, struct bStream * s, char terminator);
Read a block of data terminated by the terminator character or the end of the stream from the '''bStream''' s and appends the data to end of the '''bstring''' r. The matched terminator, if found, appears at the end of 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 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()'''.
extern int bsreadlns (bstring r, struct bStream * s, bstring terminators);
Read a block of data terminated by any character in the terminators '''bstring''' or the end of the stream from the '''bStream''' s and return the data into the '''bstring''' 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 into the stream buffer from the core stream that are not returned, but will be retained for subsequent read operations.
extern int bsreadlnsa (bstring r, struct bStream * s, bstring terminators);
Read a block of data terminated by any character in the terminators '''bstring''' or the end of the stream from the '''bStream''' s and appends the data to end of the '''bstring''' 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 into the stream buffer from the core stream that are not returned, but will be retained for subsequent read operations.
extern int bsread (bstring r, struct bStream * s, int n);
Read a block of data of length n (or, if it is fewer, as many bytes as is remaining) from the '''bStream''' s and copy it to the '''bstring''' 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.
extern int bsreada (bstring r, 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''' s. 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.
extern int bsunread (struct bStream * s, const_bstring b);
Insert the '''bstring''' b into the '''bStream''' s at the current position. These characters will be read prior to those that actually come from the core stream.
extern int bspeek (bstring r, const struct bStream * s);
Return the number of currently buffered characters from the '''bStream''' s that will be read prior to reads from the core stream, and append it to the parameter r.
extern 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 sub-strings 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 a 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.
extern 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 sub-strings over the stream s divided by the entire sub-string 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 a 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.
extern int bseof (const struct bStream * s);
Return the de facto "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 it is 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" if an attempt has been made to read past the end of the '''bStream'''.

The Macros

The macros described below are shown in a prototype form indicating their intended usage. Note that the parameters passed to these macros will be referenced multiple times. As with all macros, programmer care is required to guard against unintended side effects.

int bstrchr (const_bstring b, int c);
Search for the character c in the '''bstring''' b forwards from the start. Returns the position of the found character or '''BSTR_ERR''' if it is not found. This has been implemented as a macro on top of '''bstrchrp()'''.
int bstrrchr (const_bstring b, int c);
Search for the character c in the '''bstring''' b backwards from the end. Returns the position of the found character or '''BSTR_ERR''' if it is not found. This has been implemented as a macro on top of '''bstrrchrp()'''.
int blengthe (const_bstring b, int err);
Returns the length of b. If b is '''NULL''', err is returned.
int blength (const_bstring b);
Returns the length of b. If b is '''NULL''', '''0''' is returned.
int bchare (const_bstring b, int p, int c);
Returns the pth character of the '''bstring''' b. If the position p refers to a position that does not exist in b or it is '''NULL''', then c is returned.
int bchar (const_bstring b, int p);
Returns the pth character of the '''bstring''' b. If the position p refers to a position that does not exist in b or it is '''NULL''', then ''''\0'''' is returned.
char * bdatae (bstring b, char * err);
Returns the '''char *''' data portion of b. If b is '''NULL''', err is returned.
char * bdata (bstring b);
Returns the '''char *''' data portion of b. If b is '''NULL''', '''NULL''' is returned.
char * bdataofse (bstring b, int ofs, char * err);
Returns the '''char *''' data portion of the '''bstring''' b offset by ofs. If b is '''NULL''', err is returned.
char * bdataofs (bstring b, int ofs);
Returns the '''char *''' data portion of the '''bstring''' b offset by ofs. If b is '''NULL''', '''NULL''' is returned.
struct tagbstring var = bsStatic ("...");
The '''bsStatic''' macro allows for static declarations of literal string constants as '''struct tagbstring '''structures. The resulting '''tagbstring''' does not need to be freed or destroyed. Note that this macro is only well defined for string literal arguments. For more general string pointers, use the '''btfromcstr''' macro. The resulting '''struct tagbstring''' is permanently write protected. Attempts to write to this '''struct tagbstring''' from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Invoking the '''bwriteallow''' macro onto this '''struct tagbstring''' has no effect.
<void * blk, int len> <= bsStaticBlkParms ("...")
The '''bsStaticBlkParms''' macro emits a pair of comma separated parameters corresponding to the block parameters for the block functions in Bstrlib (i.e., '''blk2bstr''', '''bcatblk''', '''blk2tbstr''', '''bisstemeqblk''', '''bisstemeqcaselessblk'''.) Note that this macro is only well defined for string literal arguments. Examples: 
     bstring b = blk2bstr (bsStaticBlkParms ("Fast init. "));
     bcatblk (b, bsStaticBlkParms ("Fast concatenation."));
These are faster than using '''bfromcstr()''' and '''bcatcstr()''' respectively because the length of the inline string is known as a compile time constant. Also note that separate '''struct tagbstring''' declarations for holding the output of a '''bsStatic()''' macro are not required.
void btfromcstr (struct tagbstring& t, const char * s);
Fill in the '''tagbstring''' t with the ''''\0'''' terminated char buffer s. This action is purely reference oriented; no memory management is done. The data member is just assigned s, and '''slen''' is assigned the strlen of s. The s parameter is accessed exactly once in this macro. The resulting struct tagbstring is initially write protected. Attempts to write to this struct tagbstring in a write protected state from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Invoke the '''bwriteallow''' on this struct tagbstring to make it writable (though this requires that s be obtained from a function compatible with malloc.)
void btfromblk (struct tagbstring& t, void * s, int len);
Fill in the '''tagbstring''' t with the data buffer s with length len. This action is purely reference oriented; no memory management is done. The '''data''' member of t is just assigned s, and '''slen''' is assigned len. Note that the buffer is not appended with a ''''\0'''' character. The s and len parameters are accessed exactly once each in this macro. The resulting '''struct tagbstring''' is initially write protected. Attempts to write to this '''struct tagbstring''' in a write protected state from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Invoke the '''bwriteallow''' on this '''struct tagbstring''' to make it writable (though this requires that s be obtained from a function compatible with '''malloc()'''.)
void btfromblkltrimws (struct tagbstring& t, void * s, int len);
Fill in the '''struct tagbstring''' t with the data buffer s with length len after it has been left trimmed. This action is purely reference oriented; no memory management is done. The '''data''' member of t is just assigned to a pointer inside the buffer s. Note that the buffer is not appended with a ''''\0'''' character. The s and len parameters are accessed exactly once each in this macro. The resulting '''struct tagbstring''' is permanently write protected. Attempts to write to this '''struct tagbstring''' from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Invoking the '''bwriteallow''' macro onto this '''struct tagbstring''' has no effect.
void btfromblkrtrimws (struct tagbstring& t, void * s, int len);
Fill in the '''struct tagbstring''' t with the '''data''' buffer s with length len after it has been right trimmed. This action is purely reference oriented; no memory management is done. The '''data''' member of t is just assigned to a pointer inside the buffer s. Note that the buffer is not appended with a ''''\0'''' character. The s and len parameters are accessed exactly once each in this macro. The resulting '''struct tagbstring''' is permanently write protected. Attempts to write to this '''struct tagbstring''' from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Invoking the '''bwriteallow''' macro onto this '''struct tagbstring''' has no effect.
void btfromblktrimws (struct tagbstring& t, void * s, int len);
Fill in the '''struct tagbstring''' t with the '''data''' buffer s with length len after it has been left and right trimmed. This action is purely reference oriented; no memory management is done. The data member of t is just assigned to a pointer inside the buffer s. Note that the buffer is not appended with a ''''\0'''' character. The s and len parameters are accessed exactly once each in this macro. The resulting '''struct tagbstring''' is permanently write protected. Attempts to write to this '''struct tagbstring''' from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Invoking the '''bwriteallow''' macro onto this '''struct tagbstring''' has no effect.
void bmid2tbstr (struct tagbstring& t, bstring b, int pos, int len);
Fill the '''struct tagbstring''' t with the sub-string from b, starting from position pos with a length len. The segment is clamped by the boundaries of the '''bstring''' b. This action is purely reference oriented; no memory management is done. Note that the buffer is not appended with a ''''\0'''' character. Note that the t parameter to this macro may be accessed multiple times. Note that the contents of t will become undefined if the contents of b change or are destroyed. The resulting '''struct tagbstring''' is permanently write protected. Attempts to write to this '''struct tagbstring''' in a write protected state from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Invoking the '''bwriteallow''' macro on this '''struct tagbstring''' will have no effect.
bstring bfromStatic ("...");
Allocate a bstring with the contents of a string literal. Returns NULL if an error has occurred (ran out of memory). The string literal parameter is enforced as literal at compile time.
int bcatStatic (bstring b, "...");
Append a string literal to '''bstring''' b. Returns '''0''' if successful, or '''BSTR_ERR''' if some error has occurred. The string literal parameter is enforced as literal at compile time.
int binsertStatic (bstring b, int pos, "...", char fill);
Inserts the string literal 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. The value '''BSTR_OK''' is returned if the operation is successful, otherwise '''BSTR_ERR''' is returned.
int bassignStatic (bstring b, "...");
Assign the contents of a string literal to the '''bstring''' b. The string literal parameter is enforced as literal at compile time.
int biseqStatic (const_bstring b, "...");
Compare the string b with the string literal. 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.
int biseqcaselessStatic (const_bstring b, "...");
Compare content of b and the string literal 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.
int bisstemeqStatic (bstring b, "...");
Compare beginning of '''bstring''' b with a string literal for equality. If the beginning of b differs from the string literal (or if b is too short), '''0''' is returned, if the beginning of b is equal to string literal, '''1''' is returned, if there is an error, '''-1''' is returned. The string literal parameter is enforced as literal at compile time.
int bisstemeqcaselessStatic (bstring b, "...");
Compare beginning of '''bstring''' b with a string literal without differentiating between case for equality. If the beginning of b differs from the string literal (or if b is too short), '''0''' is returned, if the beginning of b is equal to string literal, ignoring case, '''1''' is returned, if there is an error, '''-1''' is returned. The string literal parameter is enforced as literal at compile time.
bstring bjoinStatic (const struct bstrList * bl, "...");
Join the entries of the '''struct bstrList''' bl into one '''bstring''' by sequentially concatenating them with the string literal parameter in between. 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'''.
void bvformata (int& ret, bstring b, const char * format, lastarg);
Append the '''bstring''' b with '''printf()''' like formatting with the format control string, and the arguments taken from the '''...''' list of arguments after lastarg passed to the containing function. If the containing function does not have '''...''' parameters or lastarg is not the last named parameter before the '''...''' then the results are undefined. If successful, the results are appended to b and '''BSTR_OK''' is assigned to ret. Otherwise '''BSTR_ERR''' is assigned to ret. Example: 
     void dbgerror (FILE * fp, const char * fmt, ...) {
         int ret;
         bstring b;
         bvformata (ret, b = bfromcstr ("DBG: "), fmt, fmt);
         if (BSTR_OK == ret) fputs (bdata (b), fp);
         bdestroy (b);
     }
Note that if the '''BSTRLIB_NOVSNP''' macro was set when Bstrlib had been compiled the '''bvformata''' macro will not link properly. If the '''BSTRLIB_NOVSNP''' macro has been set, the '''bvformata''' macro will not be available.
void bwriteprotect (struct tagbstring& t);
Disallow '''bstring''' from being written to via the Bstrlib API. Attempts to write to the resulting tagbstring from any Bstrlib function will lead to '''BSTR_ERR''' being returned. Note: '''bstring'''s which are write protected cannot be destroyed via '''bdestroy'''. Note to C++ users: Setting a '''CBString''' as write protected will not prevent it from being destroyed by the destructor.
void bwriteallow (struct tagbstring& t);
Allow '''bstring''' to be written to via the Bstrlib API. Note that such an action makes the '''bstring''' both writable and destroyable. If the '''bstring''' is not legitimately writable (as is the case for '''struct tagbstrings''' initialized with a '''bsStatic''' value), the results of this are undefined. Note that invoking the '''bwriteallow''' macro may increase the number of '''realloc'''s by one more than necessary for every call to '''bwriteallow''' interleaved with any Bstrlib function which writes to this '''bstring'''.
int biswriteprotected (struct tagbstring& t);
Returns '''1''' if the '''bstring''' is write protected, otherwise '''0''' is returned.

Unicode functions

The two modules '''utf8util.c''' and '''buniutil.c''' implement basic functions for parsing and collecting Unicode data in the UTF8 format. Unicode is described by a sequence of "code points" which are values between 0 and 1114111 inclusive mapped to symbol content corresponding to nearly all the standardized scripts of the world.

The semantics of Unicode code points is varied and complicated. The base support of the better string library does not attempt to perform any interpretation of these code points. The better string library solely provides support for iterating through Unicode code points, appending and extracting code points to and from '''bstring'''s, and parsing UTF8 and UTF16 from raw data.

The types '''cpUcs4''' and '''cpUcs2''' respectively are defined as 4 byte and 2 byte encoding formats corresponding to UCS4 and UCS2 respectively. To test if a raw code point is valid, the macro '''isLegalUnicodeCodePoint()''' has been defined. The utf8 iterator is defined by '''struct utf8Iterator'''. To test if the iterator has more code points to walk through the macro '''utf8IteratorNoMore()''' has been defined.

To use these functions compile and link '''utf8util.c''' and '''buniutil.c''' to your application.

extern void utf8IteratorInit (struct utf8Iterator* iter, unsigned char* data, int slen);
Initialize a Unicode utf8 iterator to traverse an array of utf8 encoded code points pointed to by data, with length slen from the start. The iterator iter is only valid for as long as the array it is pointed to is valid and not modified.
extern void utf8IteratorUninit (struct utf8Iterator* iter);
Invalidate utf8 iterator. After calling this the iterator, iter should yield false when passed to the '''utf8IteratorNoMore()''' macro.
extern cpUcs4 utf8IteratorGetNextCodePoint (struct utf8Iterator* iter, cpUcs4 errCh);
Parse code point the iterator is pointing at and advance the iterator to the next code point. If the iterator was pointing at a valid code point the code point is returned, otherwise, errCh will be returned.
extern cpUcs4 utf8IteratorGetCurrCodePoint (struct utf8Iterator* iter, cpUcs4 errCh);
Parse code point the iterator is pointing at. If the iterator was pointing at a valid code point the code point is returned, otherwise, errCh will be returned.
extern int utf8ScanBackwardsForCodePoint (unsigned char* msg, int len, int pos, cpUcs4* out);
From the position pos in the array msg of length len, search for the last position before or at pos where from which a valid Unicode code point can be parsed. If such an offset is found it is returned otherwise a negative value is returned. The code point parsed is put into '''*'''out if it is not '''NULL'''.
extern int buIsUTF8Content (const_bstring bu);
Scan a '''bstring''' and determine if it is made entirely of Unicode code valid points. If it is, '''1''' is returned, otherwise '''0''' is returned.
extern int buAppendBlkUcs4 (bstring b, const cpUcs4* bu, int len, cpUcs4 errCh);
Append the code points passed in the UCS4 format (raw numbers) in the array bu of length len. Any unparsable characters are replaced by errCh. If errCh is not a valid Unicode code point, then parsing errors will cause '''BSTR_ERR''' to be returned.
extern int buGetBlkUTF16 (cpUcs2* ucs2, int len, cpUcs4 errCh, const_bstring bu, int pos);
Convert a string of UTF8 code points, bu, skipping the first pos, into a sequence of UTF16 encoded code points. Returns the number of UCS2 16-bit words written to the output. No more than len words are written to the target array ucs2. If any code point in bu is unparsable, it will be translated to errCh.
extern int buAppendBlkUTF16 (bstring bu, const cpUcs2* utf16, int len, cpUcs2* bom, cpUcs4 errCh);
Append an array of UCS2 code points (utf16) to UTF8 code points, bu. Any invalid code point is replaced by errCh. If errCh is itself not a valid code point, then this translation will halt upon the first error and return '''BSTR_ERR'''. Otherwise '''BSTR_OK''' is returned. If a byte order mark has been previously read, it may be passed in as bom, otherwise if '''*'''bom is set to '''0''', it will be filled in with the BOM as read from the first character if it is a BOM.

The Better String Library

Download GIT src

Download GIT zip

Download Examples

Docs Documentation

Docs Security

Docs Porting

Docs FAQ

Docs Comparison

Docs Licenses: [BSD] (https://raw.githubusercontent.com/websnarf/bstrlib/master/LICENSE) GPL

Docs Forum

Docs Email Paul Hsieh

Clone this wiki locally