The Strings subsystem was rewritten since the last prerelease version of ODF (1.0d11). The subsystem was modified to work more closely with the OpenDoc ODIText data structure, improving compatiblity with OpenDoc and improving support for international character sets. The Strings chapter from the ODF Class Reference could not be updated in time for this release; so this document serves as the primary reference for the Strings subsystem.
Overview
The Strings subsystem provides only a few public classes, and most ODF parts will need to use only one of these classes: FW_CString. FW_CString supports localizable strings. A string is a run of characters from one locale. The run of characters is stored as a contiguous sequence of bytes. The OpenDoc ODIText data structure is used for the actual storage of the bytes. The ODIText data structure is stored inside a private ODF data structure (FW_SPrivStringRep), along with a reference count. FW_CString objects can share string storage, and use copy-on-write semantics to defer the duplication of string storage until absolutely necessary, thus eliminating unneeded duplication (improving performance in both space and time).
FW_CString provides a rich API for manipulating strings. Functions exist to Append, Insert, and Prepend characters to a string, where the characters may be provided in several forms (NUL terminated ISO string, pointer and length, another FW_CString, an ODIText, etc.). Other functions exist to do simple search and replace operations, to monocase, truncate, etc. Accessor functions exist to get the length in bytes and the length in characters. Other functions exist to convert a number into a string representation, or to parse a string to extract a number. See the FW_CString class interface for a complete list of functions.
If your part's needs for strings are simple (and we expect most parts to be), you may not need to know anything else about the Strings subsystem. However, you may want to quickly skim through the remainder of this document so that you'll be aware of what other features the Strings subsystem provides.
In addition to the class FW_CString, there are two subclasses FW_CString32 and FW_CString255. These classes add arrays of 32 bytes and 256 bytes respectively to the string object, and the string object is initialized to use this storage instead of dynamically allocating storage for the string. You may want to consider using these classes for stack-based strings local to a function, though the savings will probably be minimal in normal circumstances.
The Strings subystem also provides classes for iterating through text data structures a character at a time. These classes includes the class FW_CTextReader and its subclasses FW_CStringReader and FW_CMemoryReader, and the class FW_CTextWriter and its subclasses FW_CStringWriter and FW_CMemoryWriter. You can also make your own subclasses of FW_CTextReader and FW_CTextWriter for interfacing to your own text data structures. These classes may be useful if you have algorithms for processing text that must operate on various data structures that don't share a common base class.
What's Changed Since 1.0d11
If you have used ODF Strings from any of the prereleases of ODF, you should be aware of the following:
1) FW_CString and subclasses are now reference-counted with copy-on-write behavior (explained below). This doesn't affect APIs or the way you use strings.
2) FW_CDynamicString no longer exists. Use FW_CString instead.
3) The String tool classes were eliminated. Much of there functionality was integrated into FW_CString member functions.
4) Ranges of bytes are now used instead of ranges of characters. Member functions that took FW_CharacterCount parameters now take FW_ByteCount parameters; likewise FW_CharacterPosition parameters are now FW_BytePosition parameters. (In single-byte character sets byte counts and character counts are the same. When double-byte characters are used, there will be more bytes than characters).
Theory of Operation
For anyone curious as to how ODF Strings work, the following information may be useful.
The bulk of the implementation of the Strings subsystem is contained in ODFLibrary. The ODFFoundation static library contains thin C++ wrapper classes that call the Strings API exported by the ODFLibrary. From a user's perspective, this separation of code should be invisible.
The ODFLibrary defines the following types:
struct FW_SPrivStringRep;
// An opaque data structure!
typedef FW_SPrivStringRep* FW_HString;
// A handle to a string. The preferred way to reference a PrivStringRep
The ODFFoundation static library defines a class FW_CString, which has a protected FW_String data member:
The class FW_CString is the thin wrapper class. It has a single data member, fRep, which is an FW_HString. All member functions in FW_CString are forwarded to the Strings API defined in the ODFLibrary. The Strings API in the ODFLibrary is a collection of extern "C" functions, not C++ member functions. These functions all take an FW_HString parameter (which can be thought of as a "this" parameter), and operate on the private data pointed to by the FW_HString. The FW_CString class passes its fRep member to these functions.
The private data structure (FW_CPrivStringRep) pointed to by an FW_HString is designed to be shared, and maintains a references count of the number of references to it. The FW_CString class implements the sharing and reference counting protocol. This means that copying an FW_CString object is a very inexpensive operation. Consider the following code:
void Foo(const FW_CString& aString)
{
FW_CString aCopy;
...
aCopy = aString;
...
}
When the assignment executes, the string aCopy must decrement the reference count of the representation object it currently is using, copy the FW_HString pointer from the aString object, and then increment the reference count for that representation object. The storage for the string is not copied, but is simply reused.
Of course, if multiple strings are sharing the same storage, and one of them attempts to modify the storage, it's necessary to make sure that not all FW_CString's using that storage are modified. To prevent this, FW_CString uses copy-on-write semantics. Whenever an FW_CString member function is executed that could potentially modify the string, the reference count of the representation object is checked. If the reference count is one, then no other FW_CString could be also be using the representation, so the representation is directly modified. If the reference count is greater than one, the FW_CString object being modifed duplicates the representation object, decrements the reference count of the original, and sets the reference count of the new copy to 1. The FW_CString is then attached to the new representation object, which can then be safely modified without affecting other FW_CStrings.
