InputByteStreamRef::read_as

template <class PODType>
PODType read_as(); //1
template <class PODType, class ReadingPolicy>
/*см. ниже*/ read_as(ReadingPolicy); //2
template <class ContainerType>
ContainerType read_as(std::size_t cbHowMany); //3
template <class ContainerType, class ReadingPolicy>
/*см. ниже*/ read_as(std::size_t cbHowMany, ReadingPolicy); //4

Осуществляет чтение данных из потока InputByteStreamRef и создание из этих данных объекта PODType или контейнера байт.

1. Считывает объект POD типа.
2. Аналогично, но поведение метода кастомизируется политикой чтения.
3. Считывает данные в контейнер байт. Контейнер должен удовлетворять требованиям SequenceContainer.
4. Аналогично, но поведение метода кастомизируется политикой чтения.

Параметры шаблона

PODType	Тип возвращаемого перегрузками 1 и 2 объекта, данные которого считываются из потока InputByteStreamRef. Тип должен удовлетворять требованиям PODType.
ContainerType	Тип возвращаемого перегрузками 3 и 4 контейнера байт с содержимым, считанным из потока. Контейнер должен удовлетворять требованиям SequenceContainer, а тип его элемента должен соответствовать байту.
ReadingPolicy	Вычисляемый дедукцией тип политики чтения, используемой перегрузкой 2. Тип должен определять статическую константу компиляции value, содержащую битовую маску идентификаторов компонент политики. Эти идентификаторы заданы перечислением reading_policy_flags и имеют следующие значения. Символическое имя Целочисленное значение Описание force_fill_buffer 1 Операции чтения из потоков InputByteStreamRef блокируют осуществляющий чтение поток выполнения до тех пор, пока поданный на вход операции буфер не будет заполнен полностью, или операция чтения не будет явно отменена. Если данная политика не задана, операции чтения завершаются, как только из потока удается считать хоть какое-то количество данных, или происходит явная отмена операции. Например, если в результате неполного чтения достигнут конец данных, и флаг force_fill_buffer сброшен, операции чтения вернут управление вызывающей чтение стороне. Если же флаг установлен, операции чтения будут пытаться читать данные до тех пор, пока выходной буфер не будет заполен полностью, или операция чтения не будет отменена. get_error_code 2 Операции чтения возвращают коды ошибок типа return_code_t вместо генерации исключений для типичных ошибок чтения. Существует также метафункция reading_policy, которая позволяет задать маску политик шаблонными параметрами, как указано в примере ниже.

Параметры

cbHowMany

Количество байт, которые необходимо считать из потока в контейнер байт перегрузками 3 и 4.

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

Перегрузки 1 и 3 возвращают считанный объект напрямую. Значение, возвращаемое перегрузками 2 и 4, зависит от политики ReadingPolicy. Если флаг reading_policy_flags::get_error_code не устанавливается политикой, считанный объект возвращается напрямую аналогично перегрузкам 1 и 3. В противном случае возвращается пара std::pair значений std::pair<return_code_t, T>, где T эквивалентен типу PODType, если используется перегрузка 2, и типу ContainerType, если используется перегрузка 4. То есть возвращаемая пара содержит код завершения чтения в качестве первого элемента пары, считанный объект - в качестве второго.

См. также

IInputByteStream::ReadArray
InputByteStreamRef::read
InputByteStreamRef::read_all_as

Если чтение блокирует вызывающий поток выполнения, и эта блокировка прерывается нормальным образом (например, когда поток осуществляет чтение из интернет канала, и другой поток вызывает метод IInternetConnectionEndPoint::CancelOperations над этим каналом, или по TCP каналу связи поступает сигнал FIN)), перегрузки 2 и 4, в зависимости от значения флага политики reading_policy_flags::get_error_code, возвращают код успешного завершения CHSVERROR_SUCCESS_CANCELLED (0x2417000f) или генерирует исключение Chusov::Exceptions::OperationCancelledException. Перегрузки 1 и 3 в таких случаях всегда генерируют это исключение.

Пусть is - объект класса InputByteStreamRef. Тогда вызов перегрузки 1

is.read_as<T>();

эквивалентен вызову перегрузки 2 следующим образом.

is.read_as<T>(reading_policy<reading_policy_flags::force_fill_buffer>());

Аналогично вызов перегрузки 3

is.read_as<Container<T>>(N);

эквивалентен вызову перегрузки 4 следующим образом.

is.read_as<Container<T>>(N, reading_policy<reading_policy_flags::force_fill_buffer>());

В отличие от метода read_as метод read по умолчанию не использует политики reading_policy_flags::force_fill_buffer и не блокирует поток выполнения.

Если политика reading_policy_flags::force_fill_buffer отключена, возвращаемый объект может находиться в неопределенном состоянии, но оно всегда будет корректным.

Пример: чтение из потока с заполнением буфера полностью и с использованием сигнализации об ошибках чтения с помощью кода завершения (C++17).

#include <tuple>
#include <cstdint>
#include <camaas/istream.h>

std::uint32_t read_dword(CAMaaS::InputByteStreamRef is)
{
    auto [err, result] = is.read_as<std::uint32_t>(reading_policy<reading_policy_flags::get_error_code>());
    if (ChsvFailed(err))
        return std::uint32_t(-1);
    return result;
}

Пример: чтение из потока с заполнением буфера полностью и с генерацией исключений в случаях ошибок чтения.

#include <tuple>
#include <cstdint>
#include <camaas/istream.h>
#include <vector>

auto read_vector(CAMaaS::InputByteStreamRef is, std::size_t size)
{
    return is.read_as<std::vector<std::uint8_t>>(size);
}