Alexander Liss
01/08/2001
Source code of a class StrBuffer is in "strbuf.h" and "strbuf.cpp" files. A StrBuffer class is a C++ object, which facilitates allocation and reallocation of an array of char's allocated in heap; in addition, it facilitates storing of data in this array. Data is retrieved through a public pointer "data" to this array. A pointer to data can be passed as a parameter, when needed StrBuffer's members are purposely made public, that they can be manipulated directly. This is a low-level object, which does not provide a protection against its misuse. Its methods are modeled after an STL's string class; this makes the use of the StrBuffer class simple for programmers, who have used an STL's string class. The major application of this class is to hold strings; hence, there are methods, which allow to path strings to this class. As a rule, a trailing zero is stored after a last byte of data. Hence, when one asks for 9 bytes, the class allocates at least 10 bytes to store trailing zero. To facilitate memory alignment and to speedup computation in the case of frequent reallocation of memory in this class, the StrBuffer class uses a special strategy of memory allocation. There is a private member "increment", which is set by a constructor. The default value of this parameter is 8. Memory is allocated and reallocated in multiples of the "increment". For example, if increment=8, and one asks for 9 bytes, then 16 bytes is allocated.
int data_size, allocated; char * data;
are self-explanatory.
1. StrBuffer(int initial_allocation=0, int increment=8);
If initial_allocation is zero, the memory is not allocated, otherwise it is allocated to be not less than initial_allocation and to be a multiple of an "increment".
2. StrBuffer(const char * string);
It allocates memory and copies the zero terminated string "string" into it.
3. StrBuffer(const char * from, int size);
It allocates memory and copies "size" bytes from memory pointed to by "from".
4. StrBuffer(const StrBuffer& s);
It is a copy constructor.
~StrBuffer();
de-allocates memory, if it was allocated.
StrBuffer& operator=(const StrBuffer& s).
Public Methods return zero on success and non-zero in the case of an error.
A reallocation function
int reallocate(int new_size);
reallocates memory and copies data to this new location; it checks that "new_size" is sufficient to copy data.
Four set functions allocate memory if needed and copy data into it:
1. int set(const StrBuffer& s);
2. int set(const char * string);
copies data from a zero terminated string "string"
3. int set(const char * from, int size);
copies "size" bytes of data from the location "from".
4. int set(int number, char symbol);
sets the same char "symbol" in first "number" bytes.
Four data appending functions append data to the existing data. If needed, memory is allocated or reallocated. Data is appended the same way as strings are concatenated - there is only one trailing zero in the end of combined data.
1. int append(const StrBuffer& s);
2. int append(const char * string);
appends a zero terminated string "string".
3. int append(const char * from, int size);
appends "size" bytes from the location "from"
4. int append(int number, char symbol);
appends "number" bytes and sets them to "symbol".
A data shifting function
int shift(int bytes);
shifts data "bytes" bytes forward with trailing zero.
Protected Members and Methods are self-explanatory:
int increment;
int copy(const StrBuffer& s);
int allocate(int size);
They are protected and not private that one can derive from the StrBuffer class.