std::ios_base::xalloc (3) - Linux Manuals

std::ios_base::xalloc: std::ios_base::xalloc

NAME

std::ios_base::xalloc - std::ios_base::xalloc

Synopsis

static int xalloc();

Returns a unique (program-wide) index value that can be used to access one long and one void* elements in the private storage of std::ios_base by calling iword() and pword(). The call to xalloc does not allocate memory.

This function is thread-safe; concurrent access by multiple threads does not result in a data race.
(since C++14)
Effectively increments a private static data member of std::ios_base, as if by executing return index++;, if index is the name of that static member
(which may be std::atomic to support concurrent access by multiple threads, or otherwise synchronized)
(since C++14)

Parameters

(none)

Return value

Unique integer for use as pword/iword index.

Example

Uses base class pword storage for runtime type identification of derived stream objects.
// Run this code

  #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';
  }

Output:

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