ark::serialization::InputStream

Defined in header “ark/serialization/input_stream.hh”.

An input stream allows you to deserialize data from a stream and into appropriate C++ primitives, safely. It is the lowest level primitive in the serialization stack.

Methods

  • InputStream()
    Constructor. Initializes an empty input stream.

  • InputStream(const std::vector< uint8_t > & data)
    Constructor. Initializes an input stream that wraps the given buffer of bytes.

    You retain ownership of the vector, so if the vector falls out of scope, this input stream will be invalid.

  • InputStream(const core::ByteBuffer & data)
    Constructor. Initializes an input stream that wraps the given buffer of bytes.

    You retain ownership of the buffer, so if the buffer falls out of scope, this input stream will be invalid.

  • InputStream(const OutputStream & stream)
    Constructor. Initializes an input stream that wraps the given output stream. This is a convenience constructor.

    You retain ownership of the output stream, so if it falls out of scope, this stream will be invalid.

  • void read_bitstream_header()
    Reads a bitstream header from the stream. These headers typically denote the start of a new serialized structure, and indicate version information or if different sections are present.

    In the future, this will return that information. For now, there is only one version supported, so this throws if we get anything unexpected.

  • void read(Type & type)
    A primary dispatcher this allows you to dispatch between reading primitives in, and reading more complex classes recursively.

  • Type read()
    A helper routine for reading and returning, rather than reading into a by-reference object. Otherwise, has identical semantics to read().

  • void read_primitive(bool & value)
    These routines read their respective primitives from the underlying bitstream.

  • void read_primitive(int8_t & value)

  • void read_primitive(int16_t & value)

  • void read_primitive(int32_t & value)

  • void read_primitive(int64_t & value)

  • void read_primitive(uint8_t & value)

  • void read_primitive(uint16_t & value)

  • void read_primitive(uint32_t & value)

  • void read_primitive(uint64_t & value)

  • void read_primitive(float & value)

  • void read_primitive(double & value)

  • void read_primitive(std::string & value)

  • void read_primitive(std::chrono::nanoseconds & value)

  • void read_primitive(std::chrono::steady_clock::time_point & value)

  • void read_primitive(std::chrono::system_clock::time_point & value)

  • void read(std::vector< Type > & value)
    Reads in a vector of objects. Existing content will be overwritten.

    The ‘Type’ parameter represents the type that you are ultimated copying into, whereas the ‘DeserializeAsType’ is the type that the system will deserialize as. This is useful in a few rare occasions (for example, if you have a vector of variants).

  • void read(std::vector< Type > & value, uint32_t size)
    Reads in a vector of objects. Existing content will be overwritten. The ‘size’ parameter indicates the number of items to read in.

    The ‘Type’ parameter represents the type that you are ultimated copying into, whereas the ‘DeserializeAsType’ is the type that the system will deserialize as. This is useful in a few rare occasions (for example, if you have a vector of variants).

  • void read(std::array< Type, ArraySize > & value)
    Reads in a array of objects. Existing content will be overwritten. The ‘size’ template parameter indicates the number of items to read in.

    The ‘Type’ parameter represents the type that you are ultimated copying into, whereas the ‘DeserializeAsType’ is the type that the system will deserialize as. This is useful in a few rare occasions (for example, if you have a vector of variants).

  • void read(std::map< Key, Value > & value)
    Reads in a map of objects. This just inserts pairs directly into a map, so if the map already has content, that content is not over-written.

    See the comment on reading with vectors as to why we have a separate ‘deserialize as type’.

  • void read(IndexedVariant< VariantSubtypes… > && value)
    Reads in a variant. This is based off the type information and the existing index.

  • void read(std::variant< VariantSubtypes… > & value, const std::array< uint8_t, sizeof…(VariantSubtypes)> & index)
    Reads in a variant. This is based off the type information and the existing index.

  • void read(std::optional< std::variant< VariantSubtypes… » & value, const std::array< uint8_t, sizeof…(VariantSubtypes)> & index)
    Reads in a variant. This is based off the type information and the existing index.

  • void read(std::optional< Type > & type)
    Reads in an optional pointing at an underlying supported type. This type must be serializable (or a primitive/fundamental type). The type will be unset if the optional is not set in the bitstream.

  • void read_bytes(void *data __attribute__, size_t size)
    Reads an arbitrary number of bytes from the given bitstream. Used internally from other read() calls. Advances the read pointer by size bytes.

  • std::string_view peek(size_t bytes)
    Peeks at the next N bytes from the given cursor, returning them wrapped in a string_view. This does not advance the cursor, but will throw if you don’t have enough bytes to peek at.

  • const uint8_t * advance(size_t bytes)
    Advances the cursor forward the given number of bytes. A pointer to the data at the original cursor location is returned.

    This can be used to ‘read’ data from the stream without making any copies, which can be advantageous for large blobs.

  • bool has_more_sections()
    Returns true if this stream has additional sections to read, or false otherwise.

  • ParsedOptionalGroupHeader read_optional_group_header()
    Reads the next optional group header at the current cursor location, returning the expected size and group identifier of the header.

  • size_t remaining_size()
    Return the remaining number of bytes in the bitstream.