std::ios_base::iword
long& iword( int index ); |
||
First, allocates or resizes the private storage (dynamic array of long or another indexable data structure) sufficiently to make index a valid index, then returns a reference to the long 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 iword()
, but the stored values are retained, so that reading from iword(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 a previous call to xalloc(), otherwise the behavior is undefined. New elements are initialized to 0.
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.
Notes
Typical use of iword storage is to pass information (e.g. custom formatting flags) from user-defined I/O manipulators to user-defined operator<<
and operator>>
or to user-defined formatting facets imbued into standard streams.
Parameters
index | - | index value of the element |
Return value
A reference to the element.
Exceptions
May throw std::ios_base::failure when setting the badbit.
Example
#include <iostream> #include <string> struct Foo { static int foo_xalloc; std::string data; Foo(const std::string& s) : data(s) {} }; // Allocates the iword storage for use with Foo objects int Foo::foo_xalloc = std::ios_base::xalloc(); // This user-defined operator<< prints the string in reverse if the iword holds 1 std::ostream& operator<<(std::ostream& os, Foo& f) { if (os.iword(Foo::foo_xalloc) == 1) return os << std::string(f.data.rbegin(), f.data.rend()); else return os << f.data; } // This I/O manipulator flips the number stored in iword between 0 and 1 std::ios_base& rev(std::ios_base& os) { os.iword(Foo::foo_xalloc) = !os.iword(Foo::foo_xalloc); return os; } int main() { Foo f("example"); std::cout << f << '\n' << rev << f << '\n' << rev << f << '\n'; }
Output:
example elpmaxe example
Defect reports
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 by basic_ios (if *this is its base class subobject) |
See also
resizes the private storage if necessary and access to the void* element at the given index (public member function) | |
[static] |
returns a program-wide unique integer that is safe to use as index to pword() and iword() (public static member function) |