11.2 InfString, a class supporting unbounded strings

Class InfString provides a mechanism for building strings of unbounded size. It provides a subset of the functions in a typical C++ String class. Strings can be built up piece by piece. As segments are added, they are copied, so the caller need not keep the segments around. Upon casting to (char*), the strings are collapsed into one continuous string, and a pointer to that string is returned. The calling function can treat this as an ordinary pointer to an ordinary array of characters, and can modify the characters. But the length of the string should not be changed, nor should the string be deleted. The InfString destructor is responsible for freeing the allocated memory. InfString is publically derived from StringList, adding only the cast char*. Its internal implementation is as a list of char* strings, each on the heap. The individual substrings retain their separate identity until the conversion cast to type char* is invoked, although if access to the individual strings is needed, then StringList should be used. There are also operators that add numeric values to the StringList; there is only one format available for each such addition. WARNING: if a function or expression returns an InfString, and that value is not assigned to an InfString variable or reference, and the (char*) cast is used, it is possible (likely under g++) that the InfString temporary will be destroyed too soon, leaving the char* pointer pointing to garbage. Always assign temporary InfString to InfString variables or references before using the char* conversion. Thus, instead of

function_name(xxx,(char*)functionReturningInfString(),yyy);

one should use

InfString temp_name = (char*)functionReturningInfString();
function_name(xxx,temp_name,yyy);

This includes code like

strcpy(destBuf,functionReturningInfString());

which uses the char* conversion implicitly.

11.2.1 InfString constructors and assignment operators

The default constructor makes an empty InfString. There is also a copy constructor and six single-argument constructors that can function as conversions from other types to type InfString; they take arguments of the types char, const char*, int, double, unsigned int, and const StringList&. There are also seven assignment operators corresponding to these constructors: one that takes a const InfString& argument and also one for each of the six standard types: char, const char*, int, double, unsigned int, and const StringList&.

11.2.2 Adding to InfStrings

There are seven functions that can add a printed representation of an argument to a InfString: one each for arguments of type const InfString&, char, const char*, int, double, unsigned int, and const StringList&. In each case, the function can be accessed in either of two equivalent ways:

InfString& operator += (type arg);
InfString& operator << (type arg);

The second "stream form" is considered preferable; the "+=" form is there for backward compatibility. If a InfString object is added, each piece of the added InfString is added separately (boundaries between pieces are preserved); for the other five forms, a single piece is added.

11.2.3 InfString information functions

int length() const;

Return the length in characters.

11.2.4 InfString conversion to char *

operator char* ();

This function joins all the substrings in the InfString into a single piece, a returns a pointer to the resulting string. A null pointer is always returned if there are no characters. Warning: as pointed out above, if this function is called on a temporary InfString, it is possible that the compiler will delete the InfString object before the last use of the returned char* pointer. The result is that the pointer may wind up pointing to garbage. The best work-around for such problems is to make sure that any InfString object "has a name" before this conversion is applied to it; e.g. assign the results of functions returning InfString objects to local InfString variables or references before trying to convert them.

char* newCopy() const;

This function makes a copy of the InfString's text in a single piece as a char* in dynamic memory. The InfString object itself is not modified. This is useful when the caller wishes to be responsible for deletion of the returned text.

11.2.5 InfString destruction and zeroing

void initialize();

This function deallocates all pieces of the InfString and changes it to an empty InfString.

~InfString();

The destructor calls the initialize function.

11.2.6 Class InfStringIter

Class InfStringIter is a standard iterator that operates on InfStrings. However, the InfString class is not intended for use when access to the individual components of the string is desired. Use StringList for this.