Base Library

The library is implemented in several layers, as described in the previous chapter. The base library is used by all the others, containing functions to deal with the following major functions:

• Safe Strings
• malloc/free

These are described in the following sections.

Safe Strings

Strings are notorious for causing trouble in C code. Instead of using them, we choose to use a library that implements a safer string. This library is called the Better String Library, and is written by Paul Hsieh. It is available from: http://bstring.sourceforge.net. The basic idea is to have the string and metadata about the string in a struct, and the struct is used in the code, not the string, as shown in the code fragment below:

struct tagbstring {
    int mlen;
    int slen;
    unsigned char * data;
};

Note that the string part of this struct is named data, while the length of the valid data in the string is stored in slen, and the number of bytes allocated to data is stored in mlen. As needed, the string part of this struct is allocated, reallocated and deallocated, so that there are fewer errors by the programmer. Note that a bstring must be initialized before most of the bstring functions can operate on it sensibly. The typical usage of this new datatype is supported by many functions, a few of which are shown below:

• declaring it: bstring str1
• declaring and allocating it: bstring str1 = bfromcstr("")
• get the c-string from the bstring: bdata(bstring b)
• assign a c-string to a bstring: bassigncstr(b, "")
• sprintf: bassignformat(b, "format", variables, ...)
• refer to a character in the string: bchar(b, index)
• copy a bstring to another bstring, which may not be initialized yet: name = bstrcpy(filename)
• deallocate: bdestroy(b)
• strlen: blength(b)
• strcpy: bassign(a,b)
• strstr: binstr(b, pos, c)
• strcat: bconcat(b, c)
• constant strings: bsstatic("blah")
• reading from a file:

bstring theline = bfromcstr("");
struct bStream * bstream;
FILE *fp;
fp =fopen("name","access");
bstream = bsopen ((bNread) fread, fp);
bsread(theline,bstream,10);
bsclose(bstream);
fclose(fp);

Malloc/Free

We have an implementation of malloc/free called GMalloc/GFree that is used everywhere in our library. This currently is a thin layer on top of the C standard malloc/free. THe basic idea here is to not free null pointers, and to have stubs that can be rewritten later if needed, without having to rewrite all of our existing code.

Other things that are available in the base.h file are: definitions for TRUE and FALSE, macros MIN, MAX, ABS, bstring-comparisons: EQUAL, and EQUALN, block-copy macros: ByteCopy and BstringCopy, and a few other constants and typedefs.

next: HDF5 Abstraction Library