Growing String Package


It is often necessary to construct a string character by character,
without knowing in advance how long the string may be. However, it is
known in advance that nearly all such strings will be reasonably short.

This package handles such tasks with reasonable efficiency.

First, define a variable of type "gstring":

    gstring g;

The constructor creates an empty string and allocates one block of
memory for it. The block is allocated as part of g for maximum
efficiency when the string never grows beyond the original block.

Then use the << operator to append characters and strings:

    g << 'a' << "bcd" << 'e';
    g << "hello";

If the string grows beyond the original block size, the package
automatically calls on the "new" allocator for more memory.

A special member function is available to append a string that is not
nul-terminated:

    g.append(s, slen);

    const char *s;        pointer to first character of string to be
                          appended

    unsigned slen;        length of string to be appended

To retrieve the constructed string, just call the member function
"string":

    char *s = g.string();

This function calls on the "new" allocator for a space just long enough
to hold the string (including the terminating nul, of course), and
copies the string into it. It then returns a pointer to the first
character.

It is the responsibility of the calling program to deallocate the string
when it is no longer needed:

    delete [] s;

The destructor for the "gstring" class will deallocate any memory
allocated internally by the package.

The package will fail catastrophically if the "new" allocator returns
NULL. The calling program should provide for some appropriate action in
this case.

The block size is defined in GSTRING.H as 32. This value may be changed,
but of course it must be positive!


