std::ios_base:: pword

First, allocates or resizes the private storage (dynamic array of void * or another indexable data structure) sufficiently to make index a valid index, then returns a reference to the void * element of the private storage with the index index .

The reference may be invalidated by any operation on this ios_base object, including another call to pword() , but the stored values are retained, so that reading from pword ( index ) with the same index later will produce the same value until the next call to std::basic_ios::copyfmt() . The value can be used for any purpose. The index of the element must be obtained by xalloc() , otherwise the behavior is undefined. New elements are initialized to a null pointer .

If the function fails (possibly caused by an allocation failure) and * this is a base class subobject of a basic_ios<> object or subobject, calls std:: basic_ios <> :: setstate ( badbit ) which may throw std::ios_base::failure .

Parameters

Return value

A reference to the element.

Exceptions

May throw std::ios_base::failure when setting the badbit.

Notes

If the pointers stored in pword require management, register_callback() may be used to install handlers that execute deep copy or deallocation as needed.

Example

#include <iostream>
 
template<class CharT, class Traits = std::char_traits<CharT>>
class mystream : public std::basic_ostream<CharT, Traits>
{
public:
    static const int xindex;
 
    mystream(std::basic_ostream<CharT, Traits>& ostr) :
        std::basic_ostream<CharT, Traits>(ostr.rdbuf())
    {
        this->pword(xindex) = this;
    }
 
    void myfn()
    {
        *this << "[special handling for mystream]";
    }
};
 
// Each specialization of mystream obtains a unique index from xalloc()
template<class CharT, class Traits>
const int mystream<CharT, Traits>::xindex = std::ios_base::xalloc();
 
// This I/O manipulator will be able to recognize ostreams that are mystreams
// by looking up the pointer stored in pword
template<class CharT, class Traits>
std::basic_ostream<CharT, Traits>& mymanip(std::basic_ostream<CharT, Traits>& os)
{
    if (os.pword(mystream<CharT, Traits>::xindex) == &os)
        static_cast<mystream<CharT, Traits>&>(os).myfn();
    return os;
}
 
int main()
{
    std::cout << "cout, narrow-character test " << mymanip << '\n';
 
    mystream<char> myout(std::cout);
    myout << "myout, narrow-character test " << mymanip << '\n';
 
    std::wcout << "wcout, wide-character test " << mymanip << '\n';
 
    mystream<wchar_t> mywout(std::wcout);
    mywout << "mywout, wide-character test " << mymanip << '\n';
}

cout, narrow-character test
myout, narrow-character test [special handling for mystream]
wcout, wide-character test
mywout, wide-character test [special handling for mystream]

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also