diff --git a/LICENSE b/LICENSE
index 4c1ebdd15901f1ea589084b5e2a402a7de977042_TElDRU5TRQ==..8a73323cd97be1d11993d1a750b8f996af4daffe_TElDRU5TRQ== 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2014, websnarf
+Copyright (c) 2014, Paul Hsieh
All rights reserved.
Redistribution and use in source and binary forms, with or without
diff --git a/README.md b/README.md
index 4c1ebdd15901f1ea589084b5e2a402a7de977042_UkVBRE1FLm1k..8a73323cd97be1d11993d1a750b8f996af4daffe_UkVBRE1FLm1k 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
The Better String Library
-The Better String Library is an abstraction of a string data type which is superior to the C library char buffer
-string type, or C++'s std::string. Among the features achieved are:
+The Better String Library is an abstraction of a string data type which is
+superior to the C library char buffer string type, or C++'s std::string.
+Among the features achieved are:
@@ -5,5 +6,6 @@
- Substantial mitigation of buffer overflow/overrun problems and other failures that result from erroneous usage
- of the common C string library functions
+ Substantial mitigation of buffer overflow/overrun problems and other
+ failures that result from erroneous usage of the common C string
+ library functions
Significantly simplified string manipulation
@@ -8,6 +10,7 @@
Significantly simplified string manipulation
-
- High performance interoperability with other source/libraries which expect '\0' terminated char buffers
-
+
+ High performance interoperability with other source/libraries which
+ expect '\0' terminated char buffers
+
Improved overall performance of common string operations
@@ -13,4 +16,4 @@
Improved overall performance of common string operations
-
+
Functional equivalency with other more modern languages
@@ -15,8 +18,10 @@
Functional equivalency with other more modern languages
-The library is totally stand alone, portable (known to work with gcc/g++, MSVC++, Intel C++, WATCOM C/C++, Turbo C,
-Borland C++, IBM's native CC compiler on Windows, Linux and Mac OS X), high performance, easy to use and is not part
-of some other collection of data structures. Even the file I/O functions are totally abstracted (so that other
-stream-like mechanisms, like sockets, can be used.) Nevertheless, it is adequate as a complete replacement of the C
-string library for string manipulation in any C program.
+The library is totally stand alone, portable (known to work with gcc/g++,
+MSVC++, Intel C++, WATCOM C/C++, Turbo C, Borland C++, IBM's native CC
+compiler on Windows, Linux and Mac OS X), high performance, easy to use and
+is not part of some other collection of data structures. Even the file I/O
+functions are totally abstracted (so that other stream-like mechanisms, like
+sockets, can be used.) Nevertheless, it is adequate as a complete
+replacement of the C string library for string manipulation in any C program.
@@ -22,5 +27,6 @@
-The library includes a robust C++ wrapper that uses overloaded operators, rich constructors, exceptions, stream I/O
-and STL to make the CBString struct a natural and powerful string abstraction with more functionality and higher
-performance than std::string.
+The library includes a robust C++ wrapper that uses overloaded operators,
+rich constructors, exceptions, stream I/O and STL to make the CBString
+struct a natural and powerful string abstraction with more functionality and
+higher performance than std::string.
@@ -26,2 +32,3 @@
-Bstrlib is stable, well tested and suitable for any software production environment.
+Bstrlib is stable, well tested and suitable for any software production
+environment.
diff --git a/bsafe.c b/bsafe.c
index 4c1ebdd15901f1ea589084b5e2a402a7de977042_YnNhZmUuYw==..8a73323cd97be1d11993d1a750b8f996af4daffe_YnNhZmUuYw== 100644
--- a/bsafe.c
+++ b/bsafe.c
@@ -24,11 +24,11 @@
char * strcat (char *dst, const char *src);
char * strcpy (char *dst, const char *src) {
- dst = dst;
- src = src;
+ (void) dst;
+ (void) src;
fprintf (stderr, "bsafe error: strcpy() is not safe, use bstrcpy instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * strcat (char *dst, const char *src) {
@@ -29,11 +29,11 @@
fprintf (stderr, "bsafe error: strcpy() is not safe, use bstrcpy instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * strcat (char *dst, const char *src) {
- dst = dst;
- src = src;
+ (void) dst;
+ (void) src;
fprintf (stderr, "bsafe error: strcat() is not safe, use bstrcat instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
@@ -41,7 +41,7 @@
#if !defined (__GNUC__) && (!defined(_MSC_VER) || (_MSC_VER <= 1310))
char * (gets) (char * buf) {
- buf = buf;
+ (void) buf;
fprintf (stderr, "bsafe error: gets() is not safe, use bgets.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
@@ -49,12 +49,12 @@
#endif
char * (strncpy) (char *dst, const char *src, size_t n) {
- dst = dst;
- src = src;
- n = n;
+ (void) dst;
+ (void) src;
+ (void) n;
fprintf (stderr, "bsafe error: strncpy() is not safe, use bmidstr instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * (strncat) (char *dst, const char *src, size_t n) {
@@ -55,15 +55,15 @@
fprintf (stderr, "bsafe error: strncpy() is not safe, use bmidstr instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * (strncat) (char *dst, const char *src, size_t n) {
- dst = dst;
- src = src;
- n = n;
+ (void) dst;
+ (void) src;
+ (void) n;
fprintf (stderr, "bsafe error: strncat() is not safe, use bstrcat then btrunc\n\tor cstr2tbstr, btrunc then bstrcat instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * (strtok) (char *s1, const char *s2) {
@@ -64,14 +64,14 @@
fprintf (stderr, "bsafe error: strncat() is not safe, use bstrcat then btrunc\n\tor cstr2tbstr, btrunc then bstrcat instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * (strtok) (char *s1, const char *s2) {
- s1 = s1;
- s2 = s2;
+ (void) s1;
+ (void) s2;
fprintf (stderr, "bsafe error: strtok() is not safe, use bsplit or bsplits instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * (strdup) (const char *s) {
@@ -72,10 +72,10 @@
fprintf (stderr, "bsafe error: strtok() is not safe, use bsplit or bsplits instead.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
}
char * (strdup) (const char *s) {
- s = s;
+ (void) s;
fprintf (stderr, "bsafe error: strdup() is not safe, use bstrcpy.\n");
if (bsafeShouldExit) exit (-1);
return NULL;
diff --git a/bstrlib.txt b/bstrlib.txt
index 4c1ebdd15901f1ea589084b5e2a402a7de977042_YnN0cmxpYi50eHQ=..8a73323cd97be1d11993d1a750b8f996af4daffe_YnN0cmxpYi50eHQ= 100644
--- a/bstrlib.txt
+++ b/bstrlib.txt
@@ -3,9 +3,9 @@
by Paul Hsieh
-The bstring library is an attempt to provide improved string processing
-functionality to the C and C++ language. At the heart of the bstring library
-(Bstrlib for short) is the management of "bstring"s which are a significant
+The bstring library is an attempt to provide improved string processing
+functionality to the C and C++ language. At the heart of the bstring library
+(Bstrlib for short) is the management of "bstring"s which are a significant
improvement over '\0' terminated char buffers.
===============================================================================
@@ -15,7 +15,7 @@
The standard C string library has serious problems:
- 1) Its use of '\0' to denote the end of the string means knowing a
+ 1) Its use of '\0' to denote the end of the string means knowing a
string's length is O(n) when it could be O(1).
2) It imposes an interpretation for the character value '\0'.
3) gets() always exposes the application to a buffer overflow.
@@ -26,5 +26,5 @@
6) There is no memory management, and actions performed such as strcpy,
strcat and sprintf are common places for buffer overflows.
7) strncpy() doesn't '\0' terminate the destination in some cases.
- 8) Passing NULL to C library string functions causes an undefined NULL
+ 8) Passing NULL to C library string functions causes an undefined NULL
pointer access.
@@ -30,3 +30,3 @@
pointer access.
- 9) Parameter aliasing (overlapping, or self-referencing parameters)
+ 9) Parameter aliasing (overlapping, or self-referencing parameters)
within most C library functions has undefined behavior.
@@ -32,5 +32,5 @@
within most C library functions has undefined behavior.
- 10) Many C library string function calls take integer parameters with
+ 10) Many C library string function calls take integer parameters with
restricted legal ranges. Parameters passed outside these ranges are
not typically detected and cause undefined behavior.
@@ -45,9 +45,9 @@
without creating a dependency on stream IO functionality.
3) Implement the basic text editor-style functions insert, delete, find,
and replace.
- 4) Implement reference based sub-string access (as a generalization of
+ 4) Implement reference based sub-string access (as a generalization of
pointer arithmetic.)
5) Implement runtime write protection for strings.
There is also a desire to avoid "API-bloat". So functionality that can be
implemented trivially in other functionality is omitted. So there is no
@@ -49,9 +49,9 @@
pointer arithmetic.)
5) Implement runtime write protection for strings.
There is also a desire to avoid "API-bloat". So functionality that can be
implemented trivially in other functionality is omitted. So there is no
-left$() or right$() or reverse() or anything like that as part of the core
+left$() or right$() or reverse() or anything like that as part of the core
functionality.
Explaining Bstrings
@@ -66,6 +66,6 @@
unsigned char * data;
};
-This definition is considered exposed, not opaque (though it is neither
-necessary nor recommended that low level maintenance of bstrings be performed
+This definition is considered exposed, not opaque (though it is neither
+necessary nor recommended that low level maintenance of bstrings be performed
whenever the abstract interfaces are sufficient). The mlen field (usually)
@@ -71,7 +71,7 @@
whenever the abstract interfaces are sufficient). The mlen field (usually)
-describes a lower bound for the memory allocated for the data field. The
-slen field describes the exact length for the bstring. The data field is a
-single contiguous buffer of unsigned chars. Note that the existence of a '\0'
-character in the unsigned char buffer pointed to by the data field does not
+describes a lower bound for the memory allocated for the data field. The
+slen field describes the exact length for the bstring. The data field is a
+single contiguous buffer of unsigned chars. Note that the existence of a '\0'
+character in the unsigned char buffer pointed to by the data field does not
necessarily denote the end of the bstring.
@@ -76,10 +76,10 @@
necessarily denote the end of the bstring.
-To be a well formed modifiable bstring the mlen field must be at least the
-length of the slen field, and slen must be non-negative. Furthermore, the
-data field must point to a valid buffer in which access to the first mlen
+To be a well formed modifiable bstring the mlen field must be at least the
+length of the slen field, and slen must be non-negative. Furthermore, the
+data field must point to a valid buffer in which access to the first mlen
characters has been acquired. So the minimal check for correctness is:
(slen >= 0 && mlen >= slen && data != NULL)
bstrings returned by bstring functions can be assumed to be either NULL or
@@ -81,10 +81,10 @@
characters has been acquired. So the minimal check for correctness is:
(slen >= 0 && mlen >= slen && data != NULL)
bstrings returned by bstring functions can be assumed to be either NULL or
-satisfy the above property. (When bstrings are only readable, the mlen >=
-slen restriction is not required; this is discussed later in this section.)
+satisfy the above property. (When bstrings are only readable, the mlen >=
+slen restriction is not required; this is discussed later in this section.)
A bstring itself is just a pointer to a struct tagbstring:
typedef struct tagbstring * bstring;
@@ -93,12 +93,12 @@
around the inconsistency between C and C++'s struct namespace usage. This
definition is also considered exposed.
-Bstrlib basically manages bstrings allocated as a header and an associated
-data-buffer. Since the implementation is exposed, they can also be
-constructed manually. Functions which mutate bstrings assume that the header
-and data buffer have been malloced; the bstring library may perform free() or
-realloc() on both the header and data buffer of any bstring parameter.
-Functions which return bstring's create new bstrings. The string memory is
+Bstrlib basically manages bstrings allocated as a header and an associated
+data-buffer. Since the implementation is exposed, they can also be
+constructed manually. Functions which mutate bstrings assume that the header
+and data buffer have been malloced; the bstring library may perform free() or
+realloc() on both the header and data buffer of any bstring parameter.
+Functions which return bstring's create new bstrings. The string memory is
freed by a bdestroy() call (or using the bstrFree macro).
The following related typedef is also provided:
@@ -106,9 +106,9 @@
typedef const struct tagbstring * const_bstring;
which is also considered exposed. These are directly bstring compatible (no
-casting required) but are just used for parameters which are meant to be
-non-mutable. So in general, bstring parameters which are read as input but
+casting required) but are just used for parameters which are meant to be
+non-mutable. So in general, bstring parameters which are read as input but
not meant to be modified will be declared as const_bstring, and bstring
parameters which may be modified will be declared as bstring. This convention
is recommended for user written functions as well.
@@ -111,12 +111,12 @@
not meant to be modified will be declared as const_bstring, and bstring
parameters which may be modified will be declared as bstring. This convention
is recommended for user written functions as well.
-Since bstrings maintain interoperability with C library char-buffer style
-strings, all functions which modify, update or create bstrings also append a
-'\0' character into the position slen + 1. This trailing '\0' character is
-not required for bstrings input to the bstring functions; this is provided
-solely as a convenience for interoperability with standard C char-buffer
+Since bstrings maintain interoperability with C library char-buffer style
+strings, all functions which modify, update or create bstrings also append a
+'\0' character into the position slen + 1. This trailing '\0' character is
+not required for bstrings input to the bstring functions; this is provided
+solely as a convenience for interoperability with standard C char-buffer
functionality.
Analogs for the ANSI C string library functions have been created when they
@@ -125,7 +125,7 @@
bstring. The ->data member of any string is exposed, and therefore can be
used just as easily as char buffers for C functions which read strings.
-For those that wish to hand construct bstrings, the following should be kept
+For those that wish to hand construct bstrings, the following should be kept
in mind:
1) While bstrlib can accept constructed bstrings without terminating
@@ -138,6 +138,6 @@
properly. The struct tagbstring header is not reallocated, and only
freed by bdestroy.
3) Writing arbitrary '\0' characters at various places in the string
- will not modify its length as perceived by the bstring library
+ will not modify its length as perceived by the bstring library
functions. In fact, '\0' is a legitimate non-terminating character
for a bstring to contain.
@@ -142,6 +142,6 @@
functions. In fact, '\0' is a legitimate non-terminating character
for a bstring to contain.
- 4) For read only parameters, bstring functions do not check the mlen.
+ 4) For read only parameters, bstring functions do not check the mlen.
I.e., the minimal correctness requirements are reduced to:
(slen >= 0 && data != NULL)
@@ -150,6 +150,6 @@
-------------------------
One built-in feature of '\0' terminated char * strings, is that its very easy
-and fast to obtain a reference to the tail of any string using pointer
+and fast to obtain a reference to the tail of any string using pointer
arithmetic. Bstrlib does one better by providing a way to get a reference to
any substring of a bstring (or any other length delimited block of memory.)
@@ -154,9 +154,9 @@
arithmetic. Bstrlib does one better by providing a way to get a reference to
any substring of a bstring (or any other length delimited block of memory.)
-So rather than just having pointer arithmetic, with bstrlib one essentially
-has segment arithmetic. This is achieved using the macro blk2tbstr() which
-builds a reference to a block of memory and the macro bmid2tbstr() which
-builds a reference to a segment of a bstring. Bstrlib also includes
-functions for direct consumption of memory blocks into bstrings, namely
+So rather than just having pointer arithmetic, with bstrlib one essentially
+has segment arithmetic. This is achieved using the macro blk2tbstr() which
+builds a reference to a block of memory and the macro bmid2tbstr() which
+builds a reference to a segment of a bstring. Bstrlib also includes
+functions for direct consumption of memory blocks into bstrings, namely
bcatblk () and blk2bstr ().
@@ -161,12 +161,12 @@
bcatblk () and blk2bstr ().
-One scenario where this can be extremely useful is when string contains many
-substrings which one would like to pass as read-only reference parameters to
-some string consuming function without the need to allocate entire new
-containers for the string data. More concretely, imagine parsing a command
-line string whose parameters are space delimited. This can only be done for
+One scenario where this can be extremely useful is when string contains many
+substrings which one would like to pass as read-only reference parameters to
+some string consuming function without the need to allocate entire new
+containers for the string data. More concretely, imagine parsing a command
+line string whose parameters are space delimited. This can only be done for
tails of the string with '\0' terminated char * strings.
Improved NULL semantics and error handling
------------------------------------------
@@ -168,11 +168,11 @@
tails of the string with '\0' terminated char * strings.
Improved NULL semantics and error handling
------------------------------------------
-Unless otherwise noted, if a NULL pointer is passed as a bstring or any other
-detectably illegal parameter, the called function will return with an error
-indicator (either NULL or BSTR_ERR) rather than simply performing a NULL
+Unless otherwise noted, if a NULL pointer is passed as a bstring or any other
+detectably illegal parameter, the called function will return with an error
+indicator (either NULL or BSTR_ERR) rather than simply performing a NULL
pointer access, or having undefined behavior.
To illustrate the value of this, consider the following example:
@@ -180,10 +180,10 @@
strcpy (p = malloc (13 * sizeof (char)), "Hello,");
strcat (p, " World");
-This is not correct because malloc may return NULL (due to an out of memory
-condition), and the behaviour of strcpy is undefined if either of its
+This is not correct because malloc may return NULL (due to an out of memory
+condition), and the behaviour of strcpy is undefined if either of its
parameters are NULL. However:
bstrcat (p = bfromcstr ("Hello,"), q = bfromcstr (" World"));
bdestroy (q);
@@ -185,9 +185,9 @@
parameters are NULL. However:
bstrcat (p = bfromcstr ("Hello,"), q = bfromcstr (" World"));
bdestroy (q);
-is well defined, because if either p or q are assigned NULL (indicating a
-failure to allocate memory) both bstrcat and bdestroy will recognize it and
+is well defined, because if either p or q are assigned NULL (indicating a
+failure to allocate memory) both bstrcat and bdestroy will recognize it and
perform no detrimental action.
@@ -192,10 +192,10 @@
perform no detrimental action.
-Note that it is not necessary to check any of the members of a returned
-bstring for internal correctness (in particular the data member does not need
-to be checked against NULL when the header is non-NULL), since this is
+Note that it is not necessary to check any of the members of a returned
+bstring for internal correctness (in particular the data member does not need
+to be checked against NULL when the header is non-NULL), since this is
assured by the bstring library itself.
bStreams
--------
@@ -197,8 +197,8 @@
assured by the bstring library itself.
bStreams
--------
-In addition to the bgets and bread functions, bstrlib can abstract streams
-with a high performance read only stream called a bStream. In general, the
+In addition to the bgets and bread functions, bstrlib can abstract streams
+with a high performance read only stream called a bStream. In general, the
idea is to open a core stream (with something like fopen) then pass its
@@ -204,11 +204,11 @@
idea is to open a core stream (with something like fopen) then pass its
-handle as well as a bNread function pointer (like fread) to the bsopen
-function which will return a handle to an open bStream. Then the functions
-bsread, bsreadln or bsreadlns can be called to read portions of the stream.
-Finally, the bsclose function is called to close the bStream -- it will
-return a handle to the original (core) stream. So bStreams, essentially,
+handle as well as a bNread function pointer (like fread) to the bsopen
+function which will return a handle to an open bStream. Then the functions
+bsread, bsreadln or bsreadlns can be called to read portions of the stream.
+Finally, the bsclose function is called to close the bStream -- it will
+return a handle to the original (core) stream. So bStreams, essentially,
wrap other streams.
The bStreams have two main advantages over the bgets and bread (as well as
fgets/ungetc) paradigms:
@@ -210,9 +210,9 @@
wrap other streams.
The bStreams have two main advantages over the bgets and bread (as well as
fgets/ungetc) paradigms:
-1) Improved functionality via the bunread function which allows a stream to
- unread characters, giving the bStream stack-like functionality if so
+1) Improved functionality via the bunread function which allows a stream to
+ unread characters, giving the bStream stack-like functionality if so
desired.
2) A very high performance bsreadln function. The C library function fgets()
@@ -217,7 +217,7 @@
desired.
2) A very high performance bsreadln function. The C library function fgets()
- (and the bgets function) can typically be written as a loop on top of
- fgetc(), thus paying all of the overhead costs of calling fgetc on a per
- character basis. bsreadln will read blocks at a time, thus amortizing the
+ (and the bgets function) can typically be written as a loop on top of
+ fgetc(), thus paying all of the overhead costs of calling fgetc on a per
+ character basis. bsreadln will read blocks at a time, thus amortizing the
overhead of fread calls over many characters at once.
@@ -222,4 +222,4 @@
overhead of fread calls over many characters at once.
-However, clearly bStreams are suboptimal or unusable for certain kinds of
+However, clearly bStreams are suboptimal or unusable for certain kinds of
streams (stdin) or certain usage patterns (a few spotty, or non-sequential
@@ -225,4 +225,4 @@
streams (stdin) or certain usage patterns (a few spotty, or non-sequential
-reads from a slow stream.) For those situations, using bgets will be more
+reads from a slow stream.) For those situations, using bgets will be more
appropriate.
@@ -227,6 +227,6 @@
appropriate.
-The semantics of bStreams allows practical construction of layerable data
+The semantics of bStreams allows practical construction of layerable data
streams. What this means is that by writing a bNread compatible function on
top of a bStream, one can construct a new bStream on top of it. This can be
useful for writing multi-pass parsers that don't actually read the entire
@@ -237,8 +237,8 @@
Aliasing occurs when a function is given two parameters which point to data
structures which overlap in the memory they occupy. While this does not
-disturb read only functions, for many libraries this can make functions that
-write to these memory locations malfunction. This is a common problem of the
-C standard library and especially the string functions in the C standard
+disturb read only functions, for many libraries this can make functions that
+write to these memory locations malfunction. This is a common problem of the
+C standard library and especially the string functions in the C standard
library.
@@ -243,12 +243,12 @@
library.
-The C standard string library is entirely char by char oriented (as is
-bstring) which makes conforming implementations alias safe for some
-scenarios. However no actual detection of aliasing is typically performed,
-so it is easy to find cases where the aliasing will cause anomolous or
-undesirable behaviour (consider: strcat (p, p).) The C99 standard includes
-the "restrict" pointer modifier which allows the compiler to document and
-assume a no-alias condition on usage. However, only the most trivial cases
-can be caught (if at all) by the compiler at compile time, and thus there is
+The C standard string library is entirely char by char oriented (as is
+bstring) which makes conforming implementations alias safe for some
+scenarios. However no actual detection of aliasing is typically performed,
+so it is easy to find cases where the aliasing will cause anomolous or
+undesirable behaviour (consider: strcat (p, p).) The C99 standard includes
+the "restrict" pointer modifier which allows the compiler to document and
+assume a no-alias condition on usage. However, only the most trivial cases
+can be caught (if at all) by the compiler at compile time, and thus there is
no actual enforcement of non-aliasing.
@@ -253,12 +253,12 @@
no actual enforcement of non-aliasing.
-Bstrlib, by contrast, permits aliasing and is completely aliasing safe, in
-the C99 sense of aliasing. That is to say, under the assumption that
-pointers of incompatible types from distinct objects can never alias, bstrlib
-is completely aliasing safe. (In practice this means that the data buffer
-portion of any bstring and header of any bstring are assumed to never alias.)
-With the exception of the reference building macros, the library behaves as
-if all read-only parameters are first copied and replaced by temporary
-non-aliased parameters before any writing to any output bstring is performed
+Bstrlib, by contrast, permits aliasing and is completely aliasing safe, in
+the C99 sense of aliasing. That is to say, under the assumption that
+pointers of incompatible types from distinct objects can never alias, bstrlib
+is completely aliasing safe. (In practice this means that the data buffer
+portion of any bstring and header of any bstring are assumed to never alias.)
+With the exception of the reference building macros, the library behaves as
+if all read-only parameters are first copied and replaced by temporary
+non-aliased parameters before any writing to any output bstring is performed
(though actual copying is extremely rarely ever done.)
@@ -263,5 +263,5 @@
(though actual copying is extremely rarely ever done.)
-Besides being a useful safety feature, bstring searching/comparison
+Besides being a useful safety feature, bstring searching/comparison
functions can improve to O(1) execution when aliasing is detected.
@@ -266,9 +266,9 @@
functions can improve to O(1) execution when aliasing is detected.
-Note that aliasing detection and handling code in Bstrlib is generally
+Note that aliasing detection and handling code in Bstrlib is generally
extremely cheap. There is almost never any appreciable performance penalty
for using aliased parameters.
Reenterancy
-----------
@@ -269,10 +269,10 @@
extremely cheap. There is almost never any appreciable performance penalty
for using aliased parameters.
Reenterancy
-----------
-Nearly every function in Bstrlib is a leaf function, and is completely
-reenterable with the exception of writing to common bstrings. The split
-functions which use a callback mechanism requires only that the source string
+Nearly every function in Bstrlib is a leaf function, and is completely
+reenterable with the exception of writing to common bstrings. The split
+functions which use a callback mechanism requires only that the source string
not be destroyed by the callback function unless the callback function returns
@@ -278,3 +278,3 @@
not be destroyed by the callback function unless the callback function returns
-with an error status (note that Bstrlib functions which return an error do
+with an error status (note that Bstrlib functions which return an error do
not modify the string in any way.) The string can in fact be modified by the
@@ -280,5 +280,5 @@
not modify the string in any way.) The string can in fact be modified by the
-callback and the behaviour is deterministic. See the documentation of the
+callback and the behaviour is deterministic. See the documentation of the
various split functions for more details.
Undefined scenarios
@@ -286,14 +286,14 @@
One of the basic important premises for Bstrlib is to not to increase the
propogation of undefined situations from parameters that are otherwise legal
-in of themselves. In particular, except for extremely marginal cases, usages
-of bstrings that use the bstring library functions alone cannot lead to any
-undefined action. But due to C/C++ language and library limitations, there
-is no way to define a non-trivial library that is completely without
-undefined operations. All such possible undefined operations are described
+in of themselves. In particular, except for extremely marginal cases, usages
+of bstrings that use the bstring library functions alone cannot lead to any
+undefined action. But due to C/C++ language and library limitations, there
+is no way to define a non-trivial library that is completely without
+undefined operations. All such possible undefined operations are described
below:
1) bstrings or struct tagbstrings that are not explicitely initialized cannot
be passed as a parameter to any bstring function.
2) The members of the NULL bstring cannot be accessed directly. (Though all
APIs and macros detect the NULL bstring.)
@@ -294,11 +294,11 @@
below:
1) bstrings or struct tagbstrings that are not explicitely initialized cannot
be passed as a parameter to any bstring function.
2) The members of the NULL bstring cannot be accessed directly. (Though all
APIs and macros detect the NULL bstring.)
-3) A bstring whose data member has not been obtained from a malloc or
- compatible call and which is write accessible passed as a writable
- parameter will lead to undefined results. (i.e., do not writeAllow any
- constructed bstrings unless the data portion has been obtained from the
+3) A bstring whose data member has not been obtained from a malloc or
+ compatible call and which is write accessible passed as a writable
+ parameter will lead to undefined results. (i.e., do not writeAllow any
+ constructed bstrings unless the data portion has been obtained from the
heap.)
@@ -304,4 +304,4 @@
heap.)
-4) If the headers of two strings alias but are not identical (which can only
- happen via a defective manual construction), then passing them to a
+4) If the headers of two strings alias but are not identical (which can only
+ happen via a defective manual construction), then passing them to a
bstring function in which one is writable is not defined.
@@ -307,10 +307,10 @@
bstring function in which one is writable is not defined.
-5) If the mlen member is larger than the actual accessible length of the data
- member for a writable bstring, or if the slen member is larger than the
- readable length of the data member for a readable bstring, then the
+5) If the mlen member is larger than the actual accessible length of the data
+ member for a writable bstring, or if the slen member is larger than the
+ readable length of the data member for a readable bstring, then the
corresponding bstring operations are undefined.
6) Any bstring definition whose header or accessible data portion has been
assigned to inaccessible or otherwise illegal memory clearly cannot be
acted upon by the bstring library in any way.
7) Destroying the source of an incremental split from within the callback
and not returning with a negative value (indicating that it should abort)
@@ -311,9 +311,9 @@
corresponding bstring operations are undefined.
6) Any bstring definition whose header or accessible data portion has been
assigned to inaccessible or otherwise illegal memory clearly cannot be
acted upon by the bstring library in any way.
7) Destroying the source of an incremental split from within the callback
and not returning with a negative value (indicating that it should abort)
- will lead to undefined behaviour. (Though *modifying* or adjusting the
- state of the source data, even if those modification fail within the
+ will lead to undefined behaviour. (Though *modifying* or adjusting the
+ state of the source data, even if those modification fail within the
bstrlib API, has well defined behavior.)
@@ -319,4 +319,4 @@
bstrlib API, has well defined behavior.)
-8) Modifying a bstring which is write protected by direct access has
+8) Modifying a bstring which is write protected by direct access has
undefined behavior.
@@ -321,14 +321,14 @@
undefined behavior.
-While this may seem like a long list, with the exception of invalid uses of
-the writeAllow macro, and source destruction during an iterative split
-without an accompanying abort, no usage of the bstring API alone can cause
-any undefined scenario to occurr. I.e., the policy of restricting usage of
-bstrings to the bstring API can significantly reduce the risk of runtime
-errors (in practice it should eliminate them) related to string manipulation
+While this may seem like a long list, with the exception of invalid uses of
+the writeAllow macro, and source destruction during an iterative split
+without an accompanying abort, no usage of the bstring API alone can cause
+any undefined scenario to occurr. I.e., the policy of restricting usage of
+bstrings to the bstring API can significantly reduce the risk of runtime
+errors (in practice it should eliminate them) related to string manipulation
due to undefined action.
C++ wrapper
-----------
A C++ wrapper has been created to enable bstring functionality for C++ in the
@@ -329,13 +329,13 @@
due to undefined action.
C++ wrapper
-----------
A C++ wrapper has been created to enable bstring functionality for C++ in the
-most natural (for C++ programers) way possible. The mandate for the C++
-wrapper is different from the base C bstring library. Since the C++ language
-has far more abstracting capabilities, the CBString structure is considered
-fully abstracted -- i.e., hand generated CBStrings are not supported (though
+most natural (for C++ programers) way possible. The mandate for the C++
+wrapper is different from the base C bstring library. Since the C++ language
+has far more abstracting capabilities, the CBString structure is considered
+fully abstracted -- i.e., hand generated CBStrings are not supported (though
conversion from a struct tagbstring is allowed) and all detectable errors are
manifest as thrown exceptions.
@@ -339,8 +339,8 @@
conversion from a struct tagbstring is allowed) and all detectable errors are
manifest as thrown exceptions.
-- The C++ class definitions are all under the namespace Bstrlib. bstrwrap.h
- enables this namespace (with a using namespace Bstrlib; directive at the
- end) unless the macro BSTRLIB_DONT_ASSUME_NAMESPACE has been defined before
+- The C++ class definitions are all under the namespace Bstrlib. bstrwrap.h
+ enables this namespace (with a using namespace Bstrlib; directive at the
+ end) unless the macro BSTRLIB_DONT_ASSUME_NAMESPACE has been defined before
it is included.
@@ -345,4 +345,4 @@
it is included.
-- Erroneous accesses results in an exception being thrown. The exception
+- Erroneous accesses results in an exception being thrown. The exception
parameter is of type "struct CBStringException" which is derived from
@@ -348,4 +348,4 @@
parameter is of type "struct CBStringException" which is derived from
- std::exception if STL is used. A verbose description of the error message
+ std::exception if STL is used. A verbose description of the error message
can be obtained from the what() method.
@@ -350,6 +350,6 @@
can be obtained from the what() method.
-- CBString is a C++ structure derived from a struct tagbstring. An address
- of a CBString cast to a bstring must not be passed to bdestroy. The bstring
+- CBString is a C++ structure derived from a struct tagbstring. An address
+ of a CBString cast to a bstring must not be passed to bdestroy. The bstring
C API has been made C++ safe and can be used directly in a C++ project.
@@ -354,6 +354,6 @@
C API has been made C++ safe and can be used directly in a C++ project.
-- It includes constructors which can take a char, '\0' terminated char
- buffer, tagbstring, (char, repeat-value), a length delimited buffer or a
+- It includes constructors which can take a char, '\0' terminated char
+ buffer, tagbstring, (char, repeat-value), a length delimited buffer or a
CBStringList to initialize it.
@@ -358,6 +358,6 @@
CBStringList to initialize it.
-- Concatenation is performed with the + and += operators. Comparisons are
+- Concatenation is performed with the + and += operators. Comparisons are
done with the ==, !=, <, >, <= and >= operators. Note that == and != use
the biseq call, while <, >, <= and >= use bstrcmp.
@@ -369,5 +369,5 @@
the format(a) method(s).
- CBString contains the length, character and [] accessor methods. The
- character and [] accessors are aliases of each other. If the bounds for
+ character and [] accessors are aliases of each other. If the bounds for
the string are exceeded, an exception is thrown. To avoid the overhead for
@@ -373,5 +373,5 @@
the string are exceeded, an exception is thrown. To avoid the overhead for
- this check, first cast the CBString to a (const char *) and use [] to
- dereference the array as normal. Note that the character and [] accessor
+ this check, first cast the CBString to a (const char *) and use [] to
+ dereference the array as normal. Note that the character and [] accessor
methods allows both reading and writing of individual characters.
@@ -376,10 +376,10 @@
methods allows both reading and writing of individual characters.
-- The methods: format, formata, find, reversefind, findcaseless,
- reversefindcaseless, midstr, insert, insertchrs, replace, findreplace,
- findreplacecaseless, remove, findchr, nfindchr, alloc, toupper, tolower,
+- The methods: format, formata, find, reversefind, findcaseless,
+ reversefindcaseless, midstr, insert, insertchrs, replace, findreplace,
+ findreplacecaseless, remove, findchr, nfindchr, alloc, toupper, tolower,
gets, read are analogous to the functions that can be found in the C API.
- The caselessEqual and caselessCmp methods are analogous to biseqcaseless
and bstricmp functions respectively.
@@ -381,9 +381,9 @@
gets, read are analogous to the functions that can be found in the C API.
- The caselessEqual and caselessCmp methods are analogous to biseqcaseless
and bstricmp functions respectively.
-- Note that just like the bformat function, the format and formata methods do
- not automatically cast CBStrings into char * strings for "%s"-type
+- Note that just like the bformat function, the format and formata methods do
+ not automatically cast CBStrings into char * strings for "%s"-type
substitutions:
@@ -388,11 +388,11 @@
substitutions:
- CBString w("world");
- CBString h("Hello");
- CBString hw;
-
- /* The casts are necessary */
- hw.format ("%s, %s", (const char *)h, (const char *)w);
+ CBString w("world");
+ CBString h("Hello");
+ CBString hw;
+
+ /* The casts are necessary */
+ hw.format ("%s, %s", (const char *)h, (const char *)w);
- The methods trunc and repeat have been added instead of using pattern.
@@ -396,7 +396,7 @@
- The methods trunc and repeat have been added instead of using pattern.
-- ltrim, rtrim and trim methods have been added. These remove characters
- from a given character string set (defaulting to the whitespace characters)
+- ltrim, rtrim and trim methods have been added. These remove characters
+ from a given character string set (defaulting to the whitespace characters)
from either the left, right or both ends of the CBString, respectively.
@@ -401,6 +401,6 @@
from either the left, right or both ends of the CBString, respectively.
-- The method setsubstr is also analogous in functionality to bsetstr, except
- that it cannot be passed NULL. Instead the method fill and the fill-style
+- The method setsubstr is also analogous in functionality to bsetstr, except
+ that it cannot be passed NULL. Instead the method fill and the fill-style
constructor have been supplied to enable this functionality.
@@ -405,11 +405,11 @@
constructor have been supplied to enable this functionality.
-- The writeprotect(), writeallow() and iswriteprotected() methods are
- analogous to the bwriteprotect(), bwriteallow() and biswriteprotected()
- macros in the C API. Write protection semantics in CBString are stronger
- than with the C API in that indexed character assignment is checked for
- write protection. However, unlike with the C API, a write protected
+- The writeprotect(), writeallow() and iswriteprotected() methods are
+ analogous to the bwriteprotect(), bwriteallow() and biswriteprotected()
+ macros in the C API. Write protection semantics in CBString are stronger
+ than with the C API in that indexed character assignment is checked for
+ write protection. However, unlike with the C API, a write protected
CBString can be destroyed by the destructor.
- CBStream is a C++ structure which wraps a struct bStream (its not derived
from it, since destruction is slightly different). It is constructed by
@@ -412,9 +412,9 @@
CBString can be destroyed by the destructor.
- CBStream is a C++ structure which wraps a struct bStream (its not derived
from it, since destruction is slightly different). It is constructed by
- passing in a bNread function pointer and a stream parameter cast to void *.
- This structure includes methods for detecting eof, setting the buffer
- length, reading the whole stream or reading entries line by line or block
+ passing in a bNread function pointer and a stream parameter cast to void *.
+ This structure includes methods for detecting eof, setting the buffer
+ length, reading the whole stream or reading entries line by line or block
by block, an unread function, and a peek function.
@@ -419,6 +419,6 @@
by block, an unread function, and a peek function.
-- If STL is available, the CBStringList structure is derived from a vector of
- CBString with various split methods. The split method has been overloaded
- to accept either a character or CBString as the second parameter (when the
+- If STL is available, the CBStringList structure is derived from a vector of
+ CBString with various split methods. The split method has been overloaded
+ to accept either a character or CBString as the second parameter (when the
split parameter is a CBString any character in that CBString is used as a
@@ -424,5 +424,5 @@
split parameter is a CBString any character in that CBString is used as a
- seperator). The splitstr method takes a CBString as a substring seperator.
- Joins can be performed via a CBString constructor which takes a
+ seperator). The splitstr method takes a CBString as a substring seperator.
+ Joins can be performed via a CBString constructor which takes a
CBStringList as a parameter, or just using the CBString::join() method.
@@ -427,9 +427,9 @@
CBStringList as a parameter, or just using the CBString::join() method.
-- If there is proper support for std::iostreams, then the >> and << operators
- and the getline() function have been added (with semantics the same as
+- If there is proper support for std::iostreams, then the >> and << operators
+ and the getline() function have been added (with semantics the same as
those for std::string).
Multithreading
--------------
@@ -431,22 +431,22 @@
those for std::string).
Multithreading
--------------
-A mutable bstring is kind of analogous to a small (two entry) linked list
-allocated by malloc, with all aliasing completely under programmer control.
-I.e., manipulation of one bstring will never affect any other distinct
-bstring unless explicitely constructed to do so by the programmer via hand
-construction or via building a reference. Bstrlib also does not use any
-static or global storage, so there are no hidden unremovable race conditions.
-Bstrings are also clearly not inherently thread local. So just like
-char *'s, bstrings can be passed around from thread to thread and shared and
-so on, so long as modifications to a bstring correspond to some kind of
-exclusive access lock as should be expected (or if the bstring is read-only,
-which can be enforced by bstring write protection) for any sort of shared
+A mutable bstring is kind of analogous to a small (two entry) linked list
+allocated by malloc, with all aliasing completely under programmer control.
+I.e., manipulation of one bstring will never affect any other distinct
+bstring unless explicitely constructed to do so by the programmer via hand
+construction or via building a reference. Bstrlib also does not use any
+static or global storage, so there are no hidden unremovable race conditions.
+Bstrings are also clearly not inherently thread local. So just like
+char *'s, bstrings can be passed around from thread to thread and shared and
+so on, so long as modifications to a bstring correspond to some kind of
+exclusive access lock as should be expected (or if the bstring is read-only,
+which can be enforced by bstring write protection) for any sort of shared
object in a multithreaded environment.
Bsafe module
------------
For convenience, a bsafe module has been included. The idea is that if this
@@ -447,15 +447,15 @@
object in a multithreaded environment.
Bsafe module
------------
For convenience, a bsafe module has been included. The idea is that if this
-module is included, inadvertant usage of the most dangerous C functions will
-be overridden and lead to an immediate run time abort. Of course, it should
-be emphasized that usage of this module is completely optional. The
-intention is essentially to provide an option for creating project safety
-rules which can be enforced mechanically rather than socially. This is
-useful for larger, or open development projects where its more difficult to
+module is included, inadvertant usage of the most dangerous C functions will
+be overridden and lead to an immediate run time abort. Of course, it should
+be emphasized that usage of this module is completely optional. The
+intention is essentially to provide an option for creating project safety
+rules which can be enforced mechanically rather than socially. This is
+useful for larger, or open development projects where its more difficult to
enforce social rules or "coding conventions".
Problems not solved
@@ -465,5 +465,5 @@
that cannot be easily solved:
1. Memory leaks: Forgetting to call bdestroy on a bstring that is about to be
- unreferenced, just as forgetting to call free on a heap buffer that is
+ unreferenced, just as forgetting to call free on a heap buffer that is
about to be dereferenced. Though bstrlib itself is leak free.
@@ -469,8 +469,8 @@
about to be dereferenced. Though bstrlib itself is leak free.
-2. Read before write usage: In C, declaring an auto bstring does not
- automatically fill it with legal/valid contents. This problem has been
- somewhat mitigated in C++. (The bstrDeclare and bstrFree macros from
+2. Read before write usage: In C, declaring an auto bstring does not
+ automatically fill it with legal/valid contents. This problem has been
+ somewhat mitigated in C++. (The bstrDeclare and bstrFree macros from
bstraux can be used to help mitigate this problem.)
Other problems not addressed:
@@ -473,11 +473,11 @@
bstraux can be used to help mitigate this problem.)
Other problems not addressed:
-3. Built-in mutex usage to automatically avoid all bstring internal race
- conditions in multitasking environments: The problem with trying to
- implement such things at this low a level is that it is typically more
- efficient to use locks in higher level primitives. There is also no
+3. Built-in mutex usage to automatically avoid all bstring internal race
+ conditions in multitasking environments: The problem with trying to
+ implement such things at this low a level is that it is typically more
+ efficient to use locks in higher level primitives. There is also no
platform independent way to implement locks or mutexes.
4. Unicode/widecharacter support.
@@ -481,9 +481,9 @@
platform independent way to implement locks or mutexes.
4. Unicode/widecharacter support.
-Note that except for spotty support of wide characters, the default C
+Note that except for spotty support of wide characters, the default C
standard library does not address any of these problems either.
Configurable compilation options
--------------------------------
@@ -485,9 +485,9 @@
standard library does not address any of these problems either.
Configurable compilation options
--------------------------------
-All configuration options are meant solely for the purpose of compiler
+All configuration options are meant solely for the purpose of compiler
compatibility. Configuration options are not meant to change the semantics
or capabilities of the library, except where it is unavoidable.
@@ -491,9 +491,9 @@
compatibility. Configuration options are not meant to change the semantics
or capabilities of the library, except where it is unavoidable.
-Since some C++ compilers don't include the Standard Template Library and some
-have the options of disabling exception handling, a number of macros can be
+Since some C++ compilers don't include the Standard Template Library and some
+have the options of disabling exception handling, a number of macros can be
used to conditionally compile support for each of this:
BSTRLIB_CAN_USE_STL
@@ -496,9 +496,9 @@
used to conditionally compile support for each of this:
BSTRLIB_CAN_USE_STL
- - defining this will enable the used of the Standard Template Library.
+ - defining this will enable the used of the Standard Template Library.
Defining BSTRLIB_CAN_USE_STL overrides the BSTRLIB_CANNOT_USE_STL macro.
BSTRLIB_CANNOT_USE_STL
@@ -501,9 +501,9 @@
Defining BSTRLIB_CAN_USE_STL overrides the BSTRLIB_CANNOT_USE_STL macro.
BSTRLIB_CANNOT_USE_STL
- - defining this will disable the use of the Standard Template Library.
+ - defining this will disable the use of the Standard Template Library.
Defining BSTRLIB_CAN_USE_STL overrides the BSTRLIB_CANNOT_USE_STL macro.
BSTRLIB_CAN_USE_IOSTREAM
@@ -506,9 +506,9 @@
Defining BSTRLIB_CAN_USE_STL overrides the BSTRLIB_CANNOT_USE_STL macro.
BSTRLIB_CAN_USE_IOSTREAM
- - defining this will enable the used of streams from class std. Defining
+ - defining this will enable the used of streams from class std. Defining
BSTRLIB_CAN_USE_IOSTREAM overrides the BSTRLIB_CANNOT_USE_IOSTREAM macro.
BSTRLIB_CANNOT_USE_IOSTREAM
@@ -511,10 +511,10 @@
BSTRLIB_CAN_USE_IOSTREAM overrides the BSTRLIB_CANNOT_USE_IOSTREAM macro.
BSTRLIB_CANNOT_USE_IOSTREAM
- - defining this will disable the use of streams from class std. Defining
+ - defining this will disable the use of streams from class std. Defining
BSTRLIB_CAN_USE_IOSTREAM overrides the BSTRLIB_CANNOT_USE_IOSTREAM macro.
BSTRLIB_THROWS_EXCEPTIONS
- defining this will enable the exception handling within bstring.
@@ -516,11 +516,11 @@
BSTRLIB_CAN_USE_IOSTREAM overrides the BSTRLIB_CANNOT_USE_IOSTREAM macro.
BSTRLIB_THROWS_EXCEPTIONS
- defining this will enable the exception handling within bstring.
- Defining BSTRLIB_THROWS_EXCEPTIONS overrides the
+ Defining BSTRLIB_THROWS_EXCEPTIONS overrides the
BSTRLIB_DOESNT_THROWS_EXCEPTIONS macro.
BSTRLIB_DOESNT_THROW_EXCEPTIONS
- defining this will disable the exception handling within bstring.
@@ -522,8 +522,8 @@
BSTRLIB_DOESNT_THROWS_EXCEPTIONS macro.
BSTRLIB_DOESNT_THROW_EXCEPTIONS
- defining this will disable the exception handling within bstring.
- Defining BSTRLIB_THROWS_EXCEPTIONS overrides the
+ Defining BSTRLIB_THROWS_EXCEPTIONS overrides the
BSTRLIB_DOESNT_THROW_EXCEPTIONS macro.
@@ -528,5 +528,5 @@
BSTRLIB_DOESNT_THROW_EXCEPTIONS macro.
-Note that these macros must be defined consistently throughout all modules
+Note that these macros must be defined consistently throughout all modules
that use CBStrings including bstrwrap.cpp.
@@ -531,6 +531,6 @@
that use CBStrings including bstrwrap.cpp.
-Some older C compilers do not support functions such as vsnprintf. This is
+Some older C compilers do not support functions such as vsnprintf. This is
handled by the following macro variables:
BSTRLIB_NOVSNP
@@ -542,8 +542,8 @@
BSTRLIB_VSNP_OK
- - defining this will disable the autodetection of compilers the do not
- support of compilers that do not support vsnprintf.
+ - defining this will disable the autodetection of compilers that do not
+ vsnprintf.
Defining BSTRLIB_NOVSNP overrides the BSTRLIB_VSNP_OK macro.
Semantic compilation options
@@ -554,7 +554,7 @@
BSTRLIB_DONT_ASSUME_NAMESPACE
- - Defining this before including bstrwrap.h will disable the automatic
+ - Defining this before including bstrwrap.h will disable the automatic
enabling of the Bstrlib namespace for the C++ declarations.
BSTRLIB_DONT_USE_VIRTUAL_DESTRUCTOR
@@ -566,8 +566,8 @@
- Defining this will cause the bstrlib modules bstrlib.c and bstrwrap.cpp
to invoke a #include "memdbg.h". memdbg.h has to be supplied by the user.
-Note that these macros must be defined consistently throughout all modules
-that use bstrings or CBStrings including bstrlib.c, bstraux.c and
+Note that these macros must be defined consistently throughout all modules
+that use bstrings or CBStrings including bstrlib.c, bstraux.c and
bstrwrap.cpp.
===============================================================================
@@ -590,8 +590,8 @@
C projects need only include bstrlib.h and compile/link bstrlib.c to use the
bstring library. C++ projects need to additionally include bstrwrap.h and
-compile/link bstrwrap.cpp. For both, there may be a need to make choices
-about feature configuration as described in the "Configurable compilation
+compile/link bstrwrap.cpp. For both, there may be a need to make choices
+about feature configuration as described in the "Configurable compilation
options" in the section above.
Other files that are included in this archive are:
@@ -610,8 +610,8 @@
extern 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
+ a bstring with the same contents as the char buffer. If an error occurs
NULL is returned.
So for example:
@@ -614,15 +614,15 @@
NULL is returned.
So for example:
- bstring b = bfromcstr ("Hello");
- if (!b) {
- fprintf (stderr, "Out of memory");
- } else {
- puts ((char *) b->data);
- }
+ bstring b = bfromcstr ("Hello");
+ if (!b) {
+ fprintf (stderr, "Out of memory");
+ } else {
+ puts ((char *) b->data);
+ }
..........................................................................
extern bstring bfromcstralloc (int mlen, const char * str);
@@ -624,11 +624,11 @@
..........................................................................
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
+ 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.
So for example:
@@ -631,16 +631,16 @@
mlen characters in length. If an error occurs NULL is returned.
So 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. And we know this is well
- defined so long as b was successfully created, since it will have been
+ bstring b = bfromcstralloc (64, someCstr);
+ if (b) b->data[63] = 'x';
+
+ The idea is that this will set the 64th character of b to 'x' if it is at
+ least 64 characters long otherwise do nothing. And we know this is well
+ defined so long as b was successfully created, since it will have been
allocated with at least 64 characters.
..........................................................................
extern bstring blk2bstr (const void * blk, int len);
@@ -641,8 +641,8 @@
allocated with at least 64 characters.
..........................................................................
extern bstring blk2bstr (const void * blk, int len);
- Create a bstring whose contents are described by the contiguous buffer
+ 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
@@ -648,8 +648,8 @@
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.
+ 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.
..........................................................................
extern char * bstr2cstr (const_bstring s, char z);
@@ -650,12 +650,12 @@
Compare with the blk2tbstr macro. If an error occurs NULL is returned.
..........................................................................
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
+ 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.
..........................................................................
@@ -663,14 +663,14 @@
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 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
+ 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.
..........................................................................
extern bstring bstrcpy (const_bstring b1);
@@ -671,13 +671,13 @@
redefinitions.
..........................................................................
extern bstring bstrcpy (const_bstring b1);
- Make a copy of the passed in bstring. The copied bstring is returned if
+ Make a copy of the passed in bstring. The copied bstring is returned if
there is no error, otherwise NULL is returned.
..........................................................................
extern int bassign (bstring a, const_bstring b);
@@ -678,14 +678,14 @@
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
+ 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.
..........................................................................
int bassigncstr (bstring a, const char * str);
@@ -686,14 +686,14 @@
occurs BSTR_ERR is returned and a is not overwritten.
..........................................................................
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
+ 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.
..........................................................................
int bassignblk (bstring a, const void * s, int len);
@@ -694,14 +694,14 @@
occurs BSTR_ERR is returned and a may be partially overwritten.
..........................................................................
int bassignblk (bstring a, const void * s, int len);
- Overwrite the string a with the contents of the block (s, len). Note that
- the bstring a must be a well defined and writable bstring. If an error
+ Overwrite the string a with the contents of the block (s, 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);
@@ -702,16 +702,16 @@
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
+ 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);
@@ -712,15 +712,15 @@
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 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
+ 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.
..........................................................................
extern int bdelete (bstring s1, int pos, int len);
@@ -721,16 +721,16 @@
otherwise NULL is returned.
..........................................................................
extern 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
+ 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.
..........................................................................
extern int bconcat (bstring b0, const_bstring b1);
@@ -731,14 +731,14 @@
if the operation is successful, otherwise BSTR_ERR is returned.
..........................................................................
extern 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
+ 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.
..........................................................................
extern int bconchar (bstring b, char c);
@@ -739,14 +739,14 @@
returned.
..........................................................................
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
+ 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);
@@ -747,14 +747,14 @@
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
+ 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 * s, int len);
@@ -755,14 +755,14 @@
returned.
..........................................................................
extern 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
+ 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.
..........................................................................
extern int biseq (const_bstring b0, const_bstring b1);
@@ -763,12 +763,12 @@
BSTR_ERR is returned.
..........................................................................
extern 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
+ 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.
@@ -773,9 +773,9 @@
as a termination character.
- Note that the semantics of biseq are not completely compatible with
+ 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);
@@ -776,15 +776,15 @@
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 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,
+ 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.
..........................................................................
extern int biseqcaseless (const_bstring b0, const_bstring b1);
@@ -785,16 +785,16 @@
if there is an error, -1 is returned.
..........................................................................
extern 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'
+ 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.
..........................................................................
extern int bisstemeqcaselessblk (const_bstring b0, const void * blk, int len);
@@ -795,8 +795,8 @@
termination characters are not treated in any special way.
..........................................................................
extern int bisstemeqcaselessblk (const_bstring b0, const void * blk, int len);
- Compare beginning of bstring b0 with a block of memory of length 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
@@ -802,9 +802,9 @@
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
+ 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.
..........................................................................
extern int biseqcstr (const_bstring b, const char *s);
@@ -805,16 +805,16 @@
error, -1 is returned.
..........................................................................
extern int biseqcstr (const_bstring b, const char *s);
- Compare the bstring b and char * bstring 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
+ Compare the bstring b and char * bstring 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.
..........................................................................
@@ -827,11 +827,11 @@
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
+ 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 b0, const_bstring b1);
@@ -832,10 +832,10 @@
there is a detectable error BSTR_ERR is returned.
..........................................................................
extern 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
+ 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
@@ -841,10 +841,10 @@
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
+ 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.
@@ -849,6 +849,6 @@
encountered.
- The seemingly odd error return value, merely provides slightly more
- granularity than the undefined situation given in the C library function
+ 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().
@@ -853,10 +853,10 @@
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
+ 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 b0, const_bstring b1, int n);
@@ -857,14 +857,14 @@
character.
..........................................................................
extern 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'
+ 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.
@@ -869,10 +869,10 @@
termination characters encountered.
- The seemingly odd error return value, merely provides slightly more
- granularity than the undefined situation given in the C library function
+ 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 b0, const_bstring b1);
@@ -873,14 +873,14 @@
strncmp. The function otherwise behaves very much like strncmp().
..........................................................................
extern 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
+ 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.
..........................................................................
@@ -891,11 +891,11 @@
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
+ 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);
@@ -896,17 +896,17 @@
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
+ 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
@@ -909,8 +909,8 @@
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
+ CBString destructor.) Instead just use the ordinary C++ language
facilities to dealloc a CBString.
..........................................................................
@@ -918,8 +918,8 @@
extern 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.
+ 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).
..........................................................................
@@ -927,11 +927,11 @@
extern 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
+ 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).
..........................................................................
@@ -939,9 +939,9 @@
extern 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;
+ 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).
..........................................................................
@@ -949,14 +949,14 @@
extern 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
+ 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).
..........................................................................
extern int binchr (const_bstring b0, int pos, const_bstring b1);
@@ -957,15 +957,15 @@
position. The algorithm used is brute force; O(m*n).
..........................................................................
extern 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,
+ 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.
..........................................................................
extern int binchrr (const_bstring b0, int pos, const_bstring b1);
@@ -966,8 +966,8 @@
then BSTR_ERR is returned.
..........................................................................
extern 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
+ 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
@@ -973,8 +973,8 @@
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,
+ of O(b0->slen + b1->slen). If such a position does not exist in b0,
then BSTR_ERR is returned.
..........................................................................
extern int bninchr (const_bstring b0, int pos, const_bstring b1);
@@ -975,14 +975,14 @@
then BSTR_ERR is returned.
..........................................................................
extern 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
+ 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.
..........................................................................
extern int bninchrr (const_bstring b0, int pos, const_bstring b1);
@@ -984,15 +984,15 @@
not exist in b0, then BSTR_ERR is returned.
..........................................................................
extern 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
+
+ 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.
..........................................................................
extern int bstrchr (const_bstring b, int c);
@@ -993,11 +993,11 @@
exist in b0, then BSTR_ERR is returned.
..........................................................................
extern int bstrchr (const_bstring b, int c);
- Search for the character c in the bstring b forwards from the start of
- the bstring. Returns the position of the found character or BSTR_ERR if
+ Search for the character c in the bstring b forwards from the start of
+ the bstring. Returns the position of the found character or BSTR_ERR if
it is not found.
NOTE: This has been implemented as a macro on top of bstrchrp ().
@@ -1006,8 +1006,8 @@
extern int bstrrchr (const_bstring b, int c);
- Search for the character c in the bstring b backwards from the end of the
- bstring. Returns the position of the found character or BSTR_ERR if it is
+ Search for the character c in the bstring b backwards from the end of the
+ bstring. Returns the position of the found character or BSTR_ERR if it is
not found.
NOTE: This has been implemented as a macro on top of bstrrchrp ().
@@ -1015,12 +1015,12 @@
..........................................................................
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
+
+ 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);
@@ -1021,14 +1021,14 @@
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
+ 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 b0, int pos, const_bstring b1, unsigned char fill);
@@ -1029,9 +1029,9 @@
it is not found.
..........................................................................
extern 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
+ 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.
@@ -1037,9 +1037,9 @@
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
+ 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.
..........................................................................
extern int binsert (bstring s1, int pos, const_bstring s2, unsigned char fill);
@@ -1040,15 +1040,15 @@
returned.
..........................................................................
extern 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
+ 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.
..........................................................................
extern int binsertch (bstring s1, int pos, int len, unsigned char fill);
@@ -1049,14 +1049,14 @@
returned if the operation is successful, otherwise BSTR_ERR is returned.
..........................................................................
extern 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
+ 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.
..........................................................................
@@ -1059,7 +1059,7 @@
returned if the operation is successful, otherwise BSTR_ERR is returned.
..........................................................................
- extern int breplace (bstring b1, int pos, int len, const_bstring b2,
+ extern int breplace (bstring b1, int pos, int len, const_bstring b2,
unsigned char fill);
@@ -1064,4 +1064,4 @@
unsigned char fill);
- Replace a section of a bstring from pos for a length len with the bstring
+ 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"
@@ -1067,5 +1067,5 @@
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
+ is appended as necessary to make up the gap between the end of b1 and
pos.
..........................................................................
@@ -1073,9 +1073,9 @@
extern int bfindreplace (bstring b, const_bstring find,
const_bstring replace, int position);
- 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
+ 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.
@@ -1086,8 +1086,8 @@
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
+ 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.
..........................................................................
@@ -1095,10 +1095,10 @@
extern int bfindreplacecaseless (bstring b, const_bstring find,
const_bstring replace, int position);
- 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
+ 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:
@@ -1108,8 +1108,8 @@
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
+ 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.
..........................................................................
@@ -1118,9 +1118,9 @@
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
+ 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
@@ -1134,10 +1134,10 @@
int t;
if (BSTR_OK == balloc (b, t = (b->slen * 2))) b->slen = t;
- This function will return with BSTR_ERR if b is not detected as a valid
+ 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.
..........................................................................
extern int ballocmin (bstring b, int length);
@@ -1138,9 +1138,9 @@
bstring or length is not greater than 0, otherwise BSTR_OK is returned.
..........................................................................
extern int ballocmin (bstring b, int length);
- Change the amount of memory backing the bstring b to at least length.
- This operation will never truncate the bstring data including the
+ 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
@@ -1146,3 +1146,3 @@
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
+ b->slen + 1. Note that repeated use of this function may cause
performance problems (realloc may be called on the bstring more than
@@ -1148,7 +1148,7 @@
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,
+ 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:
@@ -1151,15 +1151,15 @@
otherwise BSTR_OK is returned.
So for example:
- if (BSTR_OK == ballocmin (b, 64)) b->data[63] = 'x';
-
- The idea is that this will set the 64th character of b to 'x' if it is at
- least 64 characters long otherwise do nothing. And we know this is well
- defined so long as the ballocmin call was successfully, since it will
+ if (BSTR_OK == ballocmin (b, 64)) b->data[63] = 'x';
+
+ The idea is that this will set the 64th character of b to 'x' if it is at
+ least 64 characters long otherwise do nothing. And we know this is well
+ defined so long as the ballocmin call was successfully, since it will
ensure that b has been allocated with at least 64 characters.
..........................................................................
int btrunc (bstring b, int n);
@@ -1160,14 +1160,14 @@
ensure that b has been allocated with at least 64 characters.
..........................................................................
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
+ 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);
@@ -1168,15 +1168,15 @@
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
+ 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);
@@ -1177,13 +1177,13 @@
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
+ 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);
@@ -1184,13 +1184,13 @@
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
+ 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);
@@ -1191,14 +1191,14 @@
BSTR_ERR if b is NULL or of length 0, otherwise BSTR_OK is returned.
..........................................................................
extern 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
+ 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.
..........................................................................
extern int brtrimws (bstring b);
@@ -1199,14 +1199,14 @@
BSTR_OK is returned.
..........................................................................
extern 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
+ 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.
..........................................................................
extern int btrimws (bstring b);
@@ -1207,12 +1207,12 @@
BSTR_OK is returned.
..........................................................................
extern 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
+ 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.
..........................................................................
@@ -1215,10 +1215,10 @@
is returned.
..........................................................................
- extern int bstrListCreate (void);
-
- Create an empty struct bstrList. The struct bstrList output structure is
+ extern struct bstrList* bstrListCreate (void);
+
+ Create an empty struct bstrList. The struct bstrList output structure is
declared as follows:
struct bstrList {
@@ -1230,11 +1230,11 @@
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
+ 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.
@@ -1242,7 +1242,7 @@
extern int bstrListDestroy (struct bstrList * sl);
- Destroy a struct bstrList structure that was returned by the bsplit
+ 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.
@@ -1264,14 +1264,14 @@
extern struct bstrList * bsplit (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
+ 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.
..........................................................................
extern struct bstrList * bsplits (bstring str, const_bstring splitStr);
@@ -1272,15 +1272,15 @@
structure of struct bstrList.
..........................................................................
extern struct bstrList * bsplits (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()
+ 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.
..........................................................................
extern struct bstrList * bsplitstr (bstring str, const_bstring splitStr);
@@ -1281,15 +1281,15 @@
above for structure of struct bstrList.
..........................................................................
extern struct bstrList * bsplitstr (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
+ 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.
..........................................................................
extern bstring bjoin (const struct bstrList * bl, const_bstring sep);
@@ -1290,12 +1290,12 @@
structure of struct bstrList.
..........................................................................
extern bstring bjoin (const struct bstrList * bl, const_bstring sep);
- Join the entries of a bstrList into one bstring by sequentially
+ 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);
@@ -1297,12 +1297,12 @@
concatenating them with the sep bstring in between. If sep is NULL, it
is treated as if it were the empty bstring. Note that:
bjoin (l = bsplit (b, s->data[0]), s);
- should result in a copy of b, if s->slen is 1. If there is an error NULL
- is returned, otherwise a bstring with the correct result is returned.
+ 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.
..........................................................................
extern int bsplitcb (const_bstring str, unsigned char splitChar, int pos,
@@ -1304,12 +1304,12 @@
See bstrListCreate() above for structure of struct bstrList.
..........................................................................
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 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,
+ 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.
@@ -1314,12 +1314,12 @@
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,
+ 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
@@ -1328,11 +1328,11 @@
..........................................................................
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 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,
+ 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.
@@ -1337,11 +1337,11 @@
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,
+ 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.
@@ -1346,8 +1346,8 @@
otherwise bsplitscb will continue in an undefined manner.
- This function is provided as an incremental alternative to bsplits that
+ This function is provided as an incremental alternative to bsplits that
is abortable and which does not impose additional memory allocation.
..........................................................................
extern int bsplitstrcb (const_bstring str, const_bstring splitStr, int pos,
@@ -1349,13 +1349,13 @@
is abortable and which does not impose additional memory allocation.
..........................................................................
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 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
+ 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.
@@ -1360,11 +1360,11 @@
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,
+ 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.
@@ -1369,9 +1369,9 @@
otherwise bsplitscb will continue in an undefined manner.
- This function is provided as an incremental alternative to bsplitstr that
+ 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, ...);
@@ -1372,11 +1372,11 @@
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,
+ 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.
@@ -1381,6 +1381,6 @@
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
+ 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:
@@ -1385,6 +1385,6 @@
the bstring:
- /* b1->data needs to be '\0' terminated, so tagbstrings generated
+ /* b1->data needs to be '\0' terminated, so tagbstrings generated
by blk2tbstr () might not be suitable. */
b0 = bformat ("Hello, %s", b1->data);
@@ -1388,10 +1388,10 @@
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
+ 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, ...);
@@ -1392,12 +1392,12 @@
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
+ 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.
@@ -1402,6 +1402,6 @@
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
+ 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:
@@ -1406,4 +1406,4 @@
the bstring:
- /* b1->data needs to be '\0' terminated, so tagbstrings generated
+ /* b1->data needs to be '\0' terminated, so tagbstrings generated
by blk2tbstr () might not be suitable. */
@@ -1409,10 +1409,10 @@
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
+ 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, ...);
@@ -1413,11 +1413,11 @@
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
+ 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.
@@ -1422,6 +1422,6 @@
'\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
+ 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:
@@ -1426,4 +1426,4 @@
the bstring:
- /* b1->data needs to be '\0' terminated, so tagbstrings generated
+ /* b1->data needs to be '\0' terminated, so tagbstrings generated
by blk2tbstr () might not be suitable. */
@@ -1429,10 +1429,10 @@
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
+ 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);
@@ -1433,14 +1433,14 @@
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
+ 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
@@ -1442,11 +1442,11 @@
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
+ 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
@@ -1450,7 +1450,7 @@
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
+ 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.
@@ -1455,7 +1455,7 @@
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
+ 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.
@@ -1460,8 +1460,8 @@
engine for the bvformata macro.
- Note that if the BSTRLIB_NOVSNP macro has been set when bstrlib has been
+ 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);
@@ -1463,8 +1463,8 @@
compiled the bvcformata function is not present.
..........................................................................
extern bstring bread (bNread readPtr, void * parm);
- typedef size_t (* bNread) (void *buff, size_t elsize, size_t nelem,
+ typedef size_t (* bNread) (void *buff, size_t elsize, size_t nelem,
void *parm);
@@ -1469,8 +1469,8 @@
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*
+ 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.)
@@ -1475,11 +1475,11 @@
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
+ 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);
@@ -1480,10 +1480,10 @@
section below.
..........................................................................
extern int breada (bstring b, bNread readPtr, void * parm);
- Read an entire stream and append it to a bstring, verbatum. Behaves
+ Read an entire stream and append it to a bstring, verbatum. Behaves
like bread, except that it appends it results to the bstring b.
BSTR_ERR is returned on error, otherwise 0 is returned.
@@ -1495,13 +1495,13 @@
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
+ 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
@@ -1505,7 +1505,7 @@
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
+ 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
@@ -1509,8 +1509,8 @@
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
+ 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:
@@ -1518,11 +1518,11 @@
fp = fopen ( ... );
if (fp) b = bgets ((bNgetc) fgetc, fp, '\n');
- (Note that only one terminator character can be used, and that '\0' is
- not assumed to terminate the stream in addition to the terminator
+ (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.)
..........................................................................
extern int bgetsa (bstring b, bNgetc getcPtr, void * parm, char terminator);
@@ -1523,11 +1523,11 @@
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 it results to the bstring b. The value 1 is
+ 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.
@@ -1536,8 +1536,8 @@
extern 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
+ 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.
@@ -1545,7 +1545,7 @@
..........................................................................
extern 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
+
+ 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.
@@ -1551,5 +1551,5 @@
library streaming functions.
-
+
..........................................................................
extern void * bsclose (struct bStream * s);
@@ -1553,9 +1553,9 @@
..........................................................................
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
+
+ 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.
..........................................................................
@@ -1563,10 +1563,10 @@
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
+ 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);
@@ -1568,7 +1568,7 @@
this function returns with the previous length.
..........................................................................
extern int bsreadln (bstring r, struct bStream * s, char terminator);
-
+
Read a bstring terminated by the terminator character or the end of the
@@ -1574,4 +1574,4 @@
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
+ 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
@@ -1576,10 +1576,10 @@
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
+ 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);
@@ -1581,7 +1581,7 @@
speed streams, this function can perform significantly faster than bgets.
..........................................................................
extern int bsreadlna (bstring r, struct bStream * s, char terminator);
-
+
Read a bstring terminated by the terminator character or the end of the
@@ -1587,4 +1587,4 @@
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
+ 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
@@ -1589,11 +1589,11 @@
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
+ 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);
@@ -1594,16 +1594,16 @@
speed streams, this function can perform significantly faster than bgets.
..........................................................................
extern int bsreadlns (bstring r, struct bStream * s, bstring terminators);
- 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
+ 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.
..........................................................................
extern int bsreadlnsa (bstring r, struct bStream * s, bstring terminators);
@@ -1604,16 +1604,16 @@
operations.
..........................................................................
extern int bsreadlnsa (bstring r, struct bStream * s, bstring terminators);
- 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
+ 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.
..........................................................................
extern int bsread (bstring r, struct bStream * s, int n);
@@ -1615,9 +1615,9 @@
will be retained for subsequent read operations.
..........................................................................
extern int bsread (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. This function will read the minimum
+
+ 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
@@ -1623,7 +1623,7 @@
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
+ 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);
@@ -1625,11 +1625,11 @@
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 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
+
+ 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.
@@ -1635,3 +1635,3 @@
is returned, otherwise BSTR_OK is returned.
-
+
..........................................................................
@@ -1637,3 +1637,3 @@
..........................................................................
-
+
extern int bsunread (struct bStream * s, const_bstring b);
@@ -1639,9 +1639,9 @@
extern 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
+
+ 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.
..........................................................................
extern int bspeek (bstring r, const struct bStream * s);
@@ -1643,12 +1643,12 @@
stream.
..........................................................................
extern int bspeek (bstring r, const struct bStream * s);
-
- Return the number of currently buffered characters from the bStream that
+
+ 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.
..........................................................................
@@ -1650,14 +1650,14 @@
will be read prior to reads from the core stream, and append it to the
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 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
+ 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 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.
@@ -1662,9 +1662,9 @@
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
+ 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
@@ -1666,9 +1666,9 @@
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
+ 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
@@ -1672,5 +1672,5 @@
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
+ or other generic stream that in total size may otherwise exceed the
practical or desired memory available. As with the other split callback
@@ -1676,5 +1676,5 @@
practical or desired memory available. As with the other split callback
- based functions this is abortable and does not impose additional memory
+ based functions this is abortable and does not impose additional memory
allocation.
..........................................................................
@@ -1678,13 +1678,13 @@
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 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
+
+ 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 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.
@@ -1689,5 +1689,5 @@
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
+ 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
@@ -1693,5 +1693,5 @@
character. The cb function can act on the stream by causing the bStream
- pointer to move, and bssplitstrcb will continue by starting the next
+ 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
@@ -1695,7 +1695,7 @@
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
+ 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
@@ -1699,5 +1699,5 @@
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
+ or other generic stream that in total size may otherwise exceed the
practical or desired memory available. As with the other split callback
@@ -1703,3 +1703,3 @@
practical or desired memory available. As with the other split callback
- based functions this is abortable and does not impose additional memory
+ based functions this is abortable and does not impose additional memory
allocation.
@@ -1705,3 +1705,3 @@
allocation.
-
+
..........................................................................
@@ -1707,4 +1707,4 @@
..........................................................................
-
+
extern int bseof (const struct bStream * s);
@@ -1709,9 +1709,9 @@
extern 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
+ 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.
@@ -1716,6 +1716,6 @@
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
+ 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
@@ -1727,8 +1727,8 @@
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
+ referenced multiple times. As with all macros, programmer care is
required to guard against unintended side effects.
int blengthe (const_bstring b, int err);
@@ -1731,11 +1731,11 @@
required to guard against unintended side effects.
int blengthe (const_bstring b, int err);
- Returns the length of the bstring. If the bstring is NULL err is
+ Returns the length of the bstring. If the bstring is NULL err is
returned.
..........................................................................
int blength (const_bstring b);
@@ -1736,13 +1736,13 @@
returned.
..........................................................................
int blength (const_bstring b);
- Returns the length of the bstring. If the bstring is NULL, the length
+ Returns the length of the bstring. If the bstring is NULL, the length
returned is 0.
..........................................................................
int bchare (const_bstring b, int p, int c);
@@ -1743,14 +1743,14 @@
returned is 0.
..........................................................................
int bchare (const_bstring b, int p, int c);
- Returns the p'th character of the bstring b. If the position p refers to
- a position that does not exist in the bstring or the bstring is NULL,
+ Returns the p'th character of the bstring b. If the position p refers to
+ a position that does not exist in the bstring or the bstring is NULL,
then c is returned.
..........................................................................
char bchar (const_bstring b, int p);
@@ -1751,11 +1751,11 @@
then c is returned.
..........................................................................
char bchar (const_bstring b, int p);
- Returns the p'th character of the bstring b. If the position p refers to
- a position that does not exist in the bstring or the bstring is NULL,
+ Returns the p'th character of the bstring b. If the position p refers to
+ a position that does not exist in the bstring or the bstring is NULL,
then '\0' is returned.
..........................................................................
@@ -1776,10 +1776,10 @@
char * bdataofse (bstring b, int ofs, char * err);
- Returns the char * data portion of the bstring b offset by ofs. If b is
+ 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);
@@ -1780,13 +1780,13 @@
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
+ Returns the char * data portion of the bstring b offset by ofs. If b is
NULL, NULL is returned.
..........................................................................
struct tagbstring var = bsStatic ("...");
@@ -1787,9 +1787,9 @@
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
+ 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
@@ -1795,4 +1795,4 @@
not need to be freed or destroyed. Note that this macro is only well
- defined for string literal arguments. For more general string pointers,
+ defined for string literal arguments. For more general string pointers,
use the btfromcstr macro.
@@ -1797,11 +1797,11 @@
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
+ 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 ("...")
@@ -1802,12 +1802,12 @@
tagbstring has no effect.
..........................................................................
<void * blk, int len> <- bsStaticBlkParms ("...")
- The bsStaticBlkParms macro emits a pair of comma seperated parameters
- corresponding to the block parameters for the block functions in Bstrlib
- (i.e., blk2bstr, bcatblk, blk2tbstr, bisstemeqblk, bisstemeqcaselessblk.)
+ The bsStaticBlkParms macro emits a pair of comma seperated 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:
@@ -1815,7 +1815,7 @@
bstring b = blk2bstr (bsStaticBlkParms ("Fast init. "));
bcatblk (b, bsStaticBlkParms ("No frills fast concatenation."));
- These are faster than using bfromcstr() and bcatcstr() respectively
+ 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 seperate struct tagbstring declarations for
holding the output of a bsStatic() macro are not required.
@@ -1824,8 +1824,8 @@
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.
+ 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.
@@ -1830,12 +1830,12 @@
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 writeable (though this
+ 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 writeable (though this
requires that s be obtained from a function compatible with malloc.)
..........................................................................
void btfromblk (struct tagbstring& t, void * s, int len);
@@ -1836,12 +1836,12 @@
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
+ 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.
@@ -1846,9 +1846,9 @@
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 writeable (though this
+ 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 writeable (though this
requires that s be obtained from a function compatible with malloc.)
..........................................................................
@@ -1856,9 +1856,9 @@
void btfromblkltrimws (struct tagbstring& t, void * s, int len);
Fill in the 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
+ 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.
@@ -1863,8 +1863,8 @@
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
+ 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.
..........................................................................
@@ -1872,9 +1872,9 @@
void btfromblkrtrimws (struct tagbstring& t, void * s, int len);
Fill in the 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
+ 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.
@@ -1879,8 +1879,8 @@
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
+ 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.
..........................................................................
@@ -1888,9 +1888,9 @@
void btfromblktrimws (struct tagbstring& t, void * s, int len);
Fill in the 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
+ 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.
@@ -1895,8 +1895,8 @@
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
+ 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.
..........................................................................
@@ -1905,9 +1905,9 @@
Fill the tagbstring t with the substring 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
+ 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.
@@ -1912,7 +1912,7 @@
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
+ 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.
@@ -1922,10 +1922,10 @@
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
+ 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:
@@ -1938,12 +1938,12 @@
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
+ 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);
@@ -1944,11 +1944,11 @@
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
+ 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: bstrings which are write protected cannot be destroyed via bdestroy.
@@ -1960,5 +1960,5 @@
void bwriteallow (struct tagbstring& t);
- Allow bstring to be written to via the bstrlib API. Note that such an
+ 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
@@ -1964,4 +1964,4 @@
action makes the bstring both writable and destroyable. If the bstring is
- not legitimately writable (as is the case for struct tagbstrings
+ not legitimately writable (as is the case for struct tagbstrings
initialized with a bsStatic value), the results of this are undefined.
@@ -1966,7 +1966,7 @@
initialized with a bsStatic value), the results of this are undefined.
- Note that invoking the bwriteallow macro may increase the number of
- reallocs by one more than necessary for every call to bwriteallow
+ Note that invoking the bwriteallow macro may increase the number of
+ reallocs by one more than necessary for every call to bwriteallow
interleaved with any bstring API which writes to this bstring.
..........................................................................
@@ -1983,6 +1983,6 @@
The bstest module is just a unit test for the bstrlib module. For correct
implementations of bstrlib, it should execute with 0 failures being reported.
This test should be utilized if modifications/customizations to bstrlib have
-been performed. It tests each core bstrlib function with bstrings of every
-mode (read-only, NULL, static and mutable) and ensures that the expected
+been performed. It tests each core bstrlib function with bstrings of every
+mode (read-only, NULL, static and mutable) and ensures that the expected
semantics are observed (including results that should indicate an error). It
@@ -1988,5 +1988,5 @@
semantics are observed (including results that should indicate an error). It
-also tests for aliasing support. Passing bstest is a necessary but not a
+also tests for aliasing support. Passing bstest is a necessary but not a
sufficient condition for ensuring the correctness of the bstrlib module.
@@ -1994,8 +1994,8 @@
---------------
The test module is just a unit test for the bstrwrap module. For correct
-implementations of bstrwrap, it should execute with 0 failures being
-reported. This test should be utilized if modifications/customizations to
-bstrwrap have been performed. It tests each core bstrwrap function with
-CBStrings write protected or not and ensures that the expected semantics are
+implementations of bstrwrap, it should execute with 0 failures being
+reported. This test should be utilized if modifications/customizations to
+bstrwrap have been performed. It tests each core bstrwrap function with
+CBStrings write protected or not and ensures that the expected semantics are
observed (including expected exceptions.) Note that exceptions cannot be
@@ -2001,5 +2001,5 @@
observed (including expected exceptions.) Note that exceptions cannot be
-disabled to run this test. Passing test is a necessary but not a sufficient
+disabled to run this test. Passing test is a necessary but not a sufficient
condition for ensuring the correctness of the bstrwrap module.
===============================================================================
@@ -2007,7 +2007,7 @@
Using Bstring and CBString as an alternative to the C library
-------------------------------------------------------------
-First let us give a table of C library functions and the alternative bstring
+First let us give a table of C library functions and the alternative bstring
functions and CBString methods that should be used instead of them.
C-library Bstring alternative CBString alternative
@@ -2039,5 +2039,5 @@
strspnp use strspn use strspn
ungetc bsunread bsunread
-The top 9 C functions listed here are troublesome in that they impose memory
+The top 9 C functions listed here are troublesome in that they impose memory
management in the calling function. The Bstring and CBstring interfaces have
@@ -2043,7 +2043,7 @@
management in the calling function. The Bstring and CBstring interfaces have
-built-in memory management, so there is far less code with far less potential
-for buffer overrun problems. strtok can only be reliably called as a "leaf"
+built-in memory management, so there is far less code with far less potential
+for buffer overrun problems. strtok can only be reliably called as a "leaf"
calculation, since it (quite bizarrely) maintains hidden internal state. And
gets is well known to be broken no matter what. The Bstrlib alternatives do
not suffer from those sorts of problems.
@@ -2046,8 +2046,8 @@
calculation, since it (quite bizarrely) maintains hidden internal state. And
gets is well known to be broken no matter what. The Bstrlib alternatives do
not suffer from those sorts of problems.
-The substitute for strncat can be performed with higher performance by using
+The substitute for strncat can be performed with higher performance by using
the blk2tbstr macro to create a presized second operand for bconcat.
C-library Bstring alternative CBString alternative
@@ -2063,7 +2063,7 @@
Remember that Bstring (and CBstring) functions will automatically append the
'\0' character to the character data buffer. So by simply accessing the data
-buffer directly, ordinary C string library functions can be called directly
+buffer directly, ordinary C string library functions can be called directly
on them. Note that bstrcmp is not the same as memcmp in exactly the same way
that strcmp is not the same as memcmp.
@@ -2072,11 +2072,11 @@
fread balloc + fread ::alloc + fread
fgets balloc + fgets ::alloc + fgets
-These are odd ones because of the exact sizing of the buffer required. The
-Bstring and CBString alternatives requires that the buffers are forced to
-hold at least the prescribed length, then just use fread or fgets directly.
-However, typically the automatic memory management of Bstring and CBstring
-will make the typical use of fgets and fread to read specifically sized
+These are odd ones because of the exact sizing of the buffer required. The
+Bstring and CBString alternatives requires that the buffers are forced to
+hold at least the prescribed length, then just use fread or fgets directly.
+However, typically the automatic memory management of Bstring and CBstring
+will make the typical use of fgets and fread to read specifically sized
strings unnecessary.
Implementation Choices
@@ -2086,10 +2086,10 @@
.........
The bstring library has more overhead versus straight char buffers for most
-functions. This overhead is essentially just the memory management and
-string header allocation. This overhead usually only shows up for small
+functions. This overhead is essentially just the memory management and
+string header allocation. This overhead usually only shows up for small
string manipulations. The performance loss has to be considered in
light of the following:
1) What would be the performance loss of trying to write this management
code in one's own application?
@@ -2091,10 +2091,10 @@
string manipulations. The performance loss has to be considered in
light of the following:
1) What would be the performance loss of trying to write this management
code in one's own application?
-2) Since the bstring library source code is given, a sufficiently powerful
- modern inlining globally optimizing compiler can remove function call
+2) Since the bstring library source code is given, a sufficiently powerful
+ modern inlining globally optimizing compiler can remove function call
overhead.
Since the data type is exposed, a developer can replace any unsatisfactory
@@ -2098,11 +2098,11 @@
overhead.
Since the data type is exposed, a developer can replace any unsatisfactory
-function with their own inline implementation. And that is besides the main
-point of what the better string library is mainly meant to provide. Any
-overhead lost has to be compared against the value of the safe abstraction
+function with their own inline implementation. And that is besides the main
+point of what the better string library is mainly meant to provide. Any
+overhead lost has to be compared against the value of the safe abstraction
for coupling memory management and string functionality.
Performance of the C interface:
...............................
@@ -2104,8 +2104,8 @@
for coupling memory management and string functionality.
Performance of the C interface:
...............................
-The algorithms used have performance advantages versus the analogous C
+The algorithms used have performance advantages versus the analogous C
library functions. For example:
@@ -2110,12 +2110,12 @@
library functions. For example:
-1. bfromcstr/blk2str/bstrcpy versus strcpy/strdup. By using memmove instead
- of strcpy, the break condition of the copy loop is based on an independent
- counter (that should be allocated in a register) rather than having to
- check the results of the load. Modern out-of-order executing CPUs can
- parallelize the final branch mis-predict penality with the loading of the
- source string. Some CPUs will also tend to have better built-in hardware
- support for counted memory moves than load-compare-store. (This is a
+1. bfromcstr/blk2str/bstrcpy versus strcpy/strdup. By using memmove instead
+ of strcpy, the break condition of the copy loop is based on an independent
+ counter (that should be allocated in a register) rather than having to
+ check the results of the load. Modern out-of-order executing CPUs can
+ parallelize the final branch mis-predict penality with the loading of the
+ source string. Some CPUs will also tend to have better built-in hardware
+ support for counted memory moves than load-compare-store. (This is a
minor, but non-zero gain.)
2. biseq versus strcmp. If the strings are unequal in length, bsiseq will
return in O(1) time. If the strings are aliased, or have aliased data
@@ -2119,8 +2119,8 @@
minor, but non-zero gain.)
2. biseq versus strcmp. If the strings are unequal in length, bsiseq will
return in O(1) time. If the strings are aliased, or have aliased data
- buffers, biseq will return in O(1) time. strcmp will always be O(k),
- where k is the length of the common prefix or the whole string if they are
+ buffers, biseq will return in O(1) time. strcmp will always be O(k),
+ where k is the length of the common prefix or the whole string if they are
identical.
3. ->slen versus strlen. ->slen is obviously always O(1), while strlen is
always O(n) where n is the length of the string.
@@ -2124,11 +2124,11 @@
identical.
3. ->slen versus strlen. ->slen is obviously always O(1), while strlen is
always O(n) where n is the length of the string.
-4. bconcat versus strcat. Both rely on precomputing the length of the
- destination string argument, which will favor the bstring library. On
+4. bconcat versus strcat. Both rely on precomputing the length of the
+ destination string argument, which will favor the bstring library. On
iterated concatenations the performance difference can be enormous.
5. bsreadln versus fgets. The bsreadln function reads large blocks at a time
from the given stream, then parses out lines from the buffers directly.
Some C libraries will implement fgets as a loop over single fgetc calls.
Testing indicates that the bsreadln approach can be several times faster
for fast stream devices (such as a file that has been entirely cached.)
@@ -2129,9 +2129,9 @@
iterated concatenations the performance difference can be enormous.
5. bsreadln versus fgets. The bsreadln function reads large blocks at a time
from the given stream, then parses out lines from the buffers directly.
Some C libraries will implement fgets as a loop over single fgetc calls.
Testing indicates that the bsreadln approach can be several times faster
for fast stream devices (such as a file that has been entirely cached.)
-6. bsplits/bsplitscb versus strspn. Accelerators for the set of match
+6. bsplits/bsplitscb versus strspn. Accelerators for the set of match
characters are generated only once.
7. binstr versus strstr. The binstr implementation unrolls the loops to
@@ -2136,6 +2136,6 @@
characters are generated only once.
7. binstr versus strstr. The binstr implementation unrolls the loops to
- help reduce loop overhead. This will matter if the target string is
+ help reduce loop overhead. This will matter if the target string is
long and source string is not found very early in the target string.
With strstr, while it is possible to unroll the source contents, it is
not possible to do so with the destination contents in a way that is
@@ -2148,5 +2148,5 @@
is no way to do this without computing the length of the string with
strlen.
-Practical testing indicates that in general Bstrlib is never signifcantly
+Practical testing indicates that in general Bstrlib is never signifcantly
slower than the C library for common operations, while very often having a
@@ -2152,8 +2152,8 @@
slower than the C library for common operations, while very often having a
-performance advantage that ranges from significant to massive. Even for
-functions like b(n)inchr versus str(c)spn() (where, in theory, there is no
-advantage for the Bstrlib architecture) the performance of Bstrlib is vastly
+performance advantage that ranges from significant to massive. Even for
+functions like b(n)inchr versus str(c)spn() (where, in theory, there is no
+advantage for the Bstrlib architecture) the performance of Bstrlib is vastly
superior to most tested C library implementations.
Some of Bstrlib's extra functionality also lead to inevitable performance
advantages over typical C solutions. For example, using the blk2tbstr macro,
@@ -2156,6 +2156,6 @@
superior to most tested C library implementations.
Some of Bstrlib's extra functionality also lead to inevitable performance
advantages over typical C solutions. For example, using the blk2tbstr macro,
-one can (in O(1) time) generate an internal substring by reference while not
+one can (in O(1) time) generate an internal substring by reference while not
disturbing the original string. If disturbing the original string is not an
@@ -2161,6 +2161,6 @@
disturbing the original string. If disturbing the original string is not an
-option, typically, a comparable char * solution would have to make a copy of
-the substring to provide similar functionality. Another example is reverse
-character set scanning -- the str(c)spn functions only scan in a forward
+option, typically, a comparable char * solution would have to make a copy of
+the substring to provide similar functionality. Another example is reverse
+character set scanning -- the str(c)spn functions only scan in a forward
direction which can complicate some parsing algorithms.
@@ -2165,7 +2165,7 @@
direction which can complicate some parsing algorithms.
-Where high performance char * based algorithms are available, Bstrlib can
-still leverage them by accessing the ->data field on bstrings. So
+Where high performance char * based algorithms are available, Bstrlib can
+still leverage them by accessing the ->data field on bstrings. So
realistically Bstrlib can never be significantly slower than any standard
'\0' terminated char * based solutions.
@@ -2173,12 +2173,12 @@
.................................
The C++ interface has been designed with an emphasis on abstraction and safety
-first. However, since it is substantially a wrapper for the C bstring
-functions, for longer strings the performance comments described in the
-"Performance of the C interface" section above still apply. Note that the
-(CBString *) type can be directly cast to a (bstring) type, and passed as
-parameters to the C functions (though a CBString must never be passed to
+first. However, since it is substantially a wrapper for the C bstring
+functions, for longer strings the performance comments described in the
+"Performance of the C interface" section above still apply. Note that the
+(CBString *) type can be directly cast to a (bstring) type, and passed as
+parameters to the C functions (though a CBString must never be passed to
bdestroy.)
Probably the most controversial choice is performing full bounds checking on
the [] operator. This decision was made because 1) the fast alternative of
@@ -2181,14 +2181,14 @@
bdestroy.)
Probably the most controversial choice is performing full bounds checking on
the [] operator. This decision was made because 1) the fast alternative of
-not bounds checking is still available by first casting the CBString to a
-(const char *) buffer or to a (struct tagbstring) then derefencing .data and
-2) because the lack of bounds checking is seen as one of the main weaknesses
-of C/C++ versus other languages. This check being done on every access leads
-to individual character extraction being actually slower than other languages
-in this one respect (other language's compilers will normally dedicate more
-resources on hoisting or removing bounds checking as necessary) but otherwise
+not bounds checking is still available by first casting the CBString to a
+(const char *) buffer or to a (struct tagbstring) then derefencing .data and
+2) because the lack of bounds checking is seen as one of the main weaknesses
+of C/C++ versus other languages. This check being done on every access leads
+to individual character extraction being actually slower than other languages
+in this one respect (other language's compilers will normally dedicate more
+resources on hoisting or removing bounds checking as necessary) but otherwise
bring C++ up to the level of other languages in terms of functionality.
It is common for other C++ libraries to leverage the abstractions provided by
@@ -2192,5 +2192,5 @@
bring C++ up to the level of other languages in terms of functionality.
It is common for other C++ libraries to leverage the abstractions provided by
-C++ to use reference counting and "copy on write" policies. While these
+C++ to use reference counting and "copy on write" policies. While these
techniques can speed up some scenarios, they impose a problem with respect to
@@ -2196,4 +2196,4 @@
techniques can speed up some scenarios, they impose a problem with respect to
-thread safety. bstrings and CBStrings can be properly protected with
+thread safety. bstrings and CBStrings can be properly protected with
"per-object" mutexes, meaning that two bstrlib calls can be made and execute
simultaneously, so long as the bstrings and CBstrings are distinct. With a
@@ -2198,7 +2198,7 @@
"per-object" mutexes, meaning that two bstrlib calls can be made and execute
simultaneously, so long as the bstrings and CBstrings are distinct. With a
-reference count and alias before copy on write policy, global mutexes are
-required that prevent multiple calls to the strings library to execute
+reference count and alias before copy on write policy, global mutexes are
+required that prevent multiple calls to the strings library to execute
simultaneously regardless of whether or not the strings represent the same
string.
@@ -2202,14 +2202,14 @@
simultaneously regardless of whether or not the strings represent the same
string.
-One interesting trade off in CBString is that the default constructor is not
-trivial. I.e., it always prepares a ready to use memory buffer. The purpose
-is to ensure that there is a uniform internal composition for any functioning
-CBString that is compatible with bstrings. It also means that the other
-methods in the class are not forced to perform "late initialization" checks.
-In the end it means that construction of CBStrings are slower than other
-comparable C++ string classes. Initial testing, however, indicates that
-CBString outperforms std::string and MFC's CString, for example, in all other
-operations. So to work around this weakness it is recommended that CBString
+One interesting trade off in CBString is that the default constructor is not
+trivial. I.e., it always prepares a ready to use memory buffer. The purpose
+is to ensure that there is a uniform internal composition for any functioning
+CBString that is compatible with bstrings. It also means that the other
+methods in the class are not forced to perform "late initialization" checks.
+In the end it means that construction of CBStrings are slower than other
+comparable C++ string classes. Initial testing, however, indicates that
+CBString outperforms std::string and MFC's CString, for example, in all other
+operations. So to work around this weakness it is recommended that CBString
declarations be pushed outside of inner loops.
@@ -2214,4 +2214,4 @@
declarations be pushed outside of inner loops.
-Practical testing indicates that with the exception of the caveats given
+Practical testing indicates that with the exception of the caveats given
above (constructors and safe index character manipulations) the C++ API for
@@ -2217,9 +2217,9 @@
above (constructors and safe index character manipulations) the C++ API for
-Bstrlib generally outperforms popular standard C++ string classes. Amongst
-the standard libraries and compilers, the quality of concatenation operations
+Bstrlib generally outperforms popular standard C++ string classes. Amongst
+the standard libraries and compilers, the quality of concatenation operations
varies wildly and very little care has gone into search functions. Bstrlib
dominates those performance benchmarks.
Memory management:
..................
@@ -2220,15 +2220,15 @@
varies wildly and very little care has gone into search functions. Bstrlib
dominates those performance benchmarks.
Memory management:
..................
-The bstring functions which write and modify bstrings will automatically
-reallocate the backing memory for the char buffer whenever it is required to
-grow. The algorithm for resizing chosen is to snap up to sizes that are a
-power of two which are sufficient to hold the intended new size. Memory
-reallocation is not performed when the required size of the buffer is
-decreased. This behavior can be relied on, and is necessary to make the
-behaviour of balloc deterministic. This trades off additional memory usage
+The bstring functions which write and modify bstrings will automatically
+reallocate the backing memory for the char buffer whenever it is required to
+grow. The algorithm for resizing chosen is to snap up to sizes that are a
+power of two which are sufficient to hold the intended new size. Memory
+reallocation is not performed when the required size of the buffer is
+decreased. This behavior can be relied on, and is necessary to make the
+behaviour of balloc deterministic. This trades off additional memory usage
for decreasing the frequency for required reallocations:
@@ -2233,5 +2233,5 @@
for decreasing the frequency for required reallocations:
-1. For any bstring whose size never exceeds n, its buffer is not ever
+1. For any bstring whose size never exceeds n, its buffer is not ever
reallocated more than log_2(n) times for its lifetime.
2. For any bstring whose size never exceeds n, its buffer is never more than
@@ -2236,5 +2236,5 @@
reallocated more than log_2(n) times for its lifetime.
2. For any bstring whose size never exceeds n, its buffer is never more than
- 2*(n+1) in length. (The extra characters beyond 2*n are to allow for the
+ 2*(n+1) in length. (The extra characters beyond 2*n are to allow for the
implicit '\0' which is always added by the bstring modifying functions.)
@@ -2239,7 +2239,7 @@
implicit '\0' which is always added by the bstring modifying functions.)
-Decreasing the buffer size when the string decreases in size would violate 1)
-above and in real world case lead to pathological heap thrashing. Similarly,
-allocating more tightly than "least power of 2 greater than necessary" would
+Decreasing the buffer size when the string decreases in size would violate 1)
+above and in real world case lead to pathological heap thrashing. Similarly,
+allocating more tightly than "least power of 2 greater than necessary" would
lead to a violation of 1) and have the same potential for heap thrashing.
@@ -2244,8 +2244,8 @@
lead to a violation of 1) and have the same potential for heap thrashing.
-Property 2) needs emphasizing. Although the memory allocated is always a
-power of 2, for a bstring that grows linearly in size, its buffer memory also
-grows linearly, not exponentially. The reason is that the amount of extra
-space increases with each reallocation, which decreases the frequency of
+Property 2) needs emphasizing. Although the memory allocated is always a
+power of 2, for a bstring that grows linearly in size, its buffer memory also
+grows linearly, not exponentially. The reason is that the amount of extra
+space increases with each reallocation, which decreases the frequency of
future reallocations.
@@ -2250,8 +2250,8 @@
future reallocations.
-Obviously, given that bstring writing functions may reallocate the data
-buffer backing the target bstring, one should not attempt to cache the data
-buffer address and use it after such bstring functions have been called.
-This includes making reference struct tagbstrings which alias to a writable
+Obviously, given that bstring writing functions may reallocate the data
+buffer backing the target bstring, one should not attempt to cache the data
+buffer address and use it after such bstring functions have been called.
+This includes making reference struct tagbstrings which alias to a writable
bstring.
@@ -2256,8 +2256,8 @@
bstring.
-balloc or bfromcstralloc can be used to preallocate the minimum amount of
-space used for a given bstring. This will reduce even further the number of
-times the data portion is reallocated. If the length of the string is never
-more than one less than the memory length then there will be no further
+balloc or bfromcstralloc can be used to preallocate the minimum amount of
+space used for a given bstring. This will reduce even further the number of
+times the data portion is reallocated. If the length of the string is never
+more than one less than the memory length then there will be no further
reallocations.
@@ -2262,7 +2262,7 @@
reallocations.
-Note that invoking the bwriteallow macro may increase the number of reallocs
-by one more than necessary for every call to bwriteallow interleaved with any
+Note that invoking the bwriteallow macro may increase the number of reallocs
+by one more than necessary for every call to bwriteallow interleaved with any
bstring API which writes to this bstring.
The library does not use any mechanism for automatic clean up for the C API.
@@ -2272,10 +2272,10 @@
Constant and static tagbstrings:
................................
-A struct tagbstring can be write protected from any bstrlib function using
-the bwriteprotect macro. A write protected struct tagbstring can then be
-reset to being writable via the bwriteallow macro. There is, of course, no
-protection from attempts to directly access the bstring members. Modifying a
+A struct tagbstring can be write protected from any bstrlib function using
+the bwriteprotect macro. A write protected struct tagbstring can then be
+reset to being writable via the bwriteallow macro. There is, of course, no
+protection from attempts to directly access the bstring members. Modifying a
bstring which is write protected by direct access has undefined behavior.
static struct tagbstrings can be declared via the bsStatic macro. They are
@@ -2279,13 +2279,13 @@
bstring which is write protected by direct access has undefined behavior.
static struct tagbstrings can be declared via the bsStatic macro. They are
-considered permanently unwritable. Such struct tagbstrings's are declared
-such that attempts to write to it are not well defined. Invoking either
-bwriteallow or bwriteprotect on static struct tagbstrings has no effect.
-
-struct tagbstring's initialized via btfromcstr or blk2tbstr are protected by
-default but can be made writeable via the bwriteallow macro. If bwriteallow
-is called on such struct tagbstring's, it is the programmer's responsibility
+considered permanently unwritable. Such struct tagbstrings's are declared
+such that attempts to write to it are not well defined. Invoking either
+bwriteallow or bwriteprotect on static struct tagbstrings has no effect.
+
+struct tagbstring's initialized via btfromcstr or blk2tbstr are protected by
+default but can be made writeable via the bwriteallow macro. If bwriteallow
+is called on such struct tagbstring's, it is the programmer's responsibility
to ensure that:
1) the buffer supplied was allocated from the heap.
@@ -2293,8 +2293,8 @@
also been allocated from the heap.)
3) free is called on the buffer to reclaim its memory.
-bwriteallow and bwriteprotect can be invoked on ordinary bstrings (they have
-to be dereferenced with the (*) operator to get the levels of indirection
+bwriteallow and bwriteprotect can be invoked on ordinary bstrings (they have
+to be dereferenced with the (*) operator to get the levels of indirection
correct) to give them write protection.
Buffer declaration:
@@ -2303,11 +2303,11 @@
The memory buffer is actually declared "unsigned char *" instead of "char *".
The reason for this is to trigger compiler warnings whenever uncasted char
buffers are assigned to the data portion of a bstring. This will draw more
-diligent programmers into taking a second look at the code where they
-have carelessly left off the typically required cast. (Research from
-AT&T/Lucent indicates that additional programmer eyeballs is one of the most
+diligent programmers into taking a second look at the code where they
+have carelessly left off the typically required cast. (Research from
+AT&T/Lucent indicates that additional programmer eyeballs is one of the most
effective mechanisms at ferreting out bugs.)
Function pointers:
..................
@@ -2309,20 +2309,20 @@
effective mechanisms at ferreting out bugs.)
Function pointers:
..................
-The bgets, bread and bStream functions use function pointers to obtain
-strings from data streams. The function pointer declarations have been
-specifically chosen to be compatible with the fgetc and fread functions.
-While this may seem to be a convoluted way of implementing fgets and fread
-style functionality, it has been specifically designed this way to ensure
-that there is no dependency on a single narrowly defined set of device
-interfaces, such as just stream I/O. In the embedded world, its quite
-possible to have environments where such interfaces may not exist in the
-standard C library form. Furthermore, the generalization that this opens up
-allows for more sophisticated uses for these functions (performing an fgets
-like function on a socket, for example.) By using function pointers, it also
-allows such abstract stream interfaces to be created using the bstring library
+The bgets, bread and bStream functions use function pointers to obtain
+strings from data streams. The function pointer declarations have been
+specifically chosen to be compatible with the fgetc and fread functions.
+While this may seem to be a convoluted way of implementing fgets and fread
+style functionality, it has been specifically designed this way to ensure
+that there is no dependency on a single narrowly defined set of device
+interfaces, such as just stream I/O. In the embedded world, its quite
+possible to have environments where such interfaces may not exist in the
+standard C library form. Furthermore, the generalization that this opens up
+allows for more sophisticated uses for these functions (performing an fgets
+like function on a socket, for example.) By using function pointers, it also
+allows such abstract stream interfaces to be created using the bstring library
itself while not creating a circular dependency.
Use of int's for sizes:
@@ -2330,9 +2330,9 @@
This is just a recognition that 16bit platforms with requirements for strings
that are larger than 64K and 32bit+ platforms with requirements for strings
-that are larger than 4GB are pretty marginal. The main focus is for 32bit
-platforms, and emerging 64bit platforms with reasonable < 4GB string
-requirements. Using ints allows for negative values which has meaning
+that are larger than 4GB are pretty marginal. The main focus is for 32bit
+platforms, and emerging 64bit platforms with reasonable < 4GB string
+requirements. Using ints allows for negative values which has meaning
internally to bstrlib.
Semantic consideration:
@@ -2352,6 +2352,6 @@
bconcat (a, b); /* Double a and b, t is now undefined. */
bdestroy (a); /* Destroy the contents of both a and b. */
-Variables of type bstring are really just references that point to real
-bstring objects. The equal operator (=) creates aliases, and the asterisk
+Variables of type bstring are really just references that point to real
+bstring objects. The equal operator (=) creates aliases, and the asterisk
dereference operator (*) creates a kind of alias to the current instance (which
@@ -2357,6 +2357,6 @@
dereference operator (*) creates a kind of alias to the current instance (which
-is generally not useful for any purpose.) Using bstrcpy() is the correct way
-of creating duplicate instances. The ampersand operator (&) is useful for
-creating aliases to struct tagbstrings (remembering that constructed struct
+is generally not useful for any purpose.) Using bstrcpy() is the correct way
+of creating duplicate instances. The ampersand operator (&) is useful for
+creating aliases to struct tagbstrings (remembering that constructed struct
tagbstrings are not writable by default.)
@@ -2361,8 +2361,8 @@
tagbstrings are not writable by default.)
-CBStrings use complete copy semantics for the equal operator (=), and thus do
-not have these sorts of issues.
+CBStrings use complete copy semantics for the equal operator (=), and thus do
+not have these sorts of issues.
Debugging:
..........
@@ -2365,9 +2365,9 @@
Debugging:
..........
-Bstrings have a simple, exposed definition and construction, and the library
-itself is open source. So most debugging is going to be fairly straight-
+Bstrings have a simple, exposed definition and construction, and the library
+itself is open source. So most debugging is going to be fairly straight-
forward. But the memory for bstrings come from the heap, which can often be
corrupted indirectly, and it might not be obvious what has happened even from
direct examination of the contents in a debugger or a core dump. There are
@@ -2376,11 +2376,11 @@
calls to malloc, realloc, calloc, free, memcpy, memmove and/or other calls
by overriding them with macro definitions.
-Although the user could hack on the Bstrlib sources directly as necessary to
-perform such an instrumentation, Bstrlib comes with a built-in mechanism for
-doing this. By defining the macro BSTRLIB_MEMORY_DEBUG and providing an
-include file named memdbg.h this will force the core Bstrlib modules to
-attempt to include this file. In such a file, macros could be defined which
+Although the user could hack on the Bstrlib sources directly as necessary to
+perform such an instrumentation, Bstrlib comes with a built-in mechanism for
+doing this. By defining the macro BSTRLIB_MEMORY_DEBUG and providing an
+include file named memdbg.h this will force the core Bstrlib modules to
+attempt to include this file. In such a file, macros could be defined which
overrides Bstrlib's useage of the C standard library.
Rather than calling malloc, realloc, free, memcpy or memmove directly, Bstrlib
@@ -2384,6 +2384,6 @@
overrides Bstrlib's useage of the C standard library.
Rather than calling malloc, realloc, free, memcpy or memmove directly, Bstrlib
-emits the macros bstr__alloc, bstr__realloc, bstr__free, bstr__memcpy and
+emits the macros bstr__alloc, bstr__realloc, bstr__free, bstr__memcpy and
bstr__memmove in their place respectively. By default these macros are simply
assigned to be equivalent to their corresponding C standard library function
@@ -2388,5 +2388,5 @@
bstr__memmove in their place respectively. By default these macros are simply
assigned to be equivalent to their corresponding C standard library function
-call. However, if they are given earlier macro definitions (via the back
+call. However, if they are given earlier macro definitions (via the back
door include file) they will not be given their default definition. In this
way Bstrlib's interface to the standard library can be changed but without
@@ -2391,6 +2391,6 @@
door include file) they will not be given their default definition. In this
way Bstrlib's interface to the standard library can be changed but without
-having to directly redefine or link standard library symbols (both of which
+having to directly redefine or link standard library symbols (both of which
are not strictly ANSI C compliant.)
An example definition might include:
@@ -2399,8 +2399,8 @@
which might help contextualize heap entries in a debugging environment.
-The NULL parameter and sanity checking of bstrings is part of the Bstrlib
-API, and thus Bstrlib itself does not present any different modes which would
+The NULL parameter and sanity checking of bstrings is part of the Bstrlib
+API, and thus Bstrlib itself does not present any different modes which would
correspond to "Debug" or "Release" modes. Bstrlib always contains mechanisms
which one might think of as debugging features, but retains the performance
and small memory footprint one would normally associate with release mode
@@ -2409,7 +2409,7 @@
Integration Microsoft's Visual Studio debugger:
...............................................
-Microsoft's Visual Studio debugger has a capability of customizable mouse
+Microsoft's Visual Studio debugger has a capability of customizable mouse
float over data type descriptions. This is accomplished by editting the
AUTOEXP.DAT file to include the following:
@@ -2431,5 +2431,5 @@
--------
Bstrlib does not come with explicit security features outside of its fairly
-comprehensive error detection, coupled with its strict semantic support.
+comprehensive error detection, coupled with its strict semantic support.
That is to say that certain common security problems, such as buffer overrun,
@@ -2435,4 +2435,4 @@
That is to say that certain common security problems, such as buffer overrun,
-constant overwrite, arbitrary truncation etc, are far less likely to happen
-inadvertently. Where it does help, Bstrlib maximizes its advantage by
+constant overwrite, arbitrary truncation etc, are far less likely to happen
+inadvertently. Where it does help, Bstrlib maximizes its advantage by
providing developers a simple adoption path that lets them leave less secure
@@ -2438,7 +2438,7 @@
providing developers a simple adoption path that lets them leave less secure
-string mechanisms behind. The library will not leave developers wanting, so
-they will be less likely to add new code using a less secure string library
+string mechanisms behind. The library will not leave developers wanting, so
+they will be less likely to add new code using a less secure string library
to add functionality that might be missing from Bstrlib.
That said there are a number of security ideas not addressed by Bstrlib:
@@ -2441,14 +2441,14 @@
to add functionality that might be missing from Bstrlib.
That said there are a number of security ideas not addressed by Bstrlib:
-1. Race condition exploitation (i.e., verifying a string's contents, then
-raising the privilege level and execute it as a shell command as two
-non-atomic steps) is well beyond the scope of what Bstrlib can provide. It
-should be noted that MFC's built-in string mutex actually does not solve this
-problem either -- it just removes immediate data corruption as a possible
-outcome of such exploit attempts (it can be argued that this is worse, since
-it will leave no trace of the exploitation). In general race conditions have
-to be dealt with by careful design and implementation; it cannot be assisted
+1. Race condition exploitation (i.e., verifying a string's contents, then
+raising the privilege level and execute it as a shell command as two
+non-atomic steps) is well beyond the scope of what Bstrlib can provide. It
+should be noted that MFC's built-in string mutex actually does not solve this
+problem either -- it just removes immediate data corruption as a possible
+outcome of such exploit attempts (it can be argued that this is worse, since
+it will leave no trace of the exploitation). In general race conditions have
+to be dealt with by careful design and implementation; it cannot be assisted
by a string library.
@@ -2453,14 +2453,14 @@
by a string library.
-2. Any kind of access control or security attributes to prevent usage in
-dangerous interfaces such as system(). Perl includes a "trust" attribute
-which can be endowed upon strings that are intended to be passed to such
-dangerous interfaces. However, Perl's solution reflects its own limitations
--- notably that it is not a strongly typed language. In the example code for
-Bstrlib, there is a module called taint.cpp. It demonstrates how to write a
-simple wrapper class for managing "untainted" or trusted strings using the
-type system to prevent questionable mixing of ordinary untrusted strings with
-untainted ones then passing them to dangerous interfaces. In this way the
-security correctness of the code reduces to auditing the direct usages of
+2. Any kind of access control or security attributes to prevent usage in
+dangerous interfaces such as system(). Perl includes a "trust" attribute
+which can be endowed upon strings that are intended to be passed to such
+dangerous interfaces. However, Perl's solution reflects its own limitations
+-- notably that it is not a strongly typed language. In the example code for
+Bstrlib, there is a module called taint.cpp. It demonstrates how to write a
+simple wrapper class for managing "untainted" or trusted strings using the
+type system to prevent questionable mixing of ordinary untrusted strings with
+untainted ones then passing them to dangerous interfaces. In this way the
+security correctness of the code reduces to auditing the direct usages of
dangerous interfaces or promotions of tainted strings to untainted ones.
@@ -2465,13 +2465,13 @@
dangerous interfaces or promotions of tainted strings to untainted ones.
-3. Encryption of string contents is way beyond the scope of Bstrlib.
-Maintaining encrypted string contents in the futile hopes of thwarting things
-like using system-level debuggers to examine sensitive string data is likely
-to be a wasted effort (imagine a debugger that runs at a higher level than a
-virtual processor where the application runs). For more standard encryption
-usages, since the bstring contents are simply binary blocks of data, this
+3. Encryption of string contents is way beyond the scope of Bstrlib.
+Maintaining encrypted string contents in the futile hopes of thwarting things
+like using system-level debuggers to examine sensitive string data is likely
+to be a wasted effort (imagine a debugger that runs at a higher level than a
+virtual processor where the application runs). For more standard encryption
+usages, since the bstring contents are simply binary blocks of data, this
should pose no problem for usage with other standard encryption libraries.
Compatibility
-------------
@@ -2473,9 +2473,9 @@
should pose no problem for usage with other standard encryption libraries.
Compatibility
-------------
-The Better String Library is known to compile and function correctly with the
+The Better String Library is known to compile and function correctly with the
following compilers:
- Microsoft Visual C++
@@ -2486,13 +2486,13 @@
- Turbo C
Setting of configuration options should be unnecessary for these compilers
-(unless exceptions are being disabled or STLport has been added to WATCOM
-C/C++). Bstrlib has been developed with an emphasis on portability. As such
-porting it to other compilers should be straight forward. This package
-includes a porting guide (called porting.txt) which explains what issues may
+(unless exceptions are being disabled or STLport has been added to WATCOM
+C/C++). Bstrlib has been developed with an emphasis on portability. As such
+porting it to other compilers should be straight forward. This package
+includes a porting guide (called porting.txt) which explains what issues may
exist for porting Bstrlib to different compilers and environments.
ANSI issues
-----------
1. The function pointer types bNgetc and bNread have prototypes which are very
@@ -2493,8 +2493,8 @@
exist for porting Bstrlib to different compilers and environments.
ANSI issues
-----------
1. The function pointer types bNgetc and bNread have prototypes which are very
-similar to, but not exactly the same as fgetc and fread respectively.
+similar to, but not exactly the same as fgetc and fread respectively.
Basically the FILE * parameter is replaced by void *. The purpose of this
@@ -2500,6 +2500,6 @@
Basically the FILE * parameter is replaced by void *. The purpose of this
-was to allow one to create other functions with fgetc and fread like
-semantics without being tied to ANSI C's file streaming mechanism. I.e., one
-could very easily adapt it to sockets, or simply reading a block of memory,
+was to allow one to create other functions with fgetc and fread like
+semantics without being tied to ANSI C's file streaming mechanism. I.e., one
+could very easily adapt it to sockets, or simply reading a block of memory,
or procedurally generated strings (for fractal generation, for example.)
@@ -2504,10 +2504,10 @@
or procedurally generated strings (for fractal generation, for example.)
-The problem is that invoking the functions (bNgetc)fgetc and (bNread)fread is
-not technically legal in ANSI C. The reason being that the compiler is only
-able to coerce the function pointers themselves into the target type, however
-are unable to perform any cast (implicit or otherwise) on the parameters
-passed once invoked. I.e., if internally void * and FILE * need some kind of
-mechanical coercion, the compiler will not properly perform this conversion
+The problem is that invoking the functions (bNgetc)fgetc and (bNread)fread is
+not technically legal in ANSI C. The reason being that the compiler is only
+able to coerce the function pointers themselves into the target type, however
+are unable to perform any cast (implicit or otherwise) on the parameters
+passed once invoked. I.e., if internally void * and FILE * need some kind of
+mechanical coercion, the compiler will not properly perform this conversion
and thus lead to undefined behavior.
@@ -2512,6 +2512,6 @@
and thus lead to undefined behavior.
-Apparently a platform from Data General called "Eclipse" and another from
-Tandem called "NonStop" have a different representation for pointers to bytes
-and pointers to words, for example, where coercion via casting is necessary.
+Apparently a platform from Data General called "Eclipse" and another from
+Tandem called "NonStop" have a different representation for pointers to bytes
+and pointers to words, for example, where coercion via casting is necessary.
(Actual confirmation of the existence of such machines is hard to come by, so
@@ -2517,5 +2517,5 @@
(Actual confirmation of the existence of such machines is hard to come by, so
-it is prudent to be skeptical about this information.) However, this is not
-an issue for any known contemporary platforms. One may conclude that such
+it is prudent to be skeptical about this information.) However, this is not
+an issue for any known contemporary platforms. One may conclude that such
platforms are effectively apocryphal even if they do exist.
@@ -2520,6 +2520,6 @@
platforms are effectively apocryphal even if they do exist.
-To correctly work around this problem to the satisfaction of the ANSI
-limitations, one needs to create wrapper functions for fgets and/or
-fread with the prototypes of bNgetc and/or bNread respectively which performs
+To correctly work around this problem to the satisfaction of the ANSI
+limitations, one needs to create wrapper functions for fgets and/or
+fread with the prototypes of bNgetc and/or bNread respectively which performs
no other action other than to explicitely cast the void * parameter to a
@@ -2525,5 +2525,5 @@
no other action other than to explicitely cast the void * parameter to a
-FILE *, and simply pass the remaining parameters straight to the function
+FILE *, and simply pass the remaining parameters straight to the function
pointer call.
The wrappers themselves are trivial:
@@ -2540,8 +2540,8 @@
linking with file I/O functions.
2. vsnprintf is not available on all compilers. Because of this, the bformat
-and bformata functions (and format and formata methods) are not guaranteed to
-work properly. For those compilers that don't have vsnprintf, the
-BSTRLIB_NOVSNP macro should be set before compiling bstrlib, and the format
+and bformata functions (and format and formata methods) are not guaranteed to
+work properly. For those compilers that don't have vsnprintf, the
+BSTRLIB_NOVSNP macro should be set before compiling bstrlib, and the format
functions/method will be disabled.
@@ -2546,6 +2546,6 @@
functions/method will be disabled.
-The more recent ANSI C standards have specified the required inclusion of a
+The more recent ANSI C standards have specified the required inclusion of a
vsnprintf function.
3. The bstrlib function names are not unique in the first 6 characters. This
@@ -2549,8 +2549,8 @@
vsnprintf function.
3. The bstrlib function names are not unique in the first 6 characters. This
-is only an issue for older C compiler environments which do not store more
+is only an issue for older C compiler environments which do not store more
than 6 characters for function names.
4. The bsafe module defines macros and function names which are part of the
C library. This simply overrides the definition as expected on all platforms
@@ -2553,8 +2553,8 @@
than 6 characters for function names.
4. The bsafe module defines macros and function names which are part of the
C library. This simply overrides the definition as expected on all platforms
-tested, however it is not sanctioned by the ANSI standard. This module is
-clearly optional and should be omitted on platforms which disallow its
+tested, however it is not sanctioned by the ANSI standard. This module is
+clearly optional and should be omitted on platforms which disallow its
undefined semantics.
@@ -2559,5 +2559,5 @@
undefined semantics.
-In practice the real issue is that some compilers in some modes of operation
-can/will inline these standard library functions on a module by module basis
+In practice the real issue is that some compilers in some modes of operation
+can/will inline these standard library functions on a module by module basis
as they appear in each. The linker will thus have no opportunity to override
@@ -2563,6 +2563,6 @@
as they appear in each. The linker will thus have no opportunity to override
-the implementation of these functions for those cases. This can lead to
-inconsistent behaviour of the bsafe module on different platforms and
+the implementation of these functions for those cases. This can lead to
+inconsistent behaviour of the bsafe module on different platforms and
compilers.
===============================================================================
@@ -2570,9 +2570,9 @@
Comparison with Microsoft's CString class
-----------------------------------------
-Although developed independently, CBStrings have very similar functionality to
-Microsoft's CString class. However, the bstring library has significant
+Although developed independently, CBStrings have very similar functionality to
+Microsoft's CString class. However, the bstring library has significant
advantages over CString:
1. Bstrlib is a C-library as well as a C++ library (using the C++ wrapper).
@@ -2575,9 +2575,9 @@
advantages over CString:
1. Bstrlib is a C-library as well as a C++ library (using the C++ wrapper).
- - Thus it is compatible with more programming environments and
+ - Thus it is compatible with more programming environments and
available to a wider population of programmers.
2. The internal structure of a bstring is considered exposed.
@@ -2580,11 +2580,11 @@
available to a wider population of programmers.
2. The internal structure of a bstring is considered exposed.
- - A single contiguous block of data can be cut into read-only pieces by
- simply creating headers, without allocating additional memory to create
+ - A single contiguous block of data can be cut into read-only pieces by
+ simply creating headers, without allocating additional memory to create
reference copies of each of these sub-strings.
- In this way, using bstrings in a totally abstracted way becomes a choice
rather than an imposition. Further this choice can be made differently
at different layers of applications that use it.
@@ -2586,8 +2586,8 @@
reference copies of each of these sub-strings.
- In this way, using bstrings in a totally abstracted way becomes a choice
rather than an imposition. Further this choice can be made differently
at different layers of applications that use it.
-3. Static declaration support precludes the need for constructor
+3. Static declaration support precludes the need for constructor
invocation.
@@ -2592,7 +2592,7 @@
invocation.
- - Allows for static declarations of constant strings that has no
+ - Allows for static declarations of constant strings that has no
additional constructor overhead.
4. Bstrlib is not attached to another library.
@@ -2595,8 +2595,8 @@
additional constructor overhead.
4. Bstrlib is not attached to another library.
- - Bstrlib is designed to be easily plugged into any other library
- collection, without dependencies on other libraries or paradigms (such
+ - Bstrlib is designed to be easily plugged into any other library
+ collection, without dependencies on other libraries or paradigms (such
as "MFC".)
@@ -2601,6 +2601,6 @@
as "MFC".)
-The bstring library also comes with a few additional functions that are not
+The bstring library also comes with a few additional functions that are not
available in the CString class:
- bsetstr
@@ -2609,5 +2609,5 @@
- breplace (this is different from CString::Replace())
- Writable indexed characters (for example a[i]='x')
-Interestingly, although Microsoft did implement mid$(), left$() and right$()
+Interestingly, although Microsoft did implement mid$(), left$() and right$()
functional analogues (these are functions from GWBASIC) they seem to have
@@ -2613,5 +2613,5 @@
functional analogues (these are functions from GWBASIC) they seem to have
-forgotten that mid$() could be also used to write into the middle of a string.
-This functionality exists in Bstrlib with the bsetstr() and breplace()
+forgotten that mid$() could be also used to write into the middle of a string.
+This functionality exists in Bstrlib with the bsetstr() and breplace()
functions.
@@ -2616,12 +2616,12 @@
functions.
-Among the disadvantages of Bstrlib is that there is no special support for
-localization or wide characters. Such things are considered beyond the scope
-of what bstrings are trying to deliver. CString essentially supports the
-older UCS-2 version of Unicode via widechar_t as an application-wide compile
+Among the disadvantages of Bstrlib is that there is no special support for
+localization or wide characters. Such things are considered beyond the scope
+of what bstrings are trying to deliver. CString essentially supports the
+older UCS-2 version of Unicode via widechar_t as an application-wide compile
time switch.
CString's also use built-in mechanisms for ensuring thread safety under all
situations. While this makes writing thread safe code that much easier, this
built-in safety feature has a price -- the inner loops of each CString method
runs in its own critical section (grabbing and releasing a light weight mutex
@@ -2622,12 +2622,12 @@
time switch.
CString's also use built-in mechanisms for ensuring thread safety under all
situations. While this makes writing thread safe code that much easier, this
built-in safety feature has a price -- the inner loops of each CString method
runs in its own critical section (grabbing and releasing a light weight mutex
-on every operation.) The usual way to decrease the impact of a critical
-section performance penalty is to amortize more operations per critical
-section. But since the implementation of CStrings is fixed as a one critical
-section per-operation cost, there is no way to leverage this common
+on every operation.) The usual way to decrease the impact of a critical
+section performance penalty is to amortize more operations per critical
+section. But since the implementation of CStrings is fixed as a one critical
+section per-operation cost, there is no way to leverage this common
performance enhancing idea.
@@ -2632,12 +2632,12 @@
performance enhancing idea.
-The search facilities in Bstrlib are comparable to those in MFC's CString
-class, though it is missing locale specific collation. But because Bstrlib
-is interoperable with C's char buffers, it will allow programmers to write
-their own string searching mechanism (such as Boyer-Moore), or be able to
-choose from a variety of available existing string searching libraries (such
+The search facilities in Bstrlib are comparable to those in MFC's CString
+class, though it is missing locale specific collation. But because Bstrlib
+is interoperable with C's char buffers, it will allow programmers to write
+their own string searching mechanism (such as Boyer-Moore), or be able to
+choose from a variety of available existing string searching libraries (such
as those for regular expressions) without difficulty.
Microsoft used a very non-ANSI conforming trick in its implementation to
allow printf() to use the "%s" specifier to output a CString correctly. This
can be convenient, but it is inherently not portable. CBString requires an
@@ -2639,9 +2639,9 @@
as those for regular expressions) without difficulty.
Microsoft used a very non-ANSI conforming trick in its implementation to
allow printf() to use the "%s" specifier to output a CString correctly. This
can be convenient, but it is inherently not portable. CBString requires an
-explicit cast, while bstring requires the data member to be dereferenced.
+explicit cast, while bstring requires the data member to be dereferenced.
Microsoft's own documentation recommends casting, instead of relying on this
feature.
@@ -2653,7 +2653,7 @@
1. There is no C implementation.
2. The [] operator is not bounds checked.
3. Missing a lot of useful functions like printf-like formatting.
-4. Some sub-standard std::string implementations (SGI) are necessarily unsafe
+4. Some sub-standard std::string implementations (SGI) are necessarily unsafe
to use with multithreading.
5. Limited by STL's std::iostream which in turn is limited by ifstream which
can only take input from files. (Compare to CBStream's API which can take
@@ -2663,7 +2663,7 @@
Comparison with ISO C TR 24731 proposal
---------------------------------------
-Following the ISO C99 standard, Microsoft has proposed a group of C library
+Following the ISO C99 standard, Microsoft has proposed a group of C library
extensions which are supposedly "safer and more secure". This proposal is
expected to be adopted by the ISO C standard which follows C99.
@@ -2667,16 +2667,16 @@
extensions which are supposedly "safer and more secure". This proposal is
expected to be adopted by the ISO C standard which follows C99.
-The proposal reveals itself to be very similar to Microsoft's "StrSafe"
-library. The functions are basically the same as other standard C library
-string functions except that destination parameters are paired with an
-additional length parameter of type rsize_t. rsize_t is the same as size_t,
-however, the range is checked to make sure its between 1 and RSIZE_MAX. Like
-Bstrlib, the functions perform a "parameter check". Unlike Bstrlib, when a
-parameter check fails, rather than simply outputing accumulatable error
-statuses, they call a user settable global error function handler, and upon
-return of control performs no (additional) detrimental action. The proposal
-covers basic string functions as well as a few non-reenterable functions
+The proposal reveals itself to be very similar to Microsoft's "StrSafe"
+library. The functions are basically the same as other standard C library
+string functions except that destination parameters are paired with an
+additional length parameter of type rsize_t. rsize_t is the same as size_t,
+however, the range is checked to make sure its between 1 and RSIZE_MAX. Like
+Bstrlib, the functions perform a "parameter check". Unlike Bstrlib, when a
+parameter check fails, rather than simply outputing accumulatable error
+statuses, they call a user settable global error function handler, and upon
+return of control performs no (additional) detrimental action. The proposal
+covers basic string functions as well as a few non-reenterable functions
(asctime, ctime, and strtok).
1. Still based solely on char * buffers (and therefore strlen() and strcat()
@@ -2686,10 +2686,10 @@
4. No attempt to enhance functionality of the C library.
5. Introduces a new error scenario (strings exceeding RSIZE_MAX length).
-The hope is that by exposing the buffer length requirements there will be
-fewer buffer overrun errors. However, the error modes are really just
-transformed, rather than removed. The real problem of buffer overflows is
-that they all happen as a result of erroneous programming. So forcing
-programmers to manually deal with buffer limits, will make them more aware of
+The hope is that by exposing the buffer length requirements there will be
+fewer buffer overrun errors. However, the error modes are really just
+transformed, rather than removed. The real problem of buffer overflows is
+that they all happen as a result of erroneous programming. So forcing
+programmers to manually deal with buffer limits, will make them more aware of
the problem but doesn't remove the possibility of erroneous programming. So
a programmer that erroneously mixes up the rsize_t parameters is no better off
@@ -2694,6 +2694,6 @@
the problem but doesn't remove the possibility of erroneous programming. So
a programmer that erroneously mixes up the rsize_t parameters is no better off
-from a programmer that introduces potential buffer overflows through other
-more typical lapses. So at best this may reduce the rate of erroneous
+from a programmer that introduces potential buffer overflows through other
+more typical lapses. So at best this may reduce the rate of erroneous
programming, rather than making any attempt at removing failure modes.
@@ -2698,10 +2698,10 @@
programming, rather than making any attempt at removing failure modes.
-The error handler can discriminate between types of failures, but does not
-take into account any callsite context. So the problem is that the error is
-going to be manifest in a piece of code, but there is no pointer to that
-code. It would seem that passing in the call site __FILE__, __LINE__ as
-parameters would be very useful, but the API clearly doesn't support such a
-thing (it would increase code bloat even more than the extra length
+The error handler can discriminate between types of failures, but does not
+take into account any callsite context. So the problem is that the error is
+going to be manifest in a piece of code, but there is no pointer to that
+code. It would seem that passing in the call site __FILE__, __LINE__ as
+parameters would be very useful, but the API clearly doesn't support such a
+thing (it would increase code bloat even more than the extra length
parameter does, and would require macro tricks to implement).
@@ -2706,10 +2706,10 @@
parameter does, and would require macro tricks to implement).
-The Bstrlib C API takes the position that error handling needs to be done at
-the callsite, and just tries to make it as painless as possible. Furthermore,
-error modes are removed by supporting auto-growing strings and aliasing. For
-capturing errors in more central code fragments, Bstrlib's C++ API uses
-exception handling extensively, which is superior to the leaf-only error
+The Bstrlib C API takes the position that error handling needs to be done at
+the callsite, and just tries to make it as painless as possible. Furthermore,
+error modes are removed by supporting auto-growing strings and aliasing. For
+capturing errors in more central code fragments, Bstrlib's C++ API uses
+exception handling extensively, which is superior to the leaf-only error
handler approach.
Comparison with Managed String Library CERT proposal
@@ -2718,17 +2718,17 @@
The main webpage for the managed string library:
http://www.cert.org/secure-coding/managedstring.html
-Robert Seacord at CERT has proposed a C string library that he calls the
-"Managed String Library" for C. Like Bstrlib, it introduces a new type
-which is called a managed string. The structure of a managed string
-(string_m) is like a struct tagbstring but missing the length field. This
-internal structure is considered opaque. The length is, like the C standard
-library, always computed on the fly by searching for a terminating NUL on
-every operation that requires it. So it suffers from every performance
-problem that the C standard library suffers from. Interoperating with C
-string APIs (like printf, fopen, or anything else that takes a string
-parameter) requires copying to additionally allocating buffers that have to
-be manually freed -- this makes this library probably slower and more
+Robert Seacord at CERT has proposed a C string library that he calls the
+"Managed String Library" for C. Like Bstrlib, it introduces a new type
+which is called a managed string. The structure of a managed string
+(string_m) is like a struct tagbstring but missing the length field. This
+internal structure is considered opaque. The length is, like the C standard
+library, always computed on the fly by searching for a terminating NUL on
+every operation that requires it. So it suffers from every performance
+problem that the C standard library suffers from. Interoperating with C
+string APIs (like printf, fopen, or anything else that takes a string
+parameter) requires copying to additionally allocating buffers that have to
+be manually freed -- this makes this library probably slower and more
cumbersome than any other string library in existence.
The library gives a fully populated error status as the return value of every
@@ -2732,8 +2732,8 @@
cumbersome than any other string library in existence.
The library gives a fully populated error status as the return value of every
-string function. The hope is to be able to diagnose all problems
-specifically from the return code alone. Comparing this to Bstrlib, which
-aways returns one consistent error message, might make it seem that Bstrlib
-would be harder to debug; but this is not true. With Bstrlib, if an error
+string function. The hope is to be able to diagnose all problems
+specifically from the return code alone. Comparing this to Bstrlib, which
+aways returns one consistent error message, might make it seem that Bstrlib
+would be harder to debug; but this is not true. With Bstrlib, if an error
occurs there is always enough information from just knowing there was an error
@@ -2739,5 +2739,5 @@
occurs there is always enough information from just knowing there was an error
-and examining the parameters to deduce exactly what kind of error has
-happened. The managed string library thus gives up nested function calls
+and examining the parameters to deduce exactly what kind of error has
+happened. The managed string library thus gives up nested function calls
while achieving little benefit, while Bstrlib does not.
@@ -2742,4 +2742,4 @@
while achieving little benefit, while Bstrlib does not.
-One interesting feature that "managed strings" has is the idea of data
+One interesting feature that "managed strings" has is the idea of data
sanitization via character set whitelisting. That is to say, a globally
@@ -2745,8 +2745,8 @@
sanitization via character set whitelisting. That is to say, a globally
-definable filter that makes any attempt to put invalid characters into strings
-lead to an error and not modify the string. The author gives the following
+definable filter that makes any attempt to put invalid characters into strings
+lead to an error and not modify the string. The author gives the following
example:
// create valid char set
if (retValue = strcreate_m(&str1, "abc") ) {
fprintf(
@@ -2748,9 +2748,9 @@
example:
// create valid char set
if (retValue = strcreate_m(&str1, "abc") ) {
fprintf(
- stderr,
- "Error %d from strcreate_m.\n",
+ stderr,
+ "Error %d from strcreate_m.\n",
retValue
);
@@ -2755,5 +2755,5 @@
retValue
);
- }
+ }
if (retValue = setcharset(str1)) {
fprintf(
@@ -2758,9 +2758,9 @@
if (retValue = setcharset(str1)) {
fprintf(
- stderr,
- "Error %d from setcharset().\n",
+ stderr,
+ "Error %d from setcharset().\n",
retValue
);
}
if (retValue = strcreate_m(&str1, "aabbccabc")) {
fprintf(
@@ -2762,13 +2762,13 @@
retValue
);
}
if (retValue = strcreate_m(&str1, "aabbccabc")) {
fprintf(
- stderr,
- "Error %d from strcreate_m.\n",
+ stderr,
+ "Error %d from strcreate_m.\n",
retValue
);
}
// create string with invalid char set
if (retValue = strcreate_m(&str1, "abbccdabc")) {
fprintf(
@@ -2769,10 +2769,10 @@
retValue
);
}
// create string with invalid char set
if (retValue = strcreate_m(&str1, "abbccdabc")) {
fprintf(
- stderr,
- "Error %d from strcreate_m.\n",
+ stderr,
+ "Error %d from strcreate_m.\n",
retValue
);
@@ -2777,6 +2777,6 @@
retValue
);
- }
+ }
Which we can compare with a more Bstrlib way of doing things:
@@ -2794,16 +2794,16 @@
bstring str1 = bCreateWithFilter ("aabbccabc", &charFilter);
bstring str2 = bCreateWithFilter ("aabbccdabc", &charFilter);
-The first thing we should notice is that with the Bstrlib approach you can
-have different filters for different strings if necessary. Furthermore,
-selecting a charset filter in the Managed String Library is uni-contextual.
-That is to say, there can only be one such filter active for the entire
-program, which means its usage is not well defined for intermediate library
-usage (a library that uses it will interfere with user code that uses it, and
-vice versa.) It is also likely to be poorly defined in multi-threading
+The first thing we should notice is that with the Bstrlib approach you can
+have different filters for different strings if necessary. Furthermore,
+selecting a charset filter in the Managed String Library is uni-contextual.
+That is to say, there can only be one such filter active for the entire
+program, which means its usage is not well defined for intermediate library
+usage (a library that uses it will interfere with user code that uses it, and
+vice versa.) It is also likely to be poorly defined in multi-threading
environments.
There is also a question as to whether the data sanitization filter is checked
on every operation, or just on creation operations. Since the charset can be
set arbitrarily at run time, it might be set *after* some managed strings have
been created. This would seem to imply that all functions should run this
@@ -2804,8 +2804,8 @@
environments.
There is also a question as to whether the data sanitization filter is checked
on every operation, or just on creation operations. Since the charset can be
set arbitrarily at run time, it might be set *after* some managed strings have
been created. This would seem to imply that all functions should run this
-additional check every time if there is an attempt to enforce this. This
+additional check every time if there is an attempt to enforce this. This
would make things tremendously slow. On the other hand, if it is assumed that
@@ -2811,9 +2811,9 @@
would make things tremendously slow. On the other hand, if it is assumed that
-only creates and other operations that take char *'s as input need be checked
-because the charset was only supposed to be called once at and before any
-other managed string was created, then one can see that its easy to cover
-Bstrlib with equivalent functionality via a few wrapper calls such as the
+only creates and other operations that take char *'s as input need be checked
+because the charset was only supposed to be called once at and before any
+other managed string was created, then one can see that its easy to cover
+Bstrlib with equivalent functionality via a few wrapper calls such as the
example given above.
And finally we have to question the value of sanitation in the first place.
For example, for httpd servers, there is generally a requirement that the
@@ -2816,11 +2816,11 @@
example given above.
And finally we have to question the value of sanitation in the first place.
For example, for httpd servers, there is generally a requirement that the
-URLs parsed have some form that avoids undesirable translation to local file
-system filenames or resources. The problem is that the way URLs can be
-encoded, it must be completely parsed and translated to know if it is using
+URLs parsed have some form that avoids undesirable translation to local file
+system filenames or resources. The problem is that the way URLs can be
+encoded, it must be completely parsed and translated to know if it is using
certain invalid character combinations. That is to say, merely filtering
each character one at a time is not necessarily the right way to ensure that
a string has safe contents.
@@ -2823,9 +2823,9 @@
certain invalid character combinations. That is to say, merely filtering
each character one at a time is not necessarily the right way to ensure that
a string has safe contents.
-In the article that describes this proposal, it is claimed that it fairly
-closely approximates the existing C API semantics. On this point we should
+In the article that describes this proposal, it is claimed that it fairly
+closely approximates the existing C API semantics. On this point we should
compare this "closeness" with Bstrlib:
Bstrlib Managed String Library
@@ -2839,7 +2839,7 @@
Transparency Complete None
-Its pretty clear that the semantic mapping from C strings to Bstrlib is fairly
+Its pretty clear that the semantic mapping from C strings to Bstrlib is fairly
straightforward, and that in general semantic capabilities are the same or
superior in Bstrlib. On the other hand the Managed String Library is either
missing semantics or changes things fairly significantly.
@@ -2852,10 +2852,10 @@
1. Still based solely on char * buffers (and therefore strlen() and strcat()
is still O(n), and there are no faster streq() comparison functions.)
- Their suggestion that alternatives which wrap the string data type (such as
+ Their suggestion that alternatives which wrap the string data type (such as
bstring does) imposes a difficulty in interoperating with the C langauge's
ordinary C string library is not founded.
2. Introduction of memory (and vector?) abstractions imposes a learning
curve, and some kind of memory usage policy that is outside of the strings
themselves (and therefore must be maintained by the developer.)
3. The API is massive, and filled with all sorts of trivial (pjoin) and
@@ -2856,8 +2856,8 @@
bstring does) imposes a difficulty in interoperating with the C langauge's
ordinary C string library is not founded.
2. Introduction of memory (and vector?) abstractions imposes a learning
curve, and some kind of memory usage policy that is outside of the strings
themselves (and therefore must be maintained by the developer.)
3. The API is massive, and filled with all sorts of trivial (pjoin) and
- controvertial (pmatch -- regular expression are not sufficiently
+ controvertial (pmatch -- regular expression are not sufficiently
standardized, and there is a very large difference in performance between
@@ -2863,5 +2863,5 @@
standardized, and there is a very large difference in performance between
- compiled and non-compiled, REs) functions. Bstrlib takes a decidely
+ compiled and non-compiled, REs) functions. Bstrlib takes a decidely
minimal approach -- none of the functionality in c2lib is difficult or
challenging to implement on top of Bstrlib (except the regex stuff, which
is going to be difficult, and controvertial no matter what.)
@@ -2865,7 +2865,7 @@
minimal approach -- none of the functionality in c2lib is difficult or
challenging to implement on top of Bstrlib (except the regex stuff, which
is going to be difficult, and controvertial no matter what.)
-4. Understanding why c2lib is the way it is pretty much requires a working
+4. Understanding why c2lib is the way it is pretty much requires a working
knowledge of Perl. bstrlib requires only knowledge of the C string library
while providing just a very select few worthwhile extras.
5. It is attached to a lot of cruft like a matrix math library (that doesn't
@@ -2869,11 +2869,11 @@
knowledge of Perl. bstrlib requires only knowledge of the C string library
while providing just a very select few worthwhile extras.
5. It is attached to a lot of cruft like a matrix math library (that doesn't
- include any functions for getting the determinant, eigenvectors,
- eigenvalues, the matrix inverse, test for singularity, test for
- orthogonality, a grahm schmit orthogonlization, LU decomposition ... I
+ include any functions for getting the determinant, eigenvectors,
+ eigenvalues, the matrix inverse, test for singularity, test for
+ orthogonality, a grahm schmit orthogonlization, LU decomposition ... I
mean why bother?)
Convincing a development house to use c2lib is likely quite difficult. It
introduces too much, while not being part of any kind of standards body. The
code must therefore be trusted, or maintained by those that use it. While
@@ -2875,10 +2875,10 @@
mean why bother?)
Convincing a development house to use c2lib is likely quite difficult. It
introduces too much, while not being part of any kind of standards body. The
code must therefore be trusted, or maintained by those that use it. While
-bstring offers nothing more on this front, since its so much smaller, covers
-far less in terms of scope, and will typically improve string performance,
+bstring offers nothing more on this front, since its so much smaller, covers
+far less in terms of scope, and will typically improve string performance,
the barrier to usage should be much smaller.
Comparison with stralloc/qmail
@@ -2891,7 +2891,7 @@
1. Library is very very minimal. A little too minimal.
2. Untargetted source parameters are not declared const.
3. Slightly different expected emphasis (like _cats function which takes an
- ordinary C string char buffer as a parameter.) Its clear that the
+ ordinary C string char buffer as a parameter.) Its clear that the
remainder of the C string library is still required to perform more
useful string operations.
@@ -2900,7 +2900,7 @@
are clearly a subset of what Bstrlib supplies. For anyone who is served by
stralloc, Bstrlib is complete substitute that just adds more functionality.
-stralloc actually uses the interesting policy that a NULL data pointer
+stralloc actually uses the interesting policy that a NULL data pointer
indicates an empty string. In this way, non-static empty strings can be
declared without construction. This advantage is minimal, since static empty
bstrings can be declared inline without construction, and if the string needs
@@ -2904,9 +2904,9 @@
indicates an empty string. In this way, non-static empty strings can be
declared without construction. This advantage is minimal, since static empty
bstrings can be declared inline without construction, and if the string needs
-to be written to it should be constructed from an empty string (or its first
+to be written to it should be constructed from an empty string (or its first
initializer) in any event.
wxString class
--------------
@@ -2908,9 +2908,9 @@
initializer) in any event.
wxString class
--------------
-This is the string class used in the wxWindows project. A description of
+This is the string class used in the wxWindows project. A description of
wxString can be found here:
http://www.wxwindows.org/manuals/2.4.2/wx368.htm#wxstring
@@ -2914,7 +2914,7 @@
wxString can be found here:
http://www.wxwindows.org/manuals/2.4.2/wx368.htm#wxstring
-This C++ library is similar to CBString. However, it is littered with
+This C++ library is similar to CBString. However, it is littered with
trivial functions (IsAscii, UpperCase, RemoveLast etc.)
1. There is no C implementation.
@@ -2918,8 +2918,8 @@
trivial functions (IsAscii, UpperCase, RemoveLast etc.)
1. There is no C implementation.
-2. The memory management strategy is to allocate a bounded fixed amount of
- additional space on each resize, meaning that it does not have the
- log_2(n) property that Bstrlib has (it will thrash very easily, cause
- massive fragmentation in common heap implementations, and can easily be a
+2. The memory management strategy is to allocate a bounded fixed amount of
+ additional space on each resize, meaning that it does not have the
+ log_2(n) property that Bstrlib has (it will thrash very easily, cause
+ massive fragmentation in common heap implementations, and can easily be a
common source of performance problems).
@@ -2925,7 +2925,7 @@
common source of performance problems).
-3. The library uses a "copy on write" strategy, meaning that it has to deal
+3. The library uses a "copy on write" strategy, meaning that it has to deal
with multithreading problems.
Vstr
----
@@ -2927,9 +2927,9 @@
with multithreading problems.
Vstr
----
-This is a highly orthogonal C string library with an emphasis on
+This is a highly orthogonal C string library with an emphasis on
networking/realtime programming. It can be found here:
http://www.and.org/vstr/
@@ -2938,6 +2938,6 @@
2. The API and implementation is very large (owing to its orthogonality) and
can lead to difficulty in understanding its exact functionality.
3. An obvious dependency on gnu tools (confusing make configure step)
-4. Uses a reference counting system, meaning that it is not likely to be
+4. Uses a reference counting system, meaning that it is not likely to be
thread safe.
@@ -2942,11 +2942,11 @@
thread safe.
-The implementation has an extreme emphasis on performance for nontrivial
-actions (adds, inserts and deletes are all constant or roughly O(#operations)
-time) following the "zero copy" principle. This trades off performance of
-trivial functions (character access, char buffer access/coersion, alias
-detection) which becomes significantly slower, as well as incremental
-accumulative costs for its searching/parsing functions. Whether or not Vstr
-wins any particular performance benchmark will depend a lot on the benchmark,
+The implementation has an extreme emphasis on performance for nontrivial
+actions (adds, inserts and deletes are all constant or roughly O(#operations)
+time) following the "zero copy" principle. This trades off performance of
+trivial functions (character access, char buffer access/coersion, alias
+detection) which becomes significantly slower, as well as incremental
+accumulative costs for its searching/parsing functions. Whether or not Vstr
+wins any particular performance benchmark will depend a lot on the benchmark,
but it should handily win on some, while losing dreadfully on others.
@@ -2951,10 +2951,10 @@
but it should handily win on some, while losing dreadfully on others.
-The learning curve for Vstr is very steep, and it doesn't come with any
-obvious way to build for Windows or other platforms without gnu tools. At
-least one mechanism (the iterator) introduces a new undefined scenario
-(writing to a Vstr while iterating through it.) Vstr has a very large
-footprint, and is very ambitious in its total functionality. Vstr has no C++
+The learning curve for Vstr is very steep, and it doesn't come with any
+obvious way to build for Windows or other platforms without gnu tools. At
+least one mechanism (the iterator) introduces a new undefined scenario
+(writing to a Vstr while iterating through it.) Vstr has a very large
+footprint, and is very ambitious in its total functionality. Vstr has no C++
API.
Vstr usage requires context initialization via vstr_init() which must be run
@@ -2962,10 +2962,10 @@
this means that sharing Vstrings across threads is not well defined, or at
least not safe from race conditions. This API is clearly geared to the older
standard of fork() style multitasking in UNIX, and is not safely transportable
-to modern shared memory multithreading available in Linux and Windows. There
-is no portable external solution making the library thread safe (since it
+to modern shared memory multithreading available in Linux and Windows. There
+is no portable external solution making the library thread safe (since it
requires a mutex around each Vstr context -- not each string.)
In the documentation for this library, a big deal is made of its self hosted
s(n)printf-like function. This is an issue for older compilers that don't
include vsnprintf(), but also an issue because Vstr has a slow conversion to
@@ -2967,15 +2967,15 @@
requires a mutex around each Vstr context -- not each string.)
In the documentation for this library, a big deal is made of its self hosted
s(n)printf-like function. This is an issue for older compilers that don't
include vsnprintf(), but also an issue because Vstr has a slow conversion to
-'\0' terminated char * mechanism. That is to say, using "%s" to format data
-that originates from Vstr would be slow without some sort of native function
-to do so. Bstrlib sidesteps the issue by relying on what snprintf-like
-functionality does exist and having a high performance conversion to a char *
+'\0' terminated char * mechanism. That is to say, using "%s" to format data
+that originates from Vstr would be slow without some sort of native function
+to do so. Bstrlib sidesteps the issue by relying on what snprintf-like
+functionality does exist and having a high performance conversion to a char *
compatible string so that "%s" can be used directly.
Str Library
-----------
This is a fairly extensive string library, that includes full unicode support
@@ -2976,10 +2976,10 @@
compatible string so that "%s" can be used directly.
Str Library
-----------
This is a fairly extensive string library, that includes full unicode support
-and targetted at the goal of out performing MFC and STL. The architecture,
+and targetted at the goal of out performing MFC and STL. The architecture,
similarly to MFC's CStrings, is a copy on write reference counting mechanism.
http://www.utilitycode.com/str/default.aspx
@@ -2988,8 +2988,8 @@
2. C++ only.
This library, like Vstr, uses a ref counting system. There is only so deeply
-I can analyze it, since I don't have a license for it. However, performance
-improvements over MFC's and STL, doesn't seem like a sufficient reason to
-move your source base to it. For example, in the future, Microsoft may
+I can analyze it, since I don't have a license for it. However, performance
+improvements over MFC's and STL, doesn't seem like a sufficient reason to
+move your source base to it. For example, in the future, Microsoft may
improve the performance CString.
@@ -2994,7 +2994,7 @@
improve the performance CString.
-It should be pointed out that performance testing of Bstrlib has indicated
-that its relative performance advantage versus MFC's CString and STL's
+It should be pointed out that performance testing of Bstrlib has indicated
+that its relative performance advantage versus MFC's CString and STL's
std::string is at least as high as that for the Str library.
libmib astrings
@@ -3005,7 +3005,7 @@
http://www.mibsoftware.com/libmib/astring/
This package basically references strings through char ** pointers and assumes
-they are pointing to the top of an allocated heap entry (or NULL, in which
+they are pointing to the top of an allocated heap entry (or NULL, in which
case memory will be newly allocated from the heap.) So its still up to user
to mix and match the older C string functions with these functions whenever
pointer arithmetic is used (i.e., there is no leveraging of the type system
@@ -3009,9 +3009,9 @@
case memory will be newly allocated from the heap.) So its still up to user
to mix and match the older C string functions with these functions whenever
pointer arithmetic is used (i.e., there is no leveraging of the type system
-to assert semantic differences between references and base strings as Bstrlib
-does since no new types are introduced.) Unlike Bstrlib, exact string length
-meta data is not stored, thus requiring a strlen() call on *every* string
+to assert semantic differences between references and base strings as Bstrlib
+does since no new types are introduced.) Unlike Bstrlib, exact string length
+meta data is not stored, thus requiring a strlen() call on *every* string
writing operation. The library is very small, covering only a handful of C's
functions.
@@ -3015,7 +3015,7 @@
writing operation. The library is very small, covering only a handful of C's
functions.
-While this is better than nothing, it is clearly slower than even the
+While this is better than nothing, it is clearly slower than even the
standard C library, less safe and less functional than Bstrlib.
To explain the advantage of using libmib, their website shows an example of
@@ -3037,7 +3037,7 @@
if (!astrcpy(&pasz,getenv("PATH"))) /* malloc error */ exit(-1);
if (!astrcat(&pasz,pszExtraPath)) /* malloc error */ exit(-1);
-
+
/* Finally, a "limitless" printf! we can use */
asprintf(&paszOut,"Checking...%s\n",pasz);fputs(paszOut,stdout);
@@ -3055,9 +3055,9 @@
bdestroy (out);
Besides being shorter, we can see that error handling can be deferred right
-to the very end. Also, unlike the above two versions, if getenv() returns
-with NULL, the Bstrlib version will not exhibit undefined behavior.
-Initialization starts with the relevant content rather than an extra
+to the very end. Also, unlike the above two versions, if getenv() returns
+with NULL, the Bstrlib version will not exhibit undefined behavior.
+Initialization starts with the relevant content rather than an extra
autoinitialization step.
libclc
@@ -3085,8 +3085,8 @@
size, with safety limited to only half of the functions.
Firestring was originally just a wrapper of char * functionality with extra
-length parameters. However, it has been augmented with the inclusion of the
-estr type which has similar functionality to stralloc. But firestring does
+length parameters. However, it has been augmented with the inclusion of the
+estr type which has similar functionality to stralloc. But firestring does
not nearly cover the functional scope of Bstrlib.
Safe C String Library
@@ -3096,6 +3096,6 @@
handling capabilities.
http://www.zork.org/safestr/safestr.html
-1. While the safestr_* functions are safe in of themselves, interoperating
+1. While the safestr_* functions are safe in of themselves, interoperating
with char * string has dangerous unsafe modes of operation.
2. The architecture of safestr's causes the base pointer to change. Thus,
@@ -3100,8 +3100,8 @@
with char * string has dangerous unsafe modes of operation.
2. The architecture of safestr's causes the base pointer to change. Thus,
- its not practical/safe to store a safestr in multiple locations if any
+ its not practical/safe to store a safestr in multiple locations if any
single instance can be manipulated.
3. Dependent on an additional error handling library.
4. Uses reference counting, meaning that it is either not thread safe or
slow and not portable.
@@ -3103,10 +3103,10 @@
single instance can be manipulated.
3. Dependent on an additional error handling library.
4. Uses reference counting, meaning that it is either not thread safe or
slow and not portable.
-I think the idea of reallocating (and hence potentially changing) the base
-pointer is a serious design flaw that is fatal to this architecture. True
-safety is obtained by having automatic handling of all common scenarios
+I think the idea of reallocating (and hence potentially changing) the base
+pointer is a serious design flaw that is fatal to this architecture. True
+safety is obtained by having automatic handling of all common scenarios
without creating implicit constraints on the user.
@@ -3111,6 +3111,6 @@
without creating implicit constraints on the user.
-Because of its automatic temporary clean up system, it cannot use "const"
+Because of its automatic temporary clean up system, it cannot use "const"
semantics on input arguments. Interesting anomolies such as:
safestr_t s, t;
@@ -3118,11 +3118,11 @@
SAFESTR_TEMP (" "), SAFESTR_TEMP ("."));
/* t is now undefined. */
-are possible. If one defines a function which takes a safestr_t as a
-parameter, then the function would not know whether or not the safestr_t is
-defined after it passes it to a safestr library function. The author
-recommended method for working around this problem is to examine the
+are possible. If one defines a function which takes a safestr_t as a
+parameter, then the function would not know whether or not the safestr_t is
+defined after it passes it to a safestr library function. The author
+recommended method for working around this problem is to examine the
attributes of the safestr_t within the function which is to modify any of
its parameters and play games with its reference count. I think, therefore,
that the whole SAFESTR_TEMP idea is also fatally broken.
@@ -3125,17 +3125,17 @@
attributes of the safestr_t within the function which is to modify any of
its parameters and play games with its reference count. I think, therefore,
that the whole SAFESTR_TEMP idea is also fatally broken.
-The library implements immutability, optional non-resizability, and a "trust"
-flag. This trust flag is interesting, and suggests that applying any
-arbitrary sequence of safestr_* function calls on any set of trusted strings
-will result in a trusted string. It seems to me, however, that if one wanted
-to implement a trusted string semantic, one might do so by actually creating
-a different *type* and only implement the subset of string functions that are
-deemed safe (i.e., user input would be excluded, for example.) This, in
-essence, would allow the compiler to enforce trust propogation at compile
-time rather than run time. Non-resizability is also interesting, however,
-it seems marginal (i.e., to want a string that cannot be resized, yet can be
+The library implements immutability, optional non-resizability, and a "trust"
+flag. This trust flag is interesting, and suggests that applying any
+arbitrary sequence of safestr_* function calls on any set of trusted strings
+will result in a trusted string. It seems to me, however, that if one wanted
+to implement a trusted string semantic, one might do so by actually creating
+a different *type* and only implement the subset of string functions that are
+deemed safe (i.e., user input would be excluded, for example.) This, in
+essence, would allow the compiler to enforce trust propogation at compile
+time rather than run time. Non-resizability is also interesting, however,
+it seems marginal (i.e., to want a string that cannot be resized, yet can be
modified and yet where a fixed sized buffer is undesirable.)
===============================================================================
@@ -3171,7 +3171,7 @@
-------
The Better String Library is available under either the BSD license (see the
-accompanying license.txt) or the Gnu Public License version 2 (see the
+accompanying license.txt) or the Gnu Public License version 2 (see the
accompanying gpl.txt) at the option of the user.
===============================================================================