StringList provides a mechanism for organizing a list of strings. It can also be used to construct strings of unbounded size, but the class InfString is preferred for this. It is privately derived from SequentialList. Its internal implementation is as a list of char* strings, each on the heap. A StringList object can be treated either as a single string or as a list of strings; the individual substrings retain their separate identity until the conversion operator to type const char* is invoked. There are also operators that add numeric values to the StringList; there is only one format available for such additions. WARNING: if a function or expression returns a StringList, and that value is not assigned to a StringList variable or reference, and the (const char*) cast is used, it is possible (likely under g++) that the StringList temporary will be destroyed too soon, leaving the const char* pointer pointing to garbage. Always assign a temporary StringList to a StringList variable or reference before using the const char* conversion. Thus, instead of
function_name(xxx,(const char*)functionReturningStringList(),yyy);one should use
StringList temp_name = (const char*)functionReturningStringList();This includes code like
function_name(xxx,temp_name,yyy);
strcpy(destBuf,functionReturningStringList());which uses the
const char* conversion implicitly.
StringList. There is also a copy constructor and five single-argument constructors that can function as conversions from other types to type StringList; they take arguments of the types char, const char *, int, double, and unsigned int. There are also six assignment operators corresponding to these constructors: one that takes a const StringList& argument and also one for each of the five standard types: char, const char *, int, double, and unsigned int. The resulting object has one piece, unless initialized from another StringList in which case it has the same number of pieces.
StringList: one each for arguments of type const StringList&, char, const char *, int, double, and unsigned int. In each case, the function can be accessed in either of two equivalent ways:
StringList& operator += (type arg);The second "stream form" is considered preferable; the "+=" form is there for backward compatibility. If a
StringList& operator << (type arg);
StringList object is added, each piece of the added StringList is added separately (boundaries between pieces are preserved); for the other five forms, a single piece is added.
const char* head() const;Return the first substring on the list (the first "piece"). A null pointer is returned if there are none.
int length() const;Return the length in characters.
int numPieces() const;Return the number of substrings in the
StringList.
operator const char* ();This function joins all the substrings in the
StringList into a single piece, so that afterwards numPieces will return 1. A null pointer is always returned if there are no characters. Warning: if this function is called on a temporary StringList, it is possible that the compiler will delete the StringList object before the last use of the returned const char * pointer. The result is that the pointer may wind up pointing to garbage. The best way to work around such problems is to make sure that any StringList object "has a name" before this conversion is applied to it; e.g., assign the results of functions returning StringList objects to local StringList variables or references before trying to convert them.
char* newCopy() const;This function makes a copy of the
StringList's text in a single piece as a char* in dynamic memory. The object itself is not modified. The caller is responsible for deletion of the returned text.
void initialize();This function deallocates all pieces of the
StringList and changes it to an empty StringList.
~StringList();The destructor calls the
initialize function.
StringListIter is a standard iterator that operates on StringLists. Its next() function returns a pointer of type const char* to the next substring of the StringList. It is important to know that the operation of converting a StringList to a const char* string joins all the substrings into a single string, so that operation should be avoided if extensive use of StringListIter is planned.