std::ios_base::pword

void*& pword( int index );

Сначала выделяет или изменяет размер частного хранилища (динамического массива из void* или другой индексируемой структуры данных), чтобы index стал допустимым индексом, а затем возвращает ссылку на элемент void* частного хранилища с индексом index.

Ссылка может стать недействительной в результате любой операции над этим объектом ios_base, включая другой вызов pword(), однако сохранённые значения остаются неизменными, поэтому чтение из pword(index) с тем же индексом позднее вернёт то же значение до следующего вызова std::basic_ios::copyfmt(). Значение можно использовать для любых целей. Индекс элемента необходимо получить с помощью xalloc(), иначе поведение не определено. Новые элементы инициализируются нулевым указателем.

Если функция завершается с ошибкой (возможно, из-за сбоя выделения памяти), а *this является базовым подобъектом класса объекта или подобъекта basic_ios<>, вызывается std::basic_ios<>::setstate(badbit), который может выбросить std::ios_base::failure.

Параметры

индекс

значение индекса элемента

Возвращаемое значение

Ссылка на элемент.

Исключения

При установке badbit может быть выброшено исключение std::ios_base::failure.

Примечания

Если указатели, хранящиеся в pword, требуют управления, register_callback() можно использовать для установки обработчиков, выполняющих при необходимости глубокое копирование или освобождение памяти.

Пример

Использует хранилище pword базового класса для идентификации типа производных объектов потоков во время выполнения.

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

Вывод:

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

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были ретроактивно применены к ранее опубликованным стандартам C++.

DR	Применено к	Поведение согласно опубликованному стандарту	Правильное поведение
LWG 36	C++98	сохранённое значение могло не сохраняться, если ссылка становилась недействительной	сохранённое значение сохраняется до следующего вызова `copyfmt()`
LWG 41	C++98	при сбое функция сама устанавливала badbit, но `ios_base` не предоставляет такого интерфейса	badbit устанавливается функцией `basic_ios` (если `*this` является её базовым подобъектом класса)

См. также

iword	при необходимости изменяет размер частного хранилища и предоставляет доступ к элементу типа long с заданным индексом (открытая функция-член)
xalloc [static]	возвращает уникальное в пределах программы целое число, безопасное для использования в качестве индекса для `pword()` и `iword()` (открытая статическая функция-член)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/io/ios_base/pword