# std::ios_base::iword

> C++ Atlas: `cppatlas.com/w/cpp/io/ios_base/iword` | Source: https://en.cppreference.com/w/cpp/io/ios_base/iword | Domain: Input/output

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.

## Official Specification Summary (cppreference)

```cpp
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

```cpp
#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:

```text
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

- [`pword`](https://en.cppreference.com/w/cpp/io/ios_base/pword): resizes the private storage if necessary and access to the `void*` element at the given index (public member function)
- [`xalloc`](https://en.cppreference.com/w/cpp/io/ios_base/xalloc) [static]: returns a program-wide unique integer that is safe to use as index to `pword()` and `iword()` (public static member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/io/ios_base/iword (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.