Consider the inserter and extractor we defined for a date class in Section 32.3. The input and output operations were internationalized and relayed the task of date formatting and parsing to the stream object's locale. Here, however, the rules for formatting and parsing were fixed, making them much more restricted than the features available in the Standard C Library, for example.
In the Standard C Library, you can specify format strings, similar to those for printf() and scanf(), that describe the rules for parsing and formatting dates. (See the POSIX functions strftime(), strptime(), and wcsftime() for reference.) For example, the format string "%A, %B %d, %Y" stands for the rule that a date must consist of the name of the weekday, the name of the month, the day of the month, and the year -- as in Friday, July 12, 1996 in the C or POSIX locales.
Now imagine you want to improve the input and output operations for the date class by allowing specification of such format strings. How can you do this? Other format information is stored in the stream object's format state; consequently, you may want to store the format string for dates somewhere in the stream as well. And indeed, you can.
Each stream object maintains two dynamically sized arrays: an array of elements of type long, and an array of elements of type void*. The arrays are exposed via two members of the std::ios_base class. The memory occupied by the arrays (but not necessarily the memory the void* elements point to) is managed by the stream objects. It is allocated and reallocated as needed and deallocated when each object is destroyed.
You can use the arrays to store in a stream object whatever additional information you might need. In our example, we would want to store the format string.
The functions that allow access to the arrays are std::ios_base::iword() and std::ios_base::pword(). Both functions take an index to an array element and return a reference to the respective element.
int std::ios_base::xalloc(); long& std::ios_base::iword (int index); void*& std::ios_base::pword (int index);
The static member function std::ios_base::xalloc() returns a unique index that can be used in subsequent calls to iword() and pword(). Note that since the functions may need to grow the internal array to accomodate the index, using indices with large magnitude will lead to large amounts of memory being allocated.