C++ IOS Library - Pword

---

---

Description

It is used to get pointer element of extensible array and returns a reference to the object of type void* which corresponds to index idx in the internal extensible array.

If idx is an index to a new element and the internal extensible array is not long enough (or is not yet allocated), the function extends it (or allocates it) with as many elements initialized to null pointers as necessary.

The reference returned is guaranteed to be valid at least until another operation is performed on the stream object, including another call to pword. Once another operation is performed, the reference may become invalid, although a subsequent call to this same function with the same idx argument returns a reference to the same value within the internal extensible array.

The internal extensible array is a general-purpose array of objects of type long (if accessed with member iword) or void* (if accessed with member pword). Libraries may implement this array in diverse ways: iword and pword may or may not share a unique array, and they may not even be arrays, but some other data structure.

Declaration

Following is the declaration for ios_base::pword function.

void*& pword (int idx);

Parameters

idx − An index value for an element of the internal extensible array and some implementations expect idx to be a value previously returned by member xalloc.

Return Value

This value is returned as a reference to an object of type void*.

Exceptions

Basic guarantee − if an exception is thrown, the stream is in a valid state.

Data races

May modify the stream object. The returned value may also be used to modify it. Concurrent access to the same stream object may cause data races.

Example

In below example explains about ios_base::pword function.

#include <iostream>     

const int name_index = std::ios::xalloc();

void SetStreamName (std::ios& stream, const char* name) {
   stream.pword(name_index) = const_cast<char*>(name);
}

std::ostream& StreamName (std::ostream& os) {
   const char* name = static_cast<const char*>(os.pword(name_index));
   if (name) os << name;
   else os << "(unknown)";
   return os;
}

int main() {
   SetStreamName(std::cout, "standard output stream");
   SetStreamName(std::cerr, "standard error stream");
   std::cout << StreamName << '\n';
   std::cerr << StreamName << '\n';
   std::clog << StreamName << '\n';
   return 0;
}

Let us compile and run the above program, this will produce the following result −

standard output stream
standard error stream
(unknown)