std::ios_base::xalloc

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Input/output library

I/O manipulators

C-style I/O

Buffers

basic_streambuf

basic_filebuf

basic_stringbuf

strstreambuf (deprecated)

basic_syncbuf (C++20)

Streams

Abstractions

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

File I/O

basic_ifstream

basic_ofstream

basic_fstream

String I/O

basic_istringstream

basic_ostringstream

basic_stringstream

Array I/O

istrstream (deprecated)

ostrstream (deprecated)

strstream (deprecated)

Synchronized Output

basic_osyncstream (C++20)

Types

streamoff

streamsize

fpos

Error category interface

iostream_category (C++11)

io_errc (C++11)

std::ios_base

Member functions

ios_base::ios_base

ios_base::~ios_base

Formatting

ios_base::flags

ios_base::setf

ios_base::unsetf

ios_base::precision

ios_base::width

Locales

ios_base::imbue

ios_base::getloc

Internal extensible array

ios_base::xalloc

ios_base::iword

ios_base::pword

Miscellaneous

ios_base::register_callback

ios_base::sync_with_stdio

Member classes

ios_base::failure

ios_base::Init

Member types

ios_base::openmode

ios_base::fmtflags

ios_base::iostate

ios_base::seekdir

ios_base::event

ios_base::event_callback

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]

See also

pword	resizes the private storage if necessary and access to the void* element at the given index (public member function)
iword	resizes the private storage if necessary and access to the long element at the given index (public member function)