| I/O manipulators | ||||
| Print functions(C++23) | ||||
| C-style I/O | ||||
| Buffers | ||||
(C++23) | ||||
(C++98/26*) | ||||
(C++20) | ||||
| Streams | ||||
| Abstractions | ||||
| File I/O | ||||
| String I/O | ||||
| Array I/O | ||||
(C++23) | ||||
(C++23) | ||||
(C++23) | ||||
(C++98/26*) | ||||
(C++98/26*) | ||||
(C++98/26*) | ||||
| Synchronized Output | ||||
(C++20) | ||||
| Types | ||||
| Error category interface | ||||
(C++11) | ||||
(C++11) |
| Member functions | ||||
| Formatting | ||||
| Locales | ||||
| Internal extensible array | ||||
ios_base::pword | ||||
| Miscellaneous | ||||
| Member classes | ||||
| Member types | ||||
void*& pword(int index); | ||
First, allocates or resizes the private storage (dynamic array ofvoid* or another indexable data structure) sufficiently to makeindex a valid index, then returns a reference to thevoid* element of the private storage with the indexindex.
The reference may be invalidated by any operation on thisios_base object, including another call topword(), but the stored values are retained, so that reading frompword(index) with the same index later will produce the same value until the next call tostd::basic_ios::copyfmt(). The value can be used for any purpose. The index of the element must be obtained byxalloc(), otherwise the behavior is undefined. New elements are initialized to anull pointer.
If the function fails (possibly caused by an allocation failure) and*this is a base class subobject of abasic_ios<> object or subobject, callsstd::basic_ios<>::setstate(badbit) which may throwstd::ios_base::failure.
Contents |
| index | - | index value of the element |
A reference to the element.
May throwstd::ios_base::failure when setting the badbit.
If the pointers stored inpword require management,register_callback() may be used to install handlers that execute deep copy or deallocation as needed.
Uses base class pword storage for runtime type identification of derived stream objects.
#include <iostream> template<class CharT,class Traits=std::char_traits<CharT>>class mystream:publicstd::basic_ostream<CharT, Traits>{public:staticconstint 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>constint 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 pwordtemplate<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';}
Output:
cout, narrow-character testmyout, narrow-character test [special handling for mystream]wcout, wide-character testmywout, wide-character test [special handling for mystream]
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 36 | C++98 | the stored value might not be retained if the reference is invalidated | the stored value is retained until the next call of copyfmt() |
| LWG 41 | C++98 | the function set badbit by itself on failure, but ios_base does not provide such interface | badbit is set bybasic_ios(if*this is its base class subobject) |
| resizes the private storage if necessary and access to thelong element at the given index (public member function)[edit] | |
[static] | returns a program-wide unique integer that is safe to use as index topword() andiword() (public static member function)[edit] |
