Description

IO-related functions.

Functions
template<typename T >
void	ozo::fit_array_size (T &array, size_type count)
	Fits array container size to reqired one. More...

template<typename OidMap , typename Out >
istream &	ozo::recv (istream &in, oid_t oid, size_type size, const OidMap &oids, Out &out)
	Receive object from an input stream and control incoming oid. More...

template<typename OidMap , typename Out >
istream &	ozo::recv_data_frame (istream &in, const OidMap &oids, Out &out)
	Receive data frame of an object from an input stream. More...

template<typename OidMap , typename Out >
istream &	ozo::recv_frame (istream &in, const OidMap &oids, Out &out)
	Receive full frame of an object from an input stream. More...

template<class OidMap , class In >
ostream &	ozo::send (ostream &out, const OidMap &oid_map, const In &in)
	Send object to an output stream. More...

template<class OidMap , class In >
ostream &	ozo::send_data_frame (ostream &out, const OidMap &oid_map, const In &in)
	Send data frame of an object to an output stream. More...

template<class OidMap , class In >
ostream &	ozo::send_frame (ostream &out, const OidMap &oid_map, const In &in)
	Send full frame of an object to an output stream. More...

template<typename T >
constexpr size_type	ozo::size_of (const T &v)
	Returns size of object binary representation in bytes. More...

template<typename T >
constexpr size_type	ozo::data_frame_size (const T &v)
	Returns size of IO data frame. More...

template<typename T >
constexpr size_type	ozo::frame_size (const T &v)
	Returns size of full IO frame. More...

Function Documentation

◆ data_frame_size()

template<typename T >

constexpr size_type ozo::data_frame_size ( const T & v )

constexpr

Returns size of IO data frame.

Data frame contains a data and its size as first element. The data frame has this structure:

SECTION	SIZE
size	4 bytes
data	size_of(data) bytes

Parameters

v	— object to which size of a data frame is calculated

Returns: size_type — size of an object's data frame

References ozo::size_of().

Referenced by ozo::frame_size().

◆ fit_array_size()

template<typename T >

void ozo::fit_array_size	(	T &	array,
		size_type	count
	)

Fits array container size to reqired one.

Function is used to request container which represents an array to to be able to store requested count of elements. The function may throw exception if the container can not accept the requested count of elements (see the example below).

Parameters

array	— container which represents an array
count	— required count of elements to be able to contain

The implementation can be customized with ozo::fit_array_size_impl template specialization. By default it uses resize() function of the array container and default implementation may look like this

template <typename T>
struct fit_array_size_impl {
    static void apply(T& array, size_type count) {
        array.resize(count);
    }
};

E.g. the implementation for a fixed size container like std::array may be equal to:

template <typename T, std::size_t S>
struct fit_array_size_impl<std::array<T, S>> {
    static void apply(const std::array<T, S>& array, size_type size) {
        if (size != array.size()) {
            throw ozo::system_error(ozo::error::bad_array_size);
        }
    }
};

◆ frame_size()

template<typename T >

constexpr size_type ozo::frame_size ( const T & v )

constexpr

Returns size of full IO frame.

The full frame contains a data frame and object's type oid as a first element. The frame has this structure:

SECTION	SIZE
oid	4 bytes
size	4 bytes
data	size_of(data) bytes

Parameters

v	— object to which size of a frame is calculated

Returns: size_type — size of an object's frame

References ozo::data_frame_size().

◆ recv()

template<typename OidMap , typename Out >

istream& ozo::recv	(	istream &	in,
		oid_t	oid,
		size_type	size,
		const OidMap &	oids,
		Out &	out
	)

Receive object from an input stream and control incoming oid.

This function is used to get an object from an input stream. It checks:

incoming oid is acceptable by output object type — if oid can not be accepted by the type ozo::system_error with ozo::error::oid_type_mismatch will be thrown, it uses ozo::accepts_oid() for this check;
null state is acceptable — if output object is not #Nullable, but null state received then std::invalid_argument will be thrown.

For nullables the function allocates or resets nullables according to incoming data size which indicates null state via ozo::null_state_size. ozo::reset_nullable() and ozo::init_nullable() are used.

For deserialization implementation of simple objects like strings, integers, uuid and so on ozo::recv_impl is used. To deserialize complex types like Array or Composite special internal implementations are used.

Parameters

in	— input stream to read data from.
oid	— incoming oid type to check.
size	— incoming data size.
oids	— #OidMap to get oid for custom types from
out	— object to deserialize into

Returns: istream& — input stream

◆ recv_data_frame()

template<typename OidMap , typename Out >

istream& ozo::recv_data_frame	(	istream &	in,
		const OidMap &	oids,
		Out &	out
	)

Receive data frame of an object from an input stream.

This function is used to read from stream object's data frame to receive the object. E.g. it is used for array items deserialization. Data frame contains object's size and object's data. See ozo::data_frame_size() for more details about data frame.

Note: This function does not check objects oid on purpose.

Parameters

in	— input stream
oids	— #OidMap to determine possible nested object's oid
out	— object to receive

Returns: ostream& — reference to the input stream

References ozo::null_oid.

Referenced by ozo::recv_frame().

◆ recv_frame()

template<typename OidMap , typename Out >

istream& ozo::recv_frame	(	istream &	in,
		const OidMap &	oids,
		Out &	out
	)

Receive full frame of an object from an input stream.

This function is used to read from stream object's frame and receive the object. E.g. it is used for composite items deserialization. Frame contains object's type oid, object's size and object's data. See ozo::frame_size() for more details about the frame.

Note: The function uses ozo::recv underhood, so all the checks will be made.

Parameters

in	— input stream
oids	— #OidMap to determine object's oid
out	— object to receive

Returns: ostream& — reference to the output stream

References ozo::null_oid, and ozo::recv_data_frame().

◆ send()

template<class OidMap , class In >

ostream& ozo::send	(	ostream &	out,
		const OidMap &	oid_map,
		const In &	in
	)

Send object to an output stream.

This function is used to serialize object as query parameter. This function uses ozo::send_impl template specialization for simple types like integers, floating points, strings, uuid and so on. This behaviour may be customized via ozo::send_impl specialization. To serialize complex types like Array or Composite types special internal implementations are used. These implementation can not be customized. This function unwraps type via ozo::unwrap() thus it handles properly all nullables and wrapped types. If argument is #Nullable in null state the function does nothing. In the other case it calls ozo::send_impl::apply() method for unwrapped object.

Parameters

out	— output stream.
oid_map	— #OidMap to determine object's oid.
in	— object to send.

Returns: ostream& — reference to the output stream.

References ozo::is_null(), and ozo::unwrap().

Referenced by ozo::send_data_frame().

◆ send_data_frame()

template<class OidMap , class In >

ostream& ozo::send_data_frame	(	ostream &	out,
		const OidMap &	oid_map,
		const In &	in
	)

Send data frame of an object to an output stream.

This function is used to write into stream object's data frame. E.g. it is used for array items serialization. Data frame contains object's size and object's data. See ozo::data_frame_size() for more details about data frame.

Parameters

out	— output stream
oid_map	— #OidMap to determine object's oid
in	— object to send

Returns: ostream& — reference to the output stream

References ozo::send(), and ozo::size_of().

Referenced by ozo::send_frame().

◆ send_frame()

template<class OidMap , class In >

ostream& ozo::send_frame	(	ostream &	out,
		const OidMap &	oid_map,
		const In &	in
	)

Send full frame of an object to an output stream.

This function is used to write into stream object's frame. E.g. it is used for composite items serialization. Frame contains object's type oid, object's size and object's data. See ozo::frame_size() for more details about the frame.

Parameters

out	— output stream
oid_map	— #OidMap to determine object's oid
in	— object to send

Returns: ostream& — reference to the output stream

References ozo::send_data_frame(), and ozo::type_oid().

◆ size_of()

template<typename T >

constexpr size_type ozo::size_of ( const T & v )

constexpr

Returns size of object binary representation in bytes.

This function returns binary representation size of the object is used for the PostgreSQL binary protocol.

Parameters

v	— object to examine

Returns: ozo::size_type — size of object in bytes if object is not #Nullable or not in null state.; ozo::null_state_size — for #Nullable object in null state.